Azure-docs: Application permission 'scopes'

[stewartadam]

Following up on https://github.com/MicrosoftDocs/azure-docs/issues/21146, this documentation needs clarity on how to request scopes/roles when using application permissions, i.e. the client_credentials flow.

The documentation references using .default or https://endpoint/.default for legacy v1 behavior, but any attempt to specify a specific application permission/role (e.g. https://endpoint/User.Read.All) fails:

AADSTS70011: The provided request must include a 'scope' input parameter. The provided value for the input parameter 'scope' is not valid.

If only .default is valid, why offer a scopes parameter at all?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 0ac43307-75d4-cb6f-e561-0dd9008f28c6
• Version Independent ID: 8fc47e76-5ee1-6aeb-73e2-c64c44e3e4ed
• Content: Microsoft identity platform scopes, permissions, and consent
• Content Source: articles/active-directory/develop/v2-permissions-and-consent.md
• Service: active-directory
• Sub-service: develop
• GitHub Login: @rwike77
• Microsoft Alias: ryanwi

[AmanGarg-MSFT]

@stewartadam Thank you for the question! We are investigating this and will get back to you shortly.

[sandeepbhupathi]

Hi @AmanGarg-MSFT I have a similar question, how to provide scopes User.Read,Sites.Read.All,Sites.ReadWrite.All for getting client credentials using Java graph, if I get token using https://graph.microsoft.com/.default, I'm unable to proceed with operations on site, any recommendation would be greatly appreciated. Thanks

[FrankHu-MSFT]

Hey @stewartadam and @sandeepbhupathi you're right our documentation definitely has some room for improvement. in regards to explaining how the scopes work.

Scopes are valid, and .default is NOT the only valid parameter.

Please see the auth code flow here : https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code

for example parameters,
You'll see that you can in fact use different scopes. Can you please show the request that you're sending with the Personal Information removed?

Thanks

[FrankHu-MSFT]

@stewartadam Please let us know if there are anymore questions within the scope of this git issue. If not, I will be closing out this git issue by end of day today. Please reopen this git issue if you have anymore concerns. Thanks

[stewartadam]

The link above is for the auth code grant, the docs are insufficiently clear on the client_credentials flow where it appears only .default is supported.

[FrankHu-MSFT]

Hey @stewartadam in regards to client credentials it does say it needs to have the .default affixed, please see : https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#get-a-token

The value passed for the scope parameter in this request should be the resource identifier (application ID URI) of the resource you want, affixed with the .default suffix. For the Microsoft Graph example, the value is https://graph.microsoft.com/.default.
This value tells the Microsoft identity platform endpoint that of all the direct application permissions you have configured for your app, the endpoint should issue a token for the ones associated with the resource you want to use. To learn more about the /.default scope, see the consent documentation.

[FrankHu-MSFT]

@stewartadam Please let us know if there are anymore questions within the scope of this git issue. If not, I will be closing out this git issue by end of day today. Please reopen this git issue if you have anymore concerns. Thanks

[stewartadam]

