Extend tab app with Microsoft Graph permissions and scopes

發行項
04/06/2023

You can extend your tab app by using Microsoft Graph to allow users additional permissions, such as to view app user profile, to read mail, and more. Your app must ask for specific permission scopes to obtain the access tokens on app user's consent.

Graph scopes, such as User.Read or Mail.Read, lets you specify how your app accesses a Teams user's account. You need to specify your scopes in the authorization request.

In this section, you'll learn to:

Configure API permissions in Azure AD
Configure authentication for different platforms
Acquire access token for MS Graph

Configure API permissions in Azure AD

You can configure additional Graph scopes in Azure AD for your app. These are delegated permissions, which are used by apps that require signed-in access. A signed-in app user or administrator must consent to them. Your tab app can consent on behalf of the signed-in user when it calls Microsoft Graph.

To configure API permissions

Open the app you registered in the Azure portal.
Select Manage > API permissions from the left pane.

The API permissions page appears.
Select + Add a permission to add Microsoft Graph API permissions.

The Request API permissions page appears.
Select Microsoft Graph.

The options for Graph permissions display.
Select Delegated permissions to view the list of permissions.
Select relevant permissions for your app, and then select Add permissions.

You can also enter the permission name in the search box to find it.

A message pops up on the browser stating that the permissions were updated.

The added permissions are displayed in the API permissions page.

You've configured your app with Microsoft Graph permissions.

Configure authentication for different platforms

Depending on the platform or device where you want to target your app, additional configuration may be required such as redirect URIs, specific authentication settings, or details specific to the platform.

Note

If your tab app hasn't been granted IT admin consent, app users have to provide consent the first time they use your app on a different platform.
Implicit grant isn't required if SSO is enabled on a tab app.

You can configure authentication for multiple platforms as long as the URL is unique.

To configure authentication for a platform

Open the app you registered in the Azure portal.
Select Manage > Authentication from the left pane.

The Platform configurations page appears.
Select + Add a platform.

The Configure platforms page appears.
Select the platform that you want to configure for your tab app. You can choose the platform type from web or Single-page application.

You can configure multiple platforms for a particular platform type. Ensure that the redirect URI is unique for every platform you configure.

The Configure Web page appears.

Note

The configurations will be different based on the platform you select.
Enter the configuration details for the platform.
1. Enter the redirect URI. The URI should be unique.
2. Enter the front-channel logout URL.
3. Select the tokens you want Azure AD to send for your app.
Select Configure.

The platform is configured and displayed in the Platform configurations page.

Acquire access token for MS Graph

You'll need to acquire access token for Microsoft Graph. You can do so by using Azure AD on-behalf-of (OBO) flow.

The current implementation for SSO grants consent for only user-level permissions that aren't usable for making Graph calls. To get the permissions (scopes) needed to make a Graph call, SSO apps must implement a custom web service to exchange the token received from the Teams JavaScript library for a token that includes the needed scopes. You can use Microsoft Authentication Library (MSAL) for fetching the token from the client side.

After you've configured Graph permissions in Azure AD:

Get the token ID from Teams client
Exchange the token ID with the server-side token

Get the token ID from Teams client

The following is an example for calling token ID from Teams client:

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

Exchange the token ID with the server-side token

The following is an example of OBO flow to fetch access token from the Teams client using MSAL:

C#
Node.js

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

If you need to access Microsoft Graph data, configure your server-side code to:

Validate the access token. For more information, see Validate the access token.
Initiate the OAuth 2.0 OBO flow with a call to the Microsoft identity platform that includes the access token, some metadata about the user, and the credentials of the tab app (its app ID and client secret). The Microsoft identity platform will return a new access token that can be used to access Microsoft Graph.
Get data from Microsoft Graph by using the new token.
Use token cache serialization in MSAL.NET to cache the new access token for multiple, if required.

Important

As a best practice for security, always use the server-side code to make Microsoft Graph calls or other calls that require passing an access token. You must not return the OBO token to the client because it enables the client to make direct calls to Microsoft Graph. This helps protect the token from being intercepted or leaked.
Don’t use notifySuccess result to return the token information to the parent page. Use localStorage to save the token and pass the item key via notifySuccess.

Known limitations

Tenant admin consent: A simple way of consenting on behalf of an organization as a tenant admin is by getting consent from admin.

You can ask for consent using the Auth API. Another approach for getting Graph scopes is to present a consent dialog using our existing third party OAuth provider authentication approach. This approach involves popping up an Azure AD consent dialog box.

To ask for additional consent using the Auth API, follow these steps:

The token retrieved using getAuthToken() must be exchanged on the server-side using Azure AD on-behalf-of flow to get access to those other Graph APIs. Ensure you use the v2 Graph endpoint for this exchange.
If the exchange fails, Azure AD returns an invalid grant exception. It usually responds with one of the two error messages, invalid_grant or interaction_required.
When the exchange fails, you must ask for consent. Use the user interface (UI) to ask the app user to grant other consent. This UI must include a button that triggers an Azure AD consent dialog using Silent authentication.
When asking for more consent from Azure AD, you must include prompt=consent in your query-string-parameter to Azure AD, otherwise Azure AD wouldn't ask for other scopes.
- Instead of ?scope={scopes}, use ?prompt=consent&scope={scopes}
- Ensure that {scopes} includes all the scopes you're prompting the user for, for example, Mail.Read or User.Read.
To handle incremental consent for tab app, see incremental and dynamic user consent.
After the app user has granted more permissions, retry the OBO flow to get access to these other APIs.

Code sample

Sample name	Description	C#	Node.js
Tabs Azure AD SSO	Microsoft Teams sample app for tabs Azure AD SSO, which uses OBO flow to call Graph APIs.	View	View