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:
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
https://graph.microsoft.com/User.Readformat 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.
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.
var scopes = [ appidURI + "/.default"];