In this article, let’s have look at some details about scopes and consents and how they can be used to authorize the requests to the resources.
What are Scopes?
Microsoft Identity Platform uses OAuth 2.0 protocol. This protocol allows to access web-hosted resources on behalf of the user. Every application registered in Azure AD has a unique Application ID URI. Every web-hosted resource has it. e.g. Azure key vault has URI https://vault.azure.net
Every application can also be divided into small chunks of functionalities. The application can then also define the set of permissions required to access those functionalities.
For example, Microsoft Graph has defined permissions to do the following tasks, among others:
- Read a user’s calendar
- Write to a user’s calendar
- Send mail as a user
These types of granular permissions allow the applications to have fine grained control over how application functionality is exposed. Also, it enables the consumers to request only required set of permissions.
Users and administrators can know exactly what data the app has access to, and they can be more confident that it isn’t behaving with malicious intent. Developers should always abide by the concept of least privilege, asking for only the permissions they need for their applications to function.
In OAuth2.0 world, these permissions are called as Scopes. In Microsoft Identity Platform, the permission is represented in the form of a string value. In above example of user’s calender, the permission to read can be Calenders.read and so on.
An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint.
Common OAuth Scopes
The Open ID Connect implementation on Microsoft Identity Platform has some scopes which are not specific to any resource. Let’s have quick look at them.
openid
For performing sign in using Open ID connect, the application must request this scope.
This scope can be used by Microsoft Identity Platform token endpoint to acquire ID tokens which can be used by application for authentication.
With this scope, the token has sub claim which contains unique identifier for the user.
This scope can be used with openid or any other scope. This scope gives application the access to user’s primary email address.
The token which was requested using this scope contains email claim which holds primary email address of user. This claim is included only if the email address is available on associated user account.
So, the applications expecting this email claim, should also handle case where this claim is not returned at all (i.e. if account does not have any email address )
profile
This scope can be used with openid scope or any other scopes. This scopes gives access to username, given name, surname, etc. For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.
offline_access
This scope enables your application to access the resource on behalf of user for an extended amount of time. If this scope is used and user approves this scope, the application receives refresh tokens.
This scope should be explicitly specified to receive the refresh tokens.
Generally, the APIs are accessed using access tokens and access tokens are short lived (usually about an hour). In that case, refresh tokens are long lived and application can use them to get new access tokens.
User Consent vs Admin Consent
When we exposed an API by registering the API application in Azure AD, you may remember that there was an input – who can consent ? – and the options were Admins only vs users and admins
Let’s try to have quick look at what are those options about.
Admins Only
These are the scopes for which only administrators can provide the consent. By administrators, here we mean Azure AD tenant administrators.
There may be cases where an organization has purchased an application or license and they want to set it up in such a way that every user in organization can access it. In such cases, the tenant administrators can provide the consent.
Users and Admins
These are the scopes for which users as well as administrators both can provide the consent.
When user tries to login all the scopes are passed to authorized endpoint in scope parameter which has value of all scopes separated by space. The Microsoft Identity Platform checks if the user consent has been provided already. If it was not provided already, then a new popup is shown to user where the consent is asked.
I hope this article provides some information about basics of scopes and consent and authorization model based on them. Let me know your thoughts.
