Configure Azure AD authentication - Azure App Service (2023)

This article shows you how to configure authentication for Azure App Service or Azure Functions so that your app signs in users with the Microsoft identity platform (Azure AD) as the authentication provider.

The App Service Authentication feature can automatically create an app registration with the Microsoft identity platform. You can also use a registration that you or a directory admin creates separately.

• Create a new app registration automatically
• Use an existing registration created separately

Option 1: Create a new app registration automatically

This option is designed to make enabling authentication simple and requires just a few clicks.

1. Sign in to the Azure portal and navigate to your app.

2. Select Authentication in the menu on the left. Click Add identity provider.

3. Select Microsoft in the identity provider dropdown. The option to create a new registration is selected by default. You can change the name of the registration or the supported account types.

   A client secret will be created and stored as a slot-sticky application setting named MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. You can update that setting later to use Key Vault references if you wish to manage the secret in Azure Key Vault.

4. If this is the first identity provider configured for the application, you will also be prompted with an App Service authentication settings section. Otherwise, you may move on to the next step.

   (Video) Azure App Service Authentication - Inbuild with Azure AD

   These options determine how your application responds to unauthenticated requests, and the default selections will redirect all requests to log in with this new provider. You can change customize this behavior now or adjust these settings later from the main Authentication screen by choosing Edit next to Authentication settings. To learn more about these options, see Authentication flow.

5. (Optional) Click Next: Permissions and add any scopes needed by the application. These will be added to the app registration, but you can also change them later.

6. Click Add.

You're now ready to use the Microsoft identity platform for authentication in your app. The provider will be listed on the Authentication screen. From there, you can edit or delete this provider configuration.

For an example of configuring Azure AD login for a web app that accesses Azure Storage and Microsoft Graph, see this tutorial.

Option 2: Use an existing registration created separately

You can also manually register your application for the Microsoft identity platform, customizing the registration and configuring App Service Authentication with the registration details. This is useful, for example, if you want to use an app registration from a different Azure AD tenant than the one your application is in.

Create an app registration in Azure AD for your App Service app

First, you will create your app registration. As you do so, collect the following information which you will need later when you configure the authentication in the App Service app:

• Client ID
• Tenant ID
• Client secret (optional)
• Application ID URI

To register the app, perform the following steps:

1. Sign in to the Azure portal, search for and select App Services, and then select your app. Note your app's URL. You'll use it to configure your Azure Active Directory app registration.

2. From the portal menu, select Azure Active Directory, then go to the App registrations tab and select New registration.

3. In the Register an application page, enter a Name for your app registration.

4. In Redirect URI, select Web and type <app-url>/.auth/login/aad/callback. For example, https://contoso.azurewebsites.net/.auth/login/aad/callback.

5. Select Register.

6. After the app registration is created, copy the Application (client) ID and the Directory (tenant) ID for later.

   (Video) How to Authenticate an Azure AD, Configure Azure Web App to Use Azure Active Directory

7. Select Authentication. Under Implicit grant and hybrid flows, enable ID tokens to allow OpenID Connect user sign-ins from App Service. Select Save.

8. (Optional) Select Branding. In Home page URL, enter the URL of your App Service app and select Save.

9. Select Expose an API, and click Set next to "Application ID URI". This value uniquely identifies the application when it is used as a resource, allowing tokens to be requested that grant access. It is used as a prefix for scopes you create.

   For a single-tenant app, you can use the default value, which is in the form api://<application-client-id>. You can also specify a more readable URI like https://contoso.com/api based on one of the verified domains for your tenant. For a multi-tenant app, you must provide a custom URI. To learn more about accepted formats for App ID URIs, see the app registrations best practices reference.

   The value is automatically saved.

10. Select Add a scope.

    1. In Add a scope, the Application ID URI is the value you set in a previous step. Select Save and continue.
    2. In Scope name, enter user_impersonation.
    3. In the text boxes, enter the consent scope name and description you want users to see on the consent page. For example, enter Access <application-name>.
    4. Select Add scope.

11. (Optional) To create a client secret, select Certificates & secrets > Client secrets > New client secret. Enter a description and expiration and select Add. Copy the client secret value shown in the page. It won't be shown again.

12. (Optional) To add multiple Reply URLs, select Authentication.

Enable Azure Active Directory in your App Service app

1. Sign in to the Azure portal and navigate to your app.

2. Select Authentication in the menu on the left. Click Add identity provider.

3. Select Microsoft in the identity provider dropdown.

4. For App registration type, you can choose to Pick an existing app registration in this directory which will automatically gather the necessary app information. If your registration is from another tenant or you do not have permission to view the registration object, choose Provide the details of an existing app registration. For this option, you will need to fill in the following configuration details:

   Field	Description
   Application (client) ID	Use the Application (client) ID of the app registration.
   Client Secret	Use the client secret you generated in the app registration. With a client secret, hybrid flow is used and the App Service will return access and refresh tokens. When the client secret is not set, implicit flow is used and only an ID token is returned. These tokens are sent by the provider and stored in the EasyAuth token store.
   Issuer Url	Use <authentication-endpoint>/<tenant-id>/v2.0, and replace <authentication-endpoint> with the authentication endpoint for your cloud environment (e.g., "https://login.microsoftonline.com" for global Azure), also replacing <tenant-id> with the Directory (tenant) ID in which the app registration was created. This value is used to redirect users to the correct Azure AD tenant, as well as to download the appropriate metadata to determine the appropriate token signing keys and token issuer claim value for example. For applications that use Azure AD v1, omit /v2.0 in the URL.
   Allowed Token Audiences	The configured Application (client) ID is always implicitly considered to be an allowed audience. If this is a cloud or server app and you want to accept authentication tokens from a client App Service app (the authentication token can be retrieved in the X-MS-TOKEN-AAD-ID-TOKEN header), add the Application (client) ID of the client app here.

   The client secret will be stored as a slot-sticky application setting named MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. You can update that setting later to use Key Vault references if you wish to manage the secret in Azure Key Vault.

