Enable SSO for API-based message extensions

Single sign-on (SSO) authentication method for API based message extension uses an app user's Teams identity to provide them with access to your app. A user who has signed into Teams doesn't need to sign in again to your app within the Teams environment. Microsoft Entra SSO enables the app to silently obtain a user token that is issued for its resource by Microsoft Entra. The app can then authenticate this token and retrieve the user profile information without the user's consent.

Prerequisites

Before you start, ensure you have the following:

• An Azure account with an active subscription.
• Basic familiarity with Microsoft Entra ID and Teams app development.

The following image shows how SSO works when a Teams app user attempts to access API-based message extension app:

• The user invokes the API-based message extension app within Teams and invokes a command that requires authentication.
• The app sends a request to the Teams backend service with the app ID and the required scope (access_as_user).
• The Teams backend service checks if the user consented to the app and the scope. If not, it shows a consent screen to the user.
• If the user consents, Microsoft Entra generates an access token for the user and the app, and sends it to the app in the authorization header of the request.
• The app validates the token and extracts the user information from the token, such as the name, email, and object ID.
• After successful authentication, user is granted access to the API-based message extension.

To enable SSO authentication for API-based message extension, follow these steps:

• Register a new app in Microsoft Entra ID.
• Configure scope for access token.
• Authenticate token.
• Update app manifest.

Register a new app in Microsoft Entra ID

1. Open the Azure portal on your web browser.

2. Select the App registrations icon.

   

   The App registrations page appears.

3. Select + New registration icon.

   

   The Register an application page appears.

4. Enter the name of your app that you want to be displayed to the app user. You can change the name at a later stage if you want to.

   

5. Select the type of user account that can access your app. You can select from single or multitenant options in organizational directories or restrict the access to personal Microsoft accounts only.

   Options for supported account types

   Option	Select this to...
   Accounts in this organizational directory only (Microsoft only - Single tenant)	Build an application for use only by users (or guests) in your tenant. Often called custom app built for your org (LOB app), this app is a single-tenant application in the Microsoft identity platform.
   Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)	Let users in any Microsoft Entra tenant use your application. This option is appropriate if, for example, you're building a SaaS application, and you intend to make it available to multiple organizations. This type of app is known as a multitenant application in the Microsoft identity platform.
   Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (for example, Skype, Xbox)	Target the widest set of customers. By selecting this option, you're registering a multitenant application that can support app users who have personal Microsoft accounts also.
   Personal Microsoft accounts only	Build an application only for users who have personal Microsoft accounts.

   Note

   You don't need to enter Redirect URI for enabling SSO for an API-based message extension app.

6. Select Register. A message pops up on the browser stating that the app was created.

   

   The page with app ID and other app details is displayed.

   

7. Note and save the app ID from Application (client) ID to update the app manifest later.

   Your app is registered in Microsoft Entra ID. You now have the app ID for your API-based message extension app.

Configure scope for access token

After you've created a new app registration, configure scope (permission) options for sending access token to Teams client, and authorizing trusted client applications to enable SSO.

To configure scope and authorize trusted client applications, you must:

• Add App ID URI: Configure scope (permission) options for your app. Expose a web API and configure the app ID URI.
• Configure API scope: Define scope for the API, and the users who can consent for a scope. You can let only admins provide consent for higher-privileged permissions.
• Configure authorized client application: Create authorized client IDs for applications that you want to preauthorize. It allows the app user to access the app scopes (permissions) you've configured, without requiring any further consent. Preauthorize only those client applications you trust as your app users don't have the opportunity to decline consent.

App ID URI

1. Select Manage > Expose an API from the left pane.

   The Expose an API page appears.

2. Select Add to generate app ID URI in the form of api://{AppID}.

   

   The section for setting app ID URI appears.

3. Enter the Application ID URI in the format explained here.

   

   • The Application ID URI is prefilled with app ID (GUID) in the format api://{AppID}.
   • The app ID URI format must be: api://fully-qualified-domain-name.com/{AppID}.
   • Insert the fully-qualified-domain-name.com between api:// and {AppID} (which is, GUID). For example, api://example.com/{AppID}.

   Important

   • If you're building a standalone bot, enter the app ID URI as api://botid-{YourBotId}. Here, {YourBotId} is your Microsoft Entra app ID.
   • If you're building an app with a bot, a message extension, and a tab, enter the app ID URI as api://fully-qualified-domain-name.com/botid-{YourClientId}, where {YourClientId} is your bot app ID.
   • If you're building an app with a message extension or tab capabilities without the bot, enter the app ID URI as api://fully-qualified-domain-name.com/{YourClientId}, where {YourClientId} is your Microsoft Entra app ID.
   • Application ID URI for app with multiple capabilities: If you're building an API-based message extension, enter the app ID URI as api://fully-qualified-domain-name.com/{YourClientId}, where {YourClientId} is your Microsoft Entra app ID.
   • Format for domain name: Use only lower-case letters for domain name.

