Register your app with Microsoft Entra
For your app to access user data from Microsoft Graph, you need to authenticate users using the Microsoft identity platform. In this unit, you learn how to register your app with Microsoft Entra.
Understand the role of Microsoft identity platform
Microsoft Graph is protected by the Microsoft identity platform, which uses OAuth access tokens to verify that an app is authorized to call Microsoft Graph. When you build your app to retrieve Microsoft Graph data, users can sign into your app by using their existing Microsoft 365 account. This capability frees you from having to implement authentication in your app and maintain users' credentials. It also benefits users because they won't need to use yet another credential to work with your app.
For more information about the Microsoft identity platform, review the following article: What is the Microsoft identity platform?.
Understand access tokens
To access Microsoft Graph, an application makes an authentication request to the Microsoft identity platform to get an access token. The app can then use the access token to call the API. Access tokens that the Microsoft identity platform issues contain claims which are details about the application or the user.
Web APIs that are secured by the Microsoft identity platform, such as Microsoft Graph, use the claims to validate the caller and to ensure that the caller has the proper privileges to perform the operation they're requesting.
The caller should treat access tokens as opaque strings because the contents of the token are intended for the API only. When calling Microsoft Graph, always protect access tokens by transmitting them over a secure channel that uses transport layer security (TLS).
The following example shows a Microsoft identity platform access token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
Access tokens are a kind of security token that the Microsoft identity platform provides. They're short-lived but with variable default lifetimes.
To call Microsoft Graph, the app makes an authorization request by attaching the access token as a Bearer token to the Authorization header in an HTTP request. For example, the following call returns the profile information of the signed-in user (the access token has been shortened for readability):
GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
Microsoft Entra app registration
Before your app can get an access token from the Microsoft identity platform, it must be registered in the Microsoft Entra admin center. Registration integrates your app with the Microsoft identity platform and establishes the information that it uses to get tokens, including:
- Application ID: A unique identifier assigned by the Microsoft identity platform.
- Redirect URI/URL: One or more endpoints at which your app receives responses from the Microsoft identity platform. (For native and mobile apps, the URI is assigned by the Microsoft identity platform.)
- Client secret: A password that your app uses to authenticate with the Microsoft identity platform. You can optionally use a certificate or a federated identity credential. This property isn't required for public clients like native, mobile and single page applications.
Microsoft 365 subscription requirements
To register your app, you need:
- An Azure account that has an active subscription.
- The Azure account must have permission to manage applications in Microsoft Entra ID. The required permissions are included in any of the following Microsoft Entra roles:
- Application administrator
- Application developer
- Cloud application administrator
Register your app using Teams Toolkit
The following article explains the manual process to register your app manually in the Microsoft Entra admin center: Register an application with the Microsoft identity platform.
Instead of registering your app manually in the Microsoft Entra admin center, you can use Teams Toolkit to provision Azure resources for your app, including your Microsoft Entra app registration. Teams Toolkit integrates with Azure and the Microsoft 365 cloud, including Azure Resource Manager, which enables you to provision Azure resources that your application needs for your solution. This can be done using the Teams Toolkit extensions in Visual Studio Code and Visual Studio, or using the TeamsFx CLI.
aadApp/create
To configure your app to be registered with Microsoft Entra during the provision stage, ensure the aadApp/create action is defined in your teamsapp.yml/teamsapp.local.yml configuration files.
This action will create a new Microsoft Entra app to authenticate users if the environment variable that stores clientId is empty.
Syntax:
- uses: aadApp/create
with:
name: <your-application-name> # Required. when you run aadApp/update, the Microsoft Entra app name will be updated based on the definition in manifest. If you don't want to change the name, make sure the name in Microsoft Entra manifest is the same with the name defined here.
generateClientSecret: true # Required. If the value is false, the action will not generate client secret for you
signInAudience: "AzureADMyOrg" # Required. Specifies what Microsoft accounts are supported for the current application. Supported values are: `AzureADMyOrg`, `AzureADMultipleOrgs`, `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`.
writeToEnvironmentFile: # Write the information of created resources into environment file for the specified environment variable(s).
clientId: <your-preferred-env-var-name> # Required. The client (application) ID of Microsoft Entra application. The action will refer the environment variable defined here to determine whether to create a new Microsoft Entra app.
clientSecret: <your-preferred-env-var-name> # Required when `generateClientSecret` is `true`. The action will refer the environment variable defined here to determine whether to create a new client secret. It's recommended to add `SECRET_` prefix to the environment variable name so it will be stored to the .env.{envName}.user environment file.
objectId: <your-preferred-env-var-name> # Required. The object ID of Microsoft Entra application
tenantId: <your-preferred-env-var-name> # Optional. The tenant ID of Microsoft Entra tenant
authority: <your-preferred-env-var-name> # Optional. The Microsoft Entra authority
authorityHost: <your-preferred-env-var-name> # Optional. The host name of Microsoft Entra authority
aadApp/Update
Additionally, define the aadApp/update action, which will update your Microsoft Entra app based on details defined in your Microsoft Entra app manifest. It will refer to the id property in your Microsoft Entra app manifest to determine which Microsoft Entra app to update.
Syntax:
- uses: aadApp/update
with:
manifestPath: ./aad.manifest.json # Required. Relative path to this file. Environment variables in manifest will be replaced before apply to Microsoft Entra app.
outputFilePath : ./build/aad.manifest.${{TEAMSFX_ENV}}.json # Required. Relative path to teamsfx folder. This action will output the final Microsoft Entra manifest used to update Microsoft Entra app to this path.
Provision resources for your app
When you trigger the Provision command in Teams Toolkit or TeamsFx CLI, Teams Toolkit will perform the actions defined in your configuration file, such as registering your app with Microsoft Entra ID.