Add user authorization by using federated identity credential

The Azure AI Bot Service helps you create agents that can access online resources that require user authentication. Your agent doesn't need to handle authentication tokens because Azure manages this process. Azure uses OAuth 2.0 to generate a token based on each user's credentials. Your agent uses the token generated by Azure to access those resources. By using this approach, the user doesn't need to provide an ID and password to the agent to access a secured resource but only needs to provide them to a trusted identity provider.

Important

Web Chat and Direct Line considerations: To reduce security risks when connecting to an agent by using the Web Chat control, use Direct Line with enhanced authentication enabled. For more information, see Direct Line enhanced authentication.

To set up OAuth on an agent, register an Azure Bot if you haven't done so already.

Important

When you register an agent in Azure, the agent gets assigned a Microsoft Entra ID application. However, this application secures channel-to-bot access. You need an extra Microsoft Entra ID application for each external secured resource you want the agent to access on behalf of the user.

Microsoft Entra ID identity service

Microsoft Entra ID is a cloud identity service that you can use to build applications that securely sign in users by using industry standard protocols like OAuth 2.0.

Use one of these three identity services:

  1. Microsoft identity platform (v2.0): Also known as the Azure Active Directory v2 endpoint, which is an evolution of the Azure AD platform (v1.0).
  2. Federated Credentials: Also known as AAD v2 with Federated Credentials.
  3. Certificates: Also known as AAD v2 with Certificates.

By using these services, you can build applications that sign in to all Microsoft identity providers and get tokens to call Microsoft APIs, such as Microsoft Graph, or other APIs that developers have built.

Create the Microsoft Entra ID identity provider

This section shows how to create a Microsoft Entra ID identity provider that uses OAuth 2.0 to authenticate the agent for Microsoft Graph.

Tip

You need to create and register the Microsoft Entra ID application in a tenant where you can consent to delegate permissions requested by an application.

Create an app registration

  1. Open the Microsoft Entra ID panel in the Azure portal. If you're not in the correct tenant, select Switch directory to switch to the correct tenant. For information on how to create a tenant, see Access the portal and create a tenant.

  2. Open the App registrations panel.

  3. Set up the app registration:

    1. For Teams SSO, open the existing app registration for the agent/Azure Bot:

      1. On the Authentication pane, if you don't see a Web platform, select Add a platform.

      2. Select Web.

      3. Enter the Redirect URI from the table in the next step.

      4. Select Configure.

        Screenshot of Add Redirect URI page in Azure portal.

    2. For other channels or OAuth:

      1. In the App registrations panel, select New registration.

      2. Fill in the required fields and create the app registration:

        1. Name your application.

        2. Select the Supported account types for your application. Select Single Tenant.

        3. For the Redirect URI, select Web and set the URL to one of the supported OAuth redirect URLs:

          Data residency Cloud OAuth URL OAuth Redirect URL
          None Public https://token.botframework.com https://token.botframework.com/.auth/web/redirect
          Europe Public https://europe.token.botframework.com https://europe.token.botframework.com/.auth/web/redirect
          United States Public https://unitedstates.token.botframework.com https://unitedstates.token.botframework.com/.auth/web/redirect
          India Public https://india.token.botframework.com https://india.token.botframework.com/.auth/web/redirect
          None Azure Government https://token.botframework.azure.us https://token.botframework.azure.us/.auth/web/redirect
          None Azure operated by 21Vianet https://token.botframework.azure.cn https://token.botframework.azure.cn/.auth/web/redirect

        4. Select Register. Once the app registration is created, Azure displays the Overview page for the app.

        5. Record the Application (client) ID value. You use this value later as the client ID when you create the connection string and register the Microsoft Entra ID provider with the agent registration.

        6. Record the Directory (tenant) ID value. You use this value to register this provider application with your bot.

Add credentials for your app

  1. In the navigation pane, select Certificates & secrets to add credentials for your application.

  2. Under Federated Credentials, select Add Credentials.

    Screenshot of Entra Federated Identity Credentials panel.

  3. On Add Credentials, choose the Federated credential scenario as Other Issuer.

    Screenshot of Entra Federated Identity Credentials scenario selection page.

  4. Enter values in the required fields and review and update settings:

    1. Provide information under Connect your account.

      Screenshot of Entra Federated Identity Credentials Connect your account section.

    2. Issuer: https://login.microsoftonline.com/{customer-tenant-ID}/v2.0.

    3. Subject Identifier: /eid1/c/pub/t/{base64 encoded customer tenant ID}/a/{base64 encoded 1-P app client ID}/{unique-identifier-for-projected-identity}.

      The following table contains Base64url encoded byte-array representations of supported first-party application IDs. Use the value that represents the first-party app.

      Encoded Value Description
      9ExAW52n_ky4ZiS_jhpJIQ Base64url encoded of Bot Service Token Store
      ND1y8_Vv60yhSNmdzSUR_A Base64url encoded of Bot Framework Dev Portal

      The following table contains Base64url encoded byte-array representation of some supported tenant IDs. Use the value that represents the tenant of your app.

      Encoded Value Description
      v4j5cvGGr0GRqy180BHbRw Base64url encoded MSIT tenant ID (aaaabbbb-0000-cccc-1111-dddd2222eeee)
      PwFflyR_6Een06vEdSvzRg Base64url encoded PME tenant ID (bbbbcccc-1111-dddd-2222-eeee3333ffff)
      6q7FzcUVtk2wefyt0lBdwg Base64url encoded Torus tenant ID (ccccdddd-2222-eeee-3333-ffff4444aaaa)
      IRngM2RNjE-gVVva_9XjPQ Base64url encoded AME tenant ID (ddddeeee-3333-ffff-4444-aaaa5555bbbb)

      The primary identity service owners calculate this value once and provide it to their consumers.

    4. Unique-identifier-for-projected-identity: A unique identifier, of your choosing, that you use in the OAuth Connection Setting on the Azure Bot.

    5. Name: Name of your choice, such as "agent oauth".

    6. Audience: api://AzureADTokenExchange (Use Cloud specific values).

  5. Provide information under Credential details.

    Screenshot of Entra Federated Identity Credential details page.

  6. Select Add to add the credential.