(fwiw, feedback on the triage process -- GitHub users [even msft employees] are not able to re-open issues, so they often go unnoticed once closed, and given that 4 hours as done here (or even a full 24) isn't really a reasonable amount of time to let users reply before closing. If it's a logistical thing, maybe consider a bot to auto-close issues after 48-72h getting #tagged unless another reply was posted?)

That said, I don't consider this resolved or sufficiently clear as-is -- and given the other issue that was created (and closed) about this, and other comments here, it seems this is a common enough misconception.

The snippet you referenced above mentions the request should use /.default, not that it is a hard requirement and no other values are supported. It then links to the page this feedback issue concerns (i.e. this page) to learn more.

Given that I am now aware that https://endpoint/.default is the only supported value for client_credential flows, it's clear the document was written from the perspective of delegated auth in many places which is what causes the confusion:

You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint.

This makes it sound like /.default is a transitional measure and that the more modern scope-based requests should be used in v2 (true for delegated / code flow, not for app permissions / client_credentials flow)

The /.default scope can be used in any OAuth 2.0 flow, but is necessary in the On-Behalf-Of flow and client credentials flow.
/!\ Clients can't combine static (/.default) and dynamic consent in a single request. Thus, scope=https://graph.microsoft.com/.default+mail.read will result in an error due to the combination of scope types.

That makes it sound like the descriptions in the document apply to both flows, and that requesting specific scopes is possible as long as you don't mix (not true for client_credentials)

[sandeepbhupathi]

Hi @FrankHu-MSFT , Please find the attachment for the request.

[stewartadam]

@FrankHu-MSFT thoughts?

[FrankHu-MSFT]

Hey @stewartadam and @sandeepbhupathi I apologize for that, you should have been able to reopen the git issues. I'll look into that.

Let me also engage some more people on this issue to gather more thoughts on how to handle the .default client credential flow scenario.

[stewartadam]

Any updates on this? Thx

[psignoret]

@stewartadam @sandeepbhupathi Thanks for all your feedback here.

To clarify: There is no mechanism to dynamically request app-only permission (i.e. the permissions that are included in access tokens obtained through Client Credentials). Like you've managed to figure out, all Client Credentials requests on the v2 endpoint must include scope={resource}/.default where {resource} is the API which the app intends to call. All granted app-only permissions (roles) for that API will be included in the returned access token.

The only ways to have app-only permission _granted_ are:

• During an interactive sign-in (e.g. Authorization Code flow) using the /.default "scope", if (and only if) the authorization request resulted in a consent prompt, and the signed-in user happens to be an admin.
• At the .../adminconsent endpoint.
• From App registrations > API permissions (if the app is registered in the same tenant) or from Enterprise apps > Permissions (if the app has already been instantiated in the tenant), both of which are equivalent to using the ../adminconsent endpoint.
• Manually through creation of app role assignments using the Graph API (which, if the assigned principal is an app's ServiecPrincipal object, _are_ app-only permission grants).

All of this should be clarified in the documentation. I will submit an update to clarify.

[thespooler]

Similarly, is it possible to request multiple scopes in a single call?
If not why does MSAL ConfidentialClientApplication.PrivateAcquireTokenForClient(string[]) allows for multiple? Is there a specific format?
Requesting
app.AcquireTokenForClient(new string[] { "https://graph.microsoft.com/.default", "https://<MyTenant>.sharepoint.com/.default" }) causes the same error:

AADSTS70011: The provided request must include a 'scope' input parameter. The provided value for the input parameter 'scope' is not valid. The scope https://graph.microsoft.com/.default https://mytenant.sharepoint.com/.default is not valid.

Requesting either individually works just fine.

[psignoret]

You must identify only one resource (API) if you're using /.default.

[rwike77]

@psignoret, can you update the article? Thanks.

[dhoegl]

Hello @psignoret, please let us know when this article will be updated. The methods explained are woefully inadequate. Perhaps step-by-step instructions are needed. Thanks!

[rwike77]

reassign:@psignoret Can you update the article and close out the issue? Thanks.

[vvoinov]

@psignoret, can you, please, provide details of how to specify custom scope in Client Credentials Flow? Ex: I defined a custom scope with api://<my_app_id>/callhiapi URI. However when I try to use this a scope to get access token I get The scope api://<my_app_id>/callhiapi is not valid error.

[hpsin]

You have to use /.default. Please review the client credentials documentation as well. This document should be updated as well.

Get Outlook for Androidhttps://aka.ms/ghei36

---

From: Vladislav Voinov [e-mail]
Sent: Wednesday, April 22, 2020 1:21:32 PM
To: MicrosoftDocs/azure-docs [e-mail]
Cc: Hirsch Singhal [e-mail]; Comment [e-mail]
Subject: Re: [MicrosoftDocs/azure-docs] Application permission 'scopes' (#36432)

@psignorethttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fpsignoret&data=02%7C01%7Chirsin%40microsoft.com%7Cbd38fc8602234500ffee08d7e6fabf4d%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637231836940636109&sdata=%2BWzAwi7V40XtzNPHYI1TQBTV7Wt4%2BJLeogqdn4oHP2k%3D&reserved=0, can you, please, provide details of how to specify custom scope in Client Credentials Flow? Ex: I defined a custom scope with api:///callhiapi URI. However when I try to use this a scope to get access token I get The scope api:///callhiapi is not valid error.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHubhttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fazure-docs%2Fissues%2F36432%23issuecomment-618018390&data=02%7C01%7Chirsin%40microsoft.com%7Cbd38fc8602234500ffee08d7e6fabf4d%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637231836940646105&sdata=jODbiMnT6i2Ng8x5nFHTqC9YJI7GTGehNrd1oveLAGE%3D&reserved=0, or unsubscribehttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAMW2O3VH4FNHYJMI3TLQGLRN5GUZANCNFSM4IJBWVIA&data=02%7C01%7Chirsin%40microsoft.com%7Cbd38fc8602234500ffee08d7e6fabf4d%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637231836940646105&sdata=idtmYyb68d1lFwrqhbgHxYWXzOzNeUbSjpseWuEKH2w%3D&reserved=0.

[vvoinov]

Thanks @hpsin for confirming.

[mmacy]

@psignoret I'm going to take this one and have a go at integrating what you've spelled out in https://github.com/MicrosoftDocs/azure-docs/issues/36432#issuecomment-546324396. Will tag you in the PR for a review.

Cc: @SaeedAkhter-MSFT @CelesteDG @hpsin

reassign:mmacy

[mmacy]

@psignoret Going to #reassign:psignoret this one back over to you for follow-up, Philippe. PR for review is at https://github.com/MicrosoftDocs/azure-docs-pr/pull/124156 - feel free to comment there and/or open a new PR to resolve this issue. Thanks! -MM

Cc: @SaeedAkhter-MSFT @CelesteDG