Updated: Feb 14, 2014 - the Permissions section below has bee revised to use who how to configure an App, to use OAuth 2.0 Authorization Code Grant, by using the Azure Management Portal's Application Configuration capabilities.
You might have seen the recent announcement of developer preview for support of OAuth Code Grant in Azure Active Directory. You can use this to provide delegated access when accessing resources. We can use the same mechanism to access AAD resources using delegated access via Graph API. We have an updated PHP sample that shows how to use this. The blog post provides details on what’s required in building such an application.
In our previous posts on this blog and our samples web site, we have shown various kinds of Applications you can build that consume information from AAD Graph. But the one thing that was common to all the applications was that they used Application credentials exclusively when talking to AAD Graph and did not use User identity. Since the user identity is not used in the Client Credentials flow, the application has to take the responsibility for making sure that the users are authenticated and are given the appropriate level of access when accessing resources in AAD. Users get different permissions in AAD depending on the role they belong to. For example, all Users get permissions to read their own information. But if a User belongs to “Company Administrator” role, he has administrator permissions and can read and write objects of other users as well. So how can application developers just depend on the Access Checks put into place in AAD Graph rather than enforcing them in their application when accessing AAD data? This is where OAuth 2.0 Authorization code grant will help us build an application using delegated access to the directory resources.
The functionality provided by the PHP sample is very limited. The goal is to show how Authorization Code can be used to access AAD Graph and so the application does not do much beyond that. The first thing the application asks the customer to do is to authorize via the AAD portal. Typically the application would authenticate the user via WS-Fed or SAML protocol but to make things simple, the sample application directly takes user to authorization. Once authorized, user is redirected to a page showing his/her details. There is an Edit link at the bottom of this page. You can only use this link if you have are using Administrator credentials while authorizing the application. And this access check is not done by the application but by the Graph API. Here is a brief description of the files that are part of this sample.
The previous steps below are now replaced using the Windows Azure Management Portal: https://manage.windowsazure.com/ Login to your Azure AD company, from this portal, and select "Add an application you're developing"
Next, select the type of App that you're developing - select Web Application and give it a friendly name, advance to the next step.
On step 2, add your App properties - the Sign-on URL will not be used in the PHP demo app, so set to any value. The App ID URI is a unique identifier for the app, and will be used in the PHP app's config file later.
Next configure permissions - for this demo, select the 3rd option Single Sign-on, Read and Write Directory Data. Select the check mark to finish the initial application configuration.
From the main Azure AD management portal, select "Applications" from the top menu bar. Find your application and select it.
From the Application page, Expand the section "Enable your app to read or write directory data", and select the Configure Key link,
You should now see the Configure page similar to the one shown below.
On the Configure App page:
1. Write down the Client ID value - this is the application ID, and will be used in the settings.php of the PHP app ($clientId variable).
2. Under the keys section, select a key duration (1 or 2 year) - the key value will be displayed after you select Save at the end. The key value will be used in the settings.php file ($password variable)
3. in the Reply Url section - enter http://localhost:9485/HandleAuthorizeResponse.php - this is the URL that the Authorization endpoint will redirect to, after the user successfully authenticates. This should be equal to the $ridrectUri value in the settings.php file.
4. Under Web apis - select "Windows Azure AD Graph" from the drop down menu - in the settings.php file, the value of the $resourceUri is "https://graph.windows.net", which is the WIndows Azure AD Graph Uri.
5. Select the Save button on the bottom.
After successfully saving the configuration, the key value should be displayed under keys - please record and save this value in a safe location. This key value cannot be retrieved after exiting this page. As mentioned in the above step, the key value is used for $clientId value in the settings.php file.
Your App configuration is now complete on the Azure AD side, now update the PHP sample app's settings.php values to match your configuration - Note: you will also need to add your tenant's name in the $appTenantDomainName variable in the settings.php file - this can be any domain owned by your tenant.
Below this line was the original, out of date instructions on Application Configuration.
Steps to setting up permissions for application:
This is how the form looks before clicking “Create Permission”.
Once you click the “Create permission” button, Graph explorer will create the permission and show you the Client Id, App URL, Credentials Key for the Client application. Copy these values to settings.php file in the sample. App Url is called redirectURI in the application and Credentials Key is called password.
Now that the permission object has been set up, we can proceed to access Graph from our Application. The first thing we need to do is access the Authorization end point and get the authorization code. The end point for Authorization is: https://login.windows.net/common/oauth2/authorize . We need to specify the Application Id for the client application, application URI for the resource (in our case Graph) and the redirect URI we had specified while creating the Service Principal. The user will be redirected to the Azure AD login page and the user will be redirected back to the Redirect URI we specified in the request parameter after a successful login. The redirect URL will have the Authorization code. The sample response shown below is the redirect request to the application after a successful login. The client_id and redirect_uri in the request below comes from the above step when you created permission for this application.
HTTP Method: GET
We can now use the Authorization code in conjunction with the client application Id, client Application Secret etc. to fetch the Access token. The Access token can be used to access the data of the tenant and the permissions that the App gets will be based on the role that the User belongs to and the Role that was used in Scope parameter when creating the Permission object for this application. The client_id and client_secret are the values from the Graph explorer when we created permission for this application.
You can use access token in the response to talk to Graph by providing in the Authorization header(Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb…….. VQ). The sample application does not login the user and stores a profile locally but a lot of real world application may want to do that in which case you can go back and fetch the access token without user interaction by using the refresh_token value in the response. The next section explains how to get an access token using a refresh token.
So the user has authenticated to the application and we have the access token to access Graph. But how do we get the information about the currently authorized user. It’s really simple with the new functionality that just got added in the Graph service. You can refer to the current user using the “me” alias. So the following URL can be used to get all the groups and roles that the user is memberOf: https://graph.windows.net/me/isMemberOf?api-version=2013-11-08 . Graph will figure out the user information from the claims in the token. The PHP application just displays the information regarding the user and thus does the following query to the graph: https://graph.windows.net/me?api-version=2013-11-08 and provides the token retrieved previously from token end point in Authorization Header. Apart from the “me” alias, “myorganization” alias was also added recently to Graph and refers to the tenant associated with the currently authenticated user or application trying to access graph. So you can use the following query to get all users for the tenant: https://graph.windows.net/myorganization/users?api-version=2013-11-08 .
As always, feedback and questions are welcome.