New graph API consent permissions


Today we’re glad to announce a few updates to our Azure AD Graph API permission scopes.  Some of these new permission scopes can be consented by non-admin users, enabling greater reach for your applications.  This is something the team is really excited about. 

The new permission scopes

In addition to the four existing permission scopes (the four listed at the bottom in the Azure Management Portal screenshot below), we’ve now added four new delegated scopes (and an additional app-only permission scope which is not shown).

In order to enable a number of key scenarios, developers previously needed to request privileged permissions that required an administrator to consent.  By introducing a new set of more granular permissions, we’ve allowed some key scenarios to be enabled for your app that can either be consented by a non-admin user. For example with the “Read all users’ basic profiles” you can now build a people picking experience to control access to resources in your application, that non-admin users can consent to. While introducing this additional flexibility for you, we still ensure that privileged operations can only be consented by an administrator. This allows you to create applications that can reach a larger audience, while protecting privileged operations. Additional permissions around groups still require admin consent, but are now less privileged in nature than the pre-existing permission scopes. 

Scenario

Permission scopes required

Admin consent required?

People picker – core to many applications is the ability to pick users to control access to resources in your application.

Read all users’ basic profiles

No

Org chart navigator –  see a user’s reports and their management chain.

Read all users’ full profiles

Yes

Groups and memberships viewer

Read all users’ basic profiles

Read all groups

Yes

Group management service that allows users to create, manage and delete groups.  (NOTE the user of the app would need to be in a role that allows for group creation and management).

Read all users’ basic profiles

Read and write all groups

Yes

 

So you might ask – how can we allow an end user to consent to release  information to an application about other users in their organization?  The new permission “Read all users’ basic profiles” (which has the scope claim value “user.readbasic.all”) releases only limited information about other users. When querying the user entity, it exposes only enough information to make a people picker useful, without releasing information like phone numbers or location.  To be specific, it allows the calling application to get the first name, last name, display name, photo and email address of other users in the organization of the signed-in user.

We’ve also updated a few of the existing permission scopes:

  1. We’ve restricted the “Read and write directory data” permission so that it no longer allows the application to reset other user passwords.
  2. We’ve extended the “Sign in and read user profile” permission to also allow the application to read some basic information about the company (company display name and verified domains) through the tenantDetails entity.  NOTE: For any users who have already consented to this permission (prior to this update), the application will not have access to the tenantDetails entity.

Great new permissions topic

To go with this release, we’ve updated our Azure AD Graph API permissions topic.  This topic goes into greater detail on all our permission scopes, describing:

  • Concepts such as delegated vs app-only permissions, and full vs basic profiles for users and groups.
  • Permission scope details highlighting what each scope is capable of, if it’s app-only or delegated, and whether it requires an admin to consent.

What’s next?

This change not only introduced new permission scopes, but also an update to our underlying platform that will allow our team to introduce additional permission scopes more quickly.  New scopes will be driven by developer and application scenarios and by our principles to align permission scopes along the entities in our API and to explicitly split out new permission scopes for privileged operations (such as changing or resetting passwords).

What do you think?

As always, we’d love to hear more from you all.  Are these new permission scopes useful?  Are there any permission scopes you’d like to see and why those are important for your scenarios?