5. If this is the first identity provider configured for the application, you will also be prompted with an App Service authentication settings section. Otherwise, you may move on to the next step.

   (Video) Configuring an Azure App Service Identity Provider [GCast 133]

   These options determine how your application responds to unauthenticated requests, and the default selections will redirect all requests to log in with this new provider. You can change customize this behavior now or adjust these settings later from the main Authentication screen by choosing Edit next to Authentication settings. To learn more about these options, see Authentication flow.

6. Click Add.

You're now ready to use the Microsoft identity platform for authentication in your app. The provider will be listed on the Authentication screen. From there, you can edit or delete this provider configuration.

Additional validations (optional)

The steps defined above allow you to authenticate incoming requests for your Azure AD tenant. This allows anyone within the tenant to access the application, which is fine for many applications. However, some applications need to restrict access further by making authorization decisions. Your application code is often the best place to handle custom authorization logic. However, for common scenarios, the platform provides built-in checks that you can use to limit access.

This section shows how to enable built-in checks using the App Service authentication V2 API. Currently, the only way to configure these built-in checks is via Azure Resource Manager templates or the REST API.

Within the API object, the Azure Active Directory identity provider configuration has a valdation section that can include a defaultAuthorizationPolicy object as in the following structure:

{ "validation": { "defaultAuthorizationPolicy": { "allowedApplications": [], "allowedPrincipals": { "identities": [] } } }}

Requests that fail these built-in checks are given an HTTP 403 Forbidden response.

Configure client apps to access your App Service

In the prior section, you registered your App Service or Azure Function to authenticate users. This section explains how to register native client or daemon apps so that they can request access to APIs exposed by your App Service on behalf of users or themselves. Completing the steps in this section is not required if you only wish to authenticate users.

Native client application

You can register native clients to request access your App Service app's APIs on behalf of a signed in user.

1. In the Azure portal, select Active Directory > App registrations > New registration.

2. In the Register an application page, enter a Name for your app registration.

3. In Redirect URI, select Public client (mobile & desktop) and type the URL <app-url>/.auth/login/aad/callback. For example, https://contoso.azurewebsites.net/.auth/login/aad/callback.

   Note

   (Video) Authentication and authorization in Azure App Service and Azure Functions

   For a Microsoft Store application, use the package SID as the URI instead.

4. Select Create.

5. After the app registration is created, copy the value of Application (client) ID.

6. Select API permissions > Add a permission > My APIs.

7. Select the app registration you created earlier for your App Service app. If you don't see the app registration, make sure that you've added the user_impersonation scope in Create an app registration in Azure AD for your App Service app.

8. Under Delegated permissions, select user_impersonation, and then select Add permissions.

You have now configured a native client application that can request access your App Service app on behalf of a user.

Daemon client application (service-to-service calls)

Your application can acquire a token to call a Web API hosted in your App Service or Function app on behalf of itself (not on behalf of a user). This scenario is useful for non-interactive daemon applications that perform tasks without a logged in user. It uses the standard OAuth 2.0 client credentials grant.

1. In the Azure portal, select Active Directory > App registrations > New registration.
2. In the Register an application page, enter a Name for your daemon app registration.
3. For a daemon application, you don't need a Redirect URI so you can keep that empty.
4. Select Create.
5. After the app registration is created, copy the value of Application (client) ID.
6. Select Certificates & secrets > New client secret > Add. Copy the client secret value shown in the page. It won't be shown again.

You can now request an access token using the client ID and client secret by setting the resource parameter to the Application ID URI of the target app. The resulting access token can then be presented to the target app using the standard OAuth 2.0 Authorization header, and App Service Authentication / Authorization will validate and use the token as usual to now indicate that the caller (an application in this case, not a user) is authenticated.

At present, this allows any client application in your Azure AD tenant to request an access token and authenticate to the target app. If you also want to enforce authorization to allow only certain client applications, you must perform some additional configuration.

1. Define an App Role in the manifest of the app registration representing the App Service or Function app you want to protect.
2. On the app registration representing the client that needs to be authorized, select API permissions > Add a permission > My APIs.
3. Select the app registration you created earlier. If you don't see the app registration, make sure that you've added an App Role.
4. Under Application permissions, select the App Role you created earlier, and then select Add permissions.
5. Make sure to click Grant admin consent to authorize the client application to request the permission.
6. Similar to the previous scenario (before any roles were added), you can now request an access token for the same target resource, and the access token will include a roles claim containing the App Roles that were authorized for the client application.
7. Within the target App Service or Function app code, you can now validate that the expected roles are present in the token (this is not performed by App Service Authentication / Authorization). For more information, see Access user claims.

You have now configured a daemon client application that can access your App Service app using its own identity.

Best practices

Regardless of the configuration you use to set up authentication, the following best practices will keep your tenant and applications more secure:

• Give each App Service app its own permissions and consent.
• Configure each App Service app with its own registration.
• Avoid permission sharing between environments by using separate app registrations for separate deployment slots. When testing new code, this practice can help prevent issues from affecting the production app.

Next steps

• App Service Authentication / Authorization overview.
• Tutorial: Authenticate and authorize users end-to-end in Azure App Service

• Tutorial: Authenticate and authorize users in a web app that accesses Azure Storage and Microsoft Graph
• Tutorial: Authenticate and authorize users end-to-end in Azure App Service