Manage OAuth tokens in Azure App Service

This article shows you how to manage OAuth tokens for built-in authentication and authorization in Azure App Service.

Retrieve tokens in app code

Azure App Service injects your provider-specific tokens into the request header so you can easily access them. To get the provider-specific tokens, token store must be enabled for the app.

Send an HTTP GET request to /.auth/me from your client code, such as a mobile app or in-browser JavaScript. The returned JSON has the provider-specific tokens.

The following table lists the OAuth token header names for several App Service built-in providers:

Refresh auth tokens

The following information refers to provider tokens. For session tokens, see Extend session token expiration grace period.

If your provider's access token expires, you must reauthenticate the user before you can use that token again. You can avoid token expiration by making a GET call to the /.auth/refresh endpoint of your application.

To refresh your access token at any time, call /.auth/refresh in any language. The following snippet uses jQuery to refresh your access tokens from a JavaScript client.

function refreshTokens() {
  let refreshUrl = "/.auth/refresh";
  $.ajax(refreshUrl) .done(function() {
    console.log("Token refresh completed successfully.");
  }) .fail(function() {
    console.log("Token refresh failed. See application logs for details.");
  });
}

When called, App Service automatically refreshes the access tokens in the token store for the authenticated user. Subsequent requests for tokens get the refreshed tokens. You can see the refresh tokens and the expiration time for the tokens by using the headers listed in Retrieve tokens in app code.

Configure providers to supply refresh tokens

For token refresh to work, the token store must contain refresh tokens from your provider. Each provider documents how to get their refresh tokens. The following table provides a brief summary:

Configure the Microsoft Entra provider to supply refresh tokens

1. In the Azure portal, go to the API Playground (preview), and select New request if necessary.
2. In the Enter ARM relative path here including API version field, enter the following string, replacing the placeholders with your subscription ID, resource group name, and app name:
   subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/config/authsettingsV2?api-version=2024-11-01
3. Select Execute.
4. Select PUT at upper left, and select the Request body tab.
5. Copy the GET response contents from the Response body field and paste them into the Request body tab.
6. In the code, locate the "identityProviders": > "azureActiveDirectory": > "login": section, and add the following line:
   "loginParameters": ["scope=openid profile email offline_access"]
7. Select Execute. The Response body field shows your changes.

Offline_access is the scope that provides refresh tokens. App Service already requests the other scopes by default. For more information, see OpenID Connect Scopes and Web Apps - Update Auth Settings V2.

Extend session token expiration grace period

The authenticated session expires after 8 hours, and a 72-hour default grace period follows. Within this grace period, you can refresh the session token with App Service without reauthenticating the user. You can simply call /.auth/refresh when your session token becomes invalid, and you don't need to track token expiration yourself.

When the 72-hour grace period lapses, the user must sign in again to get a valid session token. If you need a longer expiration window than 72 hours, you can extend it, but extending the expiration for a long period could have significant security implications if an authentication token is leaked or stolen. It's best to leave the setting at the default 72 hours or set the extension period to the smallest possible value.

To extend the default expiration window, run the following Azure CLI command in Azure Cloud Shell:

az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>

Related content

• Tutorial: Authenticate and authorize users end to end