Skip to content

api scopes

Navya Canumalla edited this page Apr 20, 2019 · 1 revision

Scopes when acquiring tokens for APIs

Scopes are the permissions that a web API exposes for client applications to request access to. Client applications request the user's consent for these scopes when making authentication requests to get tokens to access the web APIs.

MSAL.js allows you to get tokens to access to Azure AD v1.0 and Azure AD v2.0 APIs. Azure AD v2.0 protocol uses scopes instead of resource in the requests. Refer Azure AD v1.0 and v2.0 comparison for more details. Based on the web API's configuration of the token version it accepts, the Azure AD v2.0 endpoint returns the access token to MSAL.js.

Below are the different format of scopes you need to pass to get tokens using MSAL.js:

Request specific scopes for a web API

When your application needs to request tokens with specific permissions for any resource API, you will need to pass the scopes containing the App ID URI of the API in the below format: appidURI/scope

For example, scopes for Microsoft Graph API:

var scopes = ["https://graph.microsoft.com/User.Read"];

For example, scopes for a custom web API:

var scopes = ["api://abscdefgh-1234-abcd-efgh-1234567890/api.read"];

Note: Only for the MS Graph API, a scope value user.read maps to https://graph.microsoft.com/User.Read format and can be used interchangeably.

Note: Certain web APIs such as Azure Resource Manager API (https://management.core.windows.net/) expect a trailing '/' in the audience claim (aud) of the access token. In this case, it is important to pass the scope as https://management.core.windows.net//user_impersonation (note the double slash), for the token to be valid in the API.

Request dynamic scopes for incremental consent

When building applications using Azure AD v1.0, you had to register the full set of permissions(static scopes) required by the application for the user to consent at the time of login. In Azure AD v2.0, you can request additional permissions as needed using scope parameter. These are called dynamic scopes. This allows the user to provide incremental consent to scopes.

For instance, if initially you just want the user to sign in and don’t need any kind of access, you can do so. If later you need the ability to read the calendar of the user, you can then request the calendar scope in the acquire token methods and get the user's consent.

For example:

var scopes = ["https://graph.microsoft.com/User.Read", "https://graph.microsoft.com/Calendar.Read"];

// pass scopes in acquireTokenPopup or acquireTokenRedirect call

Request all scopes(static scopes) for a v1.0 web API

When getting tokens for V1.0 APIs using MSAL.js, you can request all the static scopes registered on the API by appending .default to the App ID URI of the API. For example:

var scopes = [ appidURI + "/.default"];
You can’t perform that action at this time.