4. Select Save.

   A message pops up on the browser stating that the app ID URI was updated.

   

   The app ID URI displays on the page.

   

5. Note and save the app ID URI to update the app manifest later.

Configure API scope

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

   

   The Add a scope page appears.

2. Enter the details for configuring scope.

   

   1. Enter the scope name. This field is mandatory.
   2. Select the user who can give consent for this scope. The default option is Admins only.
   3. Enter the Admin consent display name. This field is mandatory.
   4. Enter the description for admin consent. This field is mandatory.
   5. Enter the User consent display name.
   6. Enter the description for user consent description.
   7. Select the Enabled option for state.
   8. Select Add scope.

   A message pops up on the browser stating that the scope was added.

   

   The new scope you defined displays on the page.

   

Configure authorized client application

1. Move through the Expose an API page to the Authorized client application section and select + Add a client application.

   

   The Add a client application page appears.

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

   

   Note

   The Microsoft 365 client IDs for mobile, desktop, and web apps for Teams are the actual IDs that you must add.

   1. Select one of the following client IDs:

      Use client ID	For authorizing...
      1fec8e78-bce4-4aaf-ab1b-5451cc387264	Teams mobile or desktop app
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Teams web app

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

   3. Select Add application.

      A message pops up on the browser stating that the authorized client app was added.

      

      The authorized app's client ID displays on the page.

      

You've successfully configured app scope, permissions, and client applications. Ensure that you note and save the app ID URI. Next, you configure the access token version.

Authenticate token

When the message extension calls the API during authentication, it receives a request with the user’s access token. The message extension then adds the token in the authorization header of the outgoing HTTP request. The header format is Authorization: Bearer <token_value>. For example, when a message extension makes an API call to a service that requires authentication. The extension constructs an HTTP request as follows:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

After the API-based message extension gets a request header with token, perform the following steps:

• Authenticate: Verify the token for the audience, scope, issuer, and signature claims to check if the token is for your app. For more claims, see ID token claims.

  The following example shows the JSON Web Token (JWT) with a header and response:

  • Token V2
  • Token V1

  {
  "typ": "JWT",
  "rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
  "alg": "RS256",
  "kid": "q-23falevZhhD3hm9CQbkP5MQyU"
  }.{
    "aud": "00000002-0000-0000-c000-000000000000",
    "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
    "iat": 1712509315,
    "nbf": 1712509315,
    "exp": 1712513961,
    "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
    "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
    "azpacr": "0",
    "name": "John Doe",
    "oid": "00000000-0000-0000-0000-000000000000",
    "preferred_username": "john.doe@contoso.com",
    "rh": "I",
    "scp": "access_as_user",
    "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
    "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
    "uti": "h7DMQwSPAEeiEe62JJUGAA",
    "ver": "2.0"
    }
  

• Use the token: Extract the user information from the token, such as name, email, and object ID and use the token to call the message extension app's own API. For more information on claims reference with details on the claims included in access tokens, see access token claims.

Update app manifest

Update the following properties in the app manifest file:

• webApplicationInfo: The webApplicationInfo property is used to enable SSO for your app to help app users access your API-based message extension app seamlessly. The app ID URI that you registered in Microsoft Entra ID is configured with the scope of the API you exposed. For more information, see webApplicationInfo.

    

• microsoftEntraConfiguration: Enables SSO authentication for your app. Configure the supportsSingleSignOn property to true to support SSO and reduce the need for multiple authentications. If the property is set to false or is left empty, the user can't upload the app to Teams and the app fails validation.

To configure app manifest:

1. Open the API-based message extension app.

2. Open the app manifest folder.

   Note

   • The app manifest folder should be at the root of your app folder. For more information, see create a Microsoft Teams app package.
   • For more information on learning how to create a manifest.json, see the app manifest schema.

3. Open the manifest.json file.

4. Add the following code snippet into the webApplicationInfo section of your app manifest file:

   "webApplicationInfo":
   {
   "id": "{Microsoft Entra AppId}",
   "resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
   }
   

   where,

   • {Microsoft Entra AppId} is the app ID you created when you registered your app in Microsoft Entra ID. It's the GUID.
   • api://subdomain.example.com/{Microsoft Entra AppId} is the app ID URI that you registered when creating scope in Microsoft Entra ID.

5. Add the following code snippet into the composeExtensions section of your app manifest file:

   "authorization": {
     "authType": "microsoftEntra",
     “microsoftEntraConfiguration”: {
       “supportsSingleSignOn”: true
     }
   },
   

6. Save the app manifest file.

Congratulations! You've enabled SSO for your API-based message extensions.

See also

• Create API-based message extension
• API key authentication
• Authenticate users in Microsoft Teams