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

• Anonymous
  October 12, 2015
  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?

• Anonymous
  October 13, 2015
  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.

• Anonymous
  November 04, 2015
  I am in the same predicament as Joonas. How does one provide the scope to reset passwords now?

• Anonymous
  November 04, 2015
  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...

• Anonymous
  November 05, 2015
  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.

• Anonymous
  November 08, 2015
  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

• Anonymous
  November 08, 2015
  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!

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

• Anonymous
  November 09, 2015
  Thanks Klaudiusz Witoszek, that link was a huge help.

• Anonymous
  November 09, 2015
  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)?

• Anonymous
  November 15, 2015
  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?

• Anonymous
  January 03, 2016
  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

• Anonymous
  February 04, 2016
  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

• Anonymous
  February 17, 2016
  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.