Expose an API endpoint

  1. Select Expose an API in the left rail.

    • For an Azure Bot Service Bot: The default api://{appid} is suitable.
    • For a Teams bot: This format is REQUIRED api://botid-{appid}.

  2. Add a scope:

    1. Select Add a scope in the Scopes defined by this API section.

      Screenshot of Add a Scope option in Azure portal.

    2. Enter the details for configuring scope.

      Screenshot of Scope Detail configuration in Azure portal.

    3. Enter the scope name defaultScopes.

    4. Select the user who can give consent for this scope. The default option is Admins only.

    5. Enter the Admin consent display name.

    6. Enter the description for admin consent.

    7. Enter the User consent display name.

    8. Enter the user consent description.

    9. Select the Enabled option for state.

    10. Select Add scope.

  3. For Teams only, configure an authorized client application:

    1. Select Add a client application.

      Screenshot of Add a client application panel in Azure portal.

    2. Enter the appropriate Microsoft 365 client ID for the applications that you want to authorize for your app's web application.

      Screenshot of Add a clientId field in Azure portal.

    3. Select one of the following client IDs:

      Client ID to use App type to authorize
      1fec8e78-bce4-4aaf-ab1b-5451cc387264 Teams mobile or desktop application
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Teams web application
      4765445b-32c6-49b0-83e6-1d93765276ca Microsoft 365 web application
      0ec893e0-5785-4de6-99da-4ed124e5296c Microsoft 365 desktop application
      d3590ed6-52b3-4102-aeff-aad2292ab01c Microsoft 365 mobile application/Outlook desktop application
      bc59ab01-8403-45c6-8796-ac3ef710b3e3 Outlook web application
      27922004-5251-4030-b22d-91ecd9a37ea4 Outlook mobile application

    4. Select the application ID URI you created for your app in Authorized scopes to add the scope to the web API you exposed.

    5. Select Add application.

      Screenshot of Client App Added confirmation in Azure portal.

Set API permissions for the app

  1. In the navigation pane, select API permissions to open the API permissions panel. Set the API permissions for the app:

  2. Select Add a permission to show the Request API permissions pane.

  3. For this sample, select Microsoft APIs and Microsoft Graph.

  4. Choose Delegated permissions and make sure the permissions you need are selected. This sample requires User.Read permissions.

    Tip

    Avoid permissions marked as ADMIN CONSENT REQUIRED because they require both a user and a tenant admin to sign in.

You now have a OAuth application configured.

Note

You assign the Application (client) ID when you create the connection string and register the identity provider with the agent registration. See next section.

Create an OAuth connection on the Azure Bot

Next, register your identity provider with your agent:

Note

Single Tenant Microsoft Entra Application supports only AAD v2 with Federated Credentials service provider. Support for multitenant apps is coming soon.

  1. Open your bot's Azure Bot resource page in the Azure portal.

  2. Select Settings, and then select Configuration.

  3. Select the OAuth Connection Settings button near the bottom of the page.

  4. Fill in the form as follows:

    1. Name. Enter a name for your connection. Use it in your agent code.

    2. Service Provider. Select AAD v2 with Federated Credentials to display service provider specific fields.

    3. Client id. Enter the application (client) ID you recorded for your Microsoft Entra ID identity provider(Only Single Tenant Supported).

    4. Unique Identifier. Enter the unique identifier you recorded for your Microsoft Entra ID identity provider while creating federated credentials.

    5. Token Exchange URL. For Teams SSO, enter the API endpoint created earlier: api://botid-{appId}. Otherwise, leave the field blank.

    6. Tenant ID. Enter the directory (tenant) ID that you recorded earlier for your Microsoft Entra ID app or common depending on the supported account types selected when you created the Azure DD app. To decide which value to assign, follow these criteria:

      • When creating the Microsoft Entra ID app, if you selected Accounts in this organizational directory only (Microsoft only - Single tenant), enter the tenant ID you recorded earlier for the Microsoft Entra ID app.
      • However, if you selected Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant and personal Microsoft accounts e.g. Xbox, Outlook.com) or Accounts in any organizational directory(Microsoft Entra ID directory - Multitenant), enter common instead of a tenant ID. Otherwise, the Microsoft Entra ID app verifies through the tenant whose ID you selected and excludes personal Microsoft accounts.

      Note

      This tenant is associated with the users who can be authenticated. For more information, see Create a tenant in Microsoft Entra ID.

    7. For Scopes, enter the names of the permission you chose from the application registration. For testing purposes, you can just enter: User.Read. If you need to use this token for OBO to another service (an exchangeable token), use api://botid-{{appId}}/defaultScopes.

    Note

    For Microsoft Entra ID, the Scopes field takes a case-sensitive, space-separated list of values.

  5. Select Save.

Test your connection

  1. Select the connection entry to open the connection you created.

  2. Select Test Connection at the top of the Service Provider Connection Setting pane.

  3. The first time, this action opens a new browser tab that lists the permissions your app is requesting and prompts you to accept.

  4. Select Accept.

  5. This action redirects you to a Test Connection to your-connection-name Succeeded page, where your-connection-succeeded is your specific connection name.

  6. For exchangeable tokens only:

    1. Copy the JSON Web Token (JWT) token.

    2. Decode the token by using https://jwt.io/.

    3. The aud claim value should begin with api://.

  • Last updated on