Note

Access to this page requires authorization. You can try signing in or .

Access to this page requires authorization. You can try .

Enable OAuth authentication for API based message extension

Integrating Open Authorization (OAuth) 2.0 into your Teams API based message extension app ensures a secure method for accessing user data from third-party apps without exposing user credentials. This protocol allows you to grant access solely to the specific data required, and the user must consent before the app can access their data. It's beneficial for apps that need to access individual items for a user.

By using OAuth 2.0, your client app can obtain authorized access to protected resources like web APIs. OAuth is designed to work with Hypertext Transfer Protocol (HTTP). It uses access tokens to prove app user's identity and allow interaction with another service on their behalf.


Implement OAuth

When a user tries to use a message action on a new Teams app with OAuth, Teams makes an invoke request to check if there's a valid access token using the app ID. If a valid token is available, Teams sends this bearer token with the HTTP request to resource API.

If there is no valid token available, Teams Client starts the sign-in process and shows the OAuth card in a pop-up. The user signs into the third-party service and approves the requested access. The third-party server sends an authorization code to the callback URL on the Teams Graph Service (TGS), which then exchanges the code for a token.

To enable OAuth for your API based message extension:

Ensure prerequisites

Before you start, you must have:

  • A Microsoft Teams app with API Message Extensions or Plugins.
  • An OAuth 2.0 client ID and client secret from the third-party authorization server.
  • When setting up your OAuth app with a third-party authentication provider, ensure that you add https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect to the list of allowed redirect endpoints. These providers maintain a list of such endpoints to call for their app, making it crucial to include this URL to ensure seamless functionality.

Configure OAuth in Developer Portal

You can register OAuth client configuration for your API based message extension and Copilot plugins in Teams Developer Portal.

To register OAuth for your API based message extensions, follow these steps:

  1. Go to Teams Developer Portal.

  2. Select OAuth client registration.

  3. Select Register Client.

    👁 Screenshot shows the registerclient option to register oauth configuration id in Developer Portal for Teams.

  4. In the OAuth client registration page under App settings, update the following:

    👁 Screenshot shows the app seetings for Oauth configutraion in developer portal for Teams.

    1. Registration name: This is a unique name to describe your OAuth client registration.

    2. Base URL: Teams transmits the secret to URL endpoints that begin with the value in this field.

    3. Under Restrict usage by org, select any of the following:

      • My organization only

      • Any Microsoft 365 organization

        Option When to use Description
        My organization only When you develop your app in your tenant and test the app as a custom app or custom app built for your org. The API key is only usable within the tenant where the API is registered.
        Any Microsoft 365 organization After you've completed testing the app and want to enable the app across different tenants.
        Ensure that you update your target tenant to Any Microsoft 365 organization before submitting your app package to the Partner Center.

        👁 Image
        		 The API key can be used in other tenants after the app is available in the Teams Store.

    4. Under Restrict usage by app, select any of the following:

      • Any Teams app

      • Existing Teams app ID

        Option When to use Description
        Any Teams app When you develop your app in your tenant and test the app as a custom app or custom app built for your organization. The API key can be used with any Teams app. It's useful when custom app or custom app built for your organization have IDs generated after app upload.
        Existing Teams app ID After you've completed testing your app within your tenant as a custom app or custom app built for your organization.
        Update your API key registration and select Existing Teams app and input your app’s manifest ID.        		 The Existing Teams app option binds the API secret registration to your specific Teams app.

  5. Under OAuth settings, update the following:

    👁 Screenshots shows the OAuth settings required for oauth configuration ID in Developer Portal for Teams

    1. Client ID: The client ID is a unique identifier assigned to your app by the third-party authorization server.

    2. Client secret: The client secret is a confidential string known by the third-party authorization server.

    3. Authorization endpoint: The authorization endpoint is the URL where a user is redirected to sign-in and grant or deny access to your app. For example, https://login.example.com/authorize.

    4. Token endpoint: The token endpoint is the URL where your app exchanges the authorization code for an access token. For example, https://authorization-server.com/oauth/token.

    5. Refresh endpoint: By using the refresh endpoint URL, your app obtains a new access token without user interaction. For example, https://authorization-server.com/oauth/refresh. At times, the refresh endpoint might be the same as the token endpoint.

    6. Scope: [Optional] The scope defines the permissions your app requests from the user.

  6. Select Save.

    An OAuth client registration ID is generated.

    👁 Screenshot shows the OAuth client registration ID generated in Developer POrtal for Teams.

Add OAuth client registration ID in API based message extension

To update OAuth client registration ID in API based message extension, follow these steps:

  1. Go to Teams Developer Portal.

  2. From the left pane, select Apps.

  3. Select the message extension app that you've created.

  4. From the left pane under Configure, select App features > Message extension.

  5. Under Authentication and authorization, select OAuth and enter the OAuth client registration ID.

  6. Select Save.

    👁 Screenshot shows the OAuth to add the registration ID copied earlier to the message extension in Developer Portal for Teams.

Your OAuth client registration ID is now added to your API based message extension.

You've successfully configured OAuth for your API based messsage extension in Developer Portal. Next, you must update the app manifest for your app.

Update app manifest

Update your app manifest schema to include the new authentication type: oAuth and the oAuthConfigurationId you received from the Developer Portal.

The following code snippet is an example of app manifest update for configuring OAuth for your API based message extension:

{
 "composeExtensions": [
 {
 "composeExtensionType": "apiBased",
 "authorization":
 {
 "authType": "oAuth2.0",
 "oAuthConfiguration": {
 "oAuthConfigurationId": "sCVBX2udSXEtxo97behM1ReO8pJc4MdA"
 }
 },
 "apiSpecificationFile": "apiSpecFiles/repairs-openapi.json",
 "commands": [
 {
 "id": "listRepairs",
 "type": "query",
 "context": ["compose", "commandBox"],
 "title": "List all repairs",
 "description": "Returns a list of repairs with their details and images",
 "parameters": [
 {
 "name": "assignedTo",
 "title": "Assigned To",
 "description": "Filter repairs by who they're assigned to"
 }
 ],
 "apiResponseRenderingTemplateFile": "adaptiveCards/repairs.json"
 }
 ]
 }
 ]
}

Handle errors

Ensure that the OAuth implementation in your app can handle error cases, such as:

  • Token error cases: Missing token, expired token, or invalid token.

  • User login or permission error cases: User fails to log-in, the permission isn't granted, or user closes the dialog box.

  • If you encounter 401 or 403 error, ensure that you've:

    • Added all the necessary scopes for your app.
    • Entered all endpoints correctly.
    • Added https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect to the allowed redirect URLs.

Implementing OAuth 2.0 for API message extensions and plugins in Teams significantly enhances the security of your app. You can ensure secure data access and protection of user credentials.

See also

Feedback

Was this page helpful?

Additional resources

  • Last updated on