Comments (14)

  1. Kunjan Patel says:

    Hello,

    We have noticed that there has been now issue with new users signing up after this update

    here is the issue details:

    social.msdn.microsoft.com/…/graph-client-throwing-insufficient-privileges-to-complete-the-operation-on-creating-ad-user

    Do we have to change anything in my app?

  2. Joonas Westlin says:

    Hello,

    Thanks for the update. I've been reading your scope permissions topic and searching elsewhere but I can't seem to find anything about which permission scope is needed for an app to be able to reset passwords? I understand it was removed from one of the scopes, but is there an alternative available currently? I tried giving my application the delegated Access directory on behalf of signed in user permission, but it is a no go even though the user is a global administrator.

  3. Kyle says:

    I am in the same predicament as Joonas. How does one provide the scope to reset passwords now?

  4. Klaudiusz Witoszek says:

    Well, great.

    "1.We've restricted the "Read and write directory data" permission so that it no longer allows the application to reset other user passwords."

    We have 30.000 users in our AAD. Managing users in our AAD is maintained by our software (plugin for MS CRM). We had few hundred requests to reset password in our organization yesterday only. What now? It seems that we will need to get back to "forms authentication" for our application. This is some kind of joke…

  5. Klaudiusz Witoszek says:

    support.microsoft.com/…/3004133

    This worked for us. When we added our App defined in Add to "Company Administrator" role everything started to work as previously. Getting token through keySecret (i.e. client credentials) started to work for update operations.

  6. Mike says:

    Hi Klaudiusz,

    I have the same issue. How did you "added our App defined in Add to "Company Administrator" role"?

    Help would be appreciated.

    Cheers,

    Mike

  7. Wensi Mu says:

    I see this article says as a non-admin user I can get all users' basic profile, but in my practice, I get permission limited issue with garp API: https://graph.windows.net/{0}/users?..

    Is next step AAD team will update graph API  or I am using the wrong query? Thanks!

  8. Sinus Frank says:

    As far as I can see, this work around is only true for Office 365 accounts? What if you don't use that?!?

  9. Cam Hart says:

    Thanks Klaudiusz Witoszek, that link was a huge help.

  10. Sinus Frank says:

    Let me rephrase that: I have a web api, from which I get a get an Access Token for the Graph API – through the app id and the secret key. Like this:

    AuthenticationResult result = null;

               var authContext = new AuthenticationContext("login.windows.net/login.bzmart.today");

               result = authContext.AcquireToken("https://graph.windows.net",

                   new ClientCredential("THE-App-ID-for-the-web-API",

                       "{Secret key}"));

               authContext.TokenCache.Clear(); // Important. This clearsTokenCache from memory!

               string token = result.AccessToken;

               return token;

    This token needs to be able to call the Graph API and update a user's password – how (when Microsoft has removed the possibility to do this)?

  11. Dan Kershaw says:

    Hi folks,

    Firstly sorry for causing these issues by removing this privileged operation from the Directory.ReadWrite.All permission.  You could use the  "Directory.AccessAsUser.All delegated permission instead. We are looking at introducing a new specialized privileged app-only permission for single tenant apps and/or a similar delegated (app+user) permission.

    Using app only mode to perform a privileged operation like resetting users passwords could be a little risky if that application is compromised.  Even more risky is giving an app full company admin permissions.

    Far safer would be to use the app+user (delegated code) flow, where a signed in user must also present as part of the API call, AND also needs permissions to perform this action (i.e. in the password reset case either a company admin or a user management admin).  For now you could use the "Directory.AccessAsUser.All delegated permission.

    So quick question – what all scenarios do you folks have that require a service (without a signed-in user) to be able to reset user's passwords?

  12. Sree says:

    Dan,

    One of the scenarios we have for password reset is some kind of licensing requirement. It is a backend webjob that checks for a certain expiry date and resets AD password such that user can no longer use the PaaS application hosted on Azure.

    As it is a web job, there is no concept of a user logging in. Currently we are using the work-around of adding our app as 'Company Administrator' as per support.microsoft.com/…/3004133

    Hope that gives sufficient background on the scenario and why we need this permission scope figured out ASAP

  13. murali says:

    Hi,

    I am accessing the graph api –

    "graph.windows.net/…/users$filter=startswith(mailNickname,'" + loggedinuser + "')&$top=" + "10" + "&api-version=1.5");

    – and I am getting forbidden error 403 – but when I am trying to access the api with "me" attribute , the data is returned.And , one more thing is I am giving the credentials as

    ClientCredential credentials = new ClientCredential( app 1 details ), for one my apps its coming ok,,but for another application the error thrown is 403 ( for app2 details ). and I am the owner for both these apps. Is there any thing to be checked.

    Thanks

  14. Gaurav (gaurav.del@gmail.com) says:

    We are moving from another identity provider to AD B2C. Another scenario when we needs password reset is allowing a user to reset password after user has provided enough information and our application has determined that the user is a real user. e.g. User X comes in, forgot his password, provides demographics, answer security questions (not sure if that is supported in Azure AD) and then if everything is correct, then we allow user to reset their password on the fly.

    I understand that we can enabled reset-password by using an alternate email address but that will change user experience.

Skip to main content