Configure Your Microsoft Entra ID (Azure AD) OAuth 2.0

This guide walks you through registering a new application in Microsoft Entra ID (formerly Azure Active Directory) to obtain the required OAuth 2.0 credentials: Client ID, Client Secret, and Token URL.

Callback URL (Redirect URI):

Use the following URL when configuring your application’s redirect settings:

https://<domain>.cloud.stackgen.com/auth/callback

Steps to Configure your Microsoft Entra ID (Azure AD) OAuth 2.0

Access the Microsoft Entra Admin Center

1. Go to the Microsoft Entra Admin Center and sign in with an account that has permissions to manage applications.
2. In the left navigation pane, click App registrations.

Register a New Application

1. Click + New registration at the top of the App registrations page.
2. On the Register an application page, enter the following details:
   • Name: Enter a descriptive name for your application (e.g., Acme StackGen Integration).
   • Supported account types: Select the option that aligns with your organization's needs (e.g., Accounts in this organizational directory only).
3. For now, leave the Redirect URI field empty.
4. Click Register to create the application.

Retrieve the Client ID (Application ID)

After registering your application, you'll be directed to its Overview page.

• Look for the value labeled Application (client) ID, this is your OAuth 2.0 Client ID.
• Copy the GUID shown and store it somewhere safe, as you’ll need it when configuring authentication in StackGen.

Configure the Callback URL (Redirect URI)

The Callback URL tells Microsoft Entra ID where to send authentication responses after login.

If you haven’t already set this up:

1. In your application's left navigation menu, go to Authentication.
2. Click + Add a platform and select Web.
3. Under Redirect URIs, enter your redirect URL, for example:

   https://acme.cloud.stackgen.com/auth/callback

4. Click Configure to save your changes.

Generate the Client Secret

The Client Secret is a crucial credential your application uses to authenticate with Microsoft Entra ID.

1. In your application's left sidebar, navigate to Certificates & secrets.

2. Under the Client secrets section, click + New client secret.

3. In the dialog that appears:

   • Description: Enter a descriptive name for the secret (e.g., StackGen Secret).
   • Expires: Choose an appropriate expiration period. (Remember to renew the secret before it expires.)

4. Click Add.

   warning

   • Immediately copy the Value of the new secret. This value is displayed only once, right after creation.
   • Do not confuse the Value with the Secret ID.
   • Store it securely, as this is your OAuth 2.0 Client Secret. If you lose this value, you will need to generate a new client secret.

Locate the Token URL (OAuth 2.0 Token Endpoint)

The Token URL is the endpoint used by your application to exchange an authorization code for an access token.

To find your Token URL:

1. Return to your application's Overview page in Microsoft Entra ID.

2. At the top, click Endpoints.

3. A pane will appear listing several service URLs.

4. Locate and copy the URL labeled OAuth 2.0 token endpoint (v1).

   note

   Microsoft Entra ID provides two versions of token endpoints (v1.0 and v2.0). For StackGen integration, make sure you use the v1.0 endpoint:

   Endpoint Name	Example Format
   OAuth 2.0 token endpoint (v1)	https://login.microsoftonline.com/{tenant-id}/oauth2/token

Copy this URL and store it safely as this is the Token URL that your application will use.

Configuring Group Claims

For detailed information, see the Microsoft Docs: Configure group claims and app roles.

We recommend creating dedicated groups for StackGen platform access. StackGen defines three default roles:

• Admin
• DevOps
• Developer

Create these corresponding roles in Microsoft Entra ID, so you can map StackGen’s roles to your users or groups. These roles can be assigned to individuals or groups as required, giving appropriate access to your users on the StackGen platform.

For more details on roles and their permissions, see the StackGen Documentation.

Update Token Configuration

To configure Group Claims in Token Configuration, follow these steps:

1. Navigate to the Token configuration section for your app registration in Microsoft Entra ID.
2. Click Add groups Claim.
3. In the dialog:
   • Check Group ID to include group identifiers in tokens.
   • Check Emit groups as role claims to emit groups in the roles claim format.
4. Save your Settings.

After saving, verify the configuration in the app registration's Manifest section. Look for the optionalClaims block or accessTokens[].additionalProperties = [“cloud_displayname”,”emit_as_roles”] to ensure the correct settings, specifically that accessToken, idToken, and saml2Token each have an entry similar to:

    "optionalClaims": {
    "accessToken": [
            {
                "name": "groups",
                "essential": false,
                "source": null,
                "additionalProperties": ["cloud_displayname", "emit_as_roles"]
            }
        ],
        "idToken": [
            {
                "name": "groups",
                "essential": false,
                "source": null,
                "additionalProperties": ["cloud_displayname", "emit_as_roles"]
            }
        ],
        "saml2Token": [
            {
                "name": "groups",
                "essential": false,
                "source": null,
                "additionalProperties": ["cloud_displayname", "emit_as_roles"]
            }
        ]
    }

This ensures group information will be included in tokens as expected for StackGen integration.

Summary of Required Credentials

Please provide the following three values to your StackGen Support Representative to complete the OAuth 2.0 configuration:

Credential	Label in Microsoft Entra ID	Location
Client ID	Application (client) ID	Overview page
Client Secret	Value	Certificates & secrets page (copied on creation)
Token URL	OAuth 2.0 token endpoint (v1)	Endpoints pane