Request permissions that require administrative consent

In this article, we describe the permission and consent experience for a scenario where you, as a developer, are writing your application code to request application permissions that require administrative consent. Example screenshots of permission and consent dialogs and the Microsoft Entra admin center give you an idea of what your users and tenant admins experience. Improve collaboration with admins to implement the Zero Trust principle of least privilege in your applications.

As you develop your application, you write code that requests access to a resource by requesting an access token with a specific scope (or permission). You use the scope parameter as described in the OAuth 2.0 standard that some people describe as a permission. Resource owners grant or deny permission requests. In Microsoft Entra ID, the resource owner is either the user of the app or an admin who has the rights to grant consent to that resource on behalf of all users.

User consent experience

When your application requests permission to access a resource, your user might see a Permissions requested dialog similar to this example.

In the above example dialog, the user grants consent to allow the app to read the data on their behalf by selecting Accept or denies the request by selecting Cancel. The application receives an access token and can continue its processes after the user grants consent. Remember to ensure that your app is ready to gracefully handle when it doesn't receive a token.

Admin consent experience

For some access requests, only an admin can grant consent. If the requested access is powerful or involves resources whose owners aren't the current users, code so that only an admin can grant requests.

However, you never know which permissions require admin consent and which allow a regular user to grant consent because tenant admins can configure their tenant with Do not allow user consent (all permissions require admin consent) as shown in the following example screenshot of User consent settings in the Microsoft Entra admin center.

Admins can also Allow user consent for apps from verified publishers, for selected permissions as shown in the following example screenshot of User consent settings in the Microsoft Entra admin center.

Admins can then Add permissions to which users can consent as shown in the following example screenshot of Permission classifications in the Microsoft Entra admin center.

When your app requests a permission that requires admin consent (by design or admin configuration), your user might see a Need admin approval dialog similar to this example.

The above example dialog shows the default (out of the box) experience for permissions that require admin consent. Most users don't know what to do in this scenario. They don't know who their admin is, they don't know who to go to for approval. This uncertainty can limit the user's ability to achieve desired results.

Improving the permissions and consent experience

To improve the permissions and consent experience, the tenant admin can configure the admin consent workflow as shown in the following example screenshot of User settings in the Microsoft Entra admin center.

In Admin consent requests, the tenant admin can improve the user's permission and consent experience by selecting Yes on Users can request admin consent to apps they're unable to consent to and configuring other Admin consent requests settings.

After the tenant admin selects Yes on Users can request admin consent to apps they're unable to consent to and an application requests a permission that requires admin consent, the user sees something similar to the following Approval required dialog that provides a better user experience.

In the above example dialog, the user can Enter justification for requesting this app before selecting Request approval. The approval request then enters an Admin consent requests queue where admins have options to review, accept, or ban applications in their organization based on risk profile.

When an admin runs an application that requires admin consent without configuring consent in the Microsoft Entra admin center, the admin user sees a Permissions requested dialog similar to the following example.

In the above example, the admin sees a description of the permissions that the application is requesting. The admin can select Accept to individually run the application or they can select Consent on behalf of your organization before selecting Accept. After the admin grants consent for the organization, no future organization user needs to grant permission for this application unless an admin removes consent from the tenant Admin consent requests configuration.

Another method of tenant admin consent is in Microsoft Entra admin center Permissions where admins can review the details of previously requested app permissions.

In the above User consent example, the admin can review the granted permissions for the app along with information about claims, permission type, and who gave consent. The admin can select Admin consent to review granted permissions that require admin consent.

Requesting admin consent in advance

Your best application permissions strategy is to declare in advance all of the permissions that your app might need or request when you register your app. You don't have to request all permissions at the same time but, after you declare all of the permissions that your app might need, admins can select Grant admin consent for in your app's configuration in the tenant to display a dialog similar to this example.

The above example shows how the admin can preconsent to the permissions that you declared and provide the best experience for your users and tenant admins.

Requesting admin consent ahead of time is an excellent choice for line of business (LOB) apps, especially the apps that your organization is developing. It's easier to not have to ask your user if your company can access your company's data by preconsenting those applications. You make the admin consent request as part of your app registration process.

Next steps

• Acquire authorization to access resources helps you to understand how to best ensure Zero Trust when acquiring resource access permissions for your application.
• API Protection describes best practices for protecting your API through registration, defining permissions and consent, and enforcing access to achieve your Zero Trust goals.
• Authorization best practices helps you to implement the best authorization, permission, and consent models for your applications.
• Customize tokens describes the information that you can receive in Microsoft Entra tokens. It explains how to customize tokens to improve flexibility and control while increasing application zero trust security with least privilege.
• Overview of permissions and consent in the Microsoft identity platform helps you to understand foundational concepts of access and authorization.
• Overview of consent and permissions helps you to learn foundational concepts and scenarios around consent and permissions in Microsoft Entra ID.
• Learn module: Permissions and consent framework helps you to learn permissions and consent framework models.
• Learn Live: Microsoft Identity: Permissions and Consent Framework helps you to learn the basics of Microsoft identity including tokens, account types, and topologies.