Radi Atanassov

SharePoint MCM, MVP, MCT and owner of OneBit Software

Authorizing Office 365 SharePoint Apps to read Azure AD data

I've been using the Azure AD Graph API in SharePoint/Office Apps for some time now and the changing releases of the different Microsoft products definitely makes it very confusing for newcomers. The documentation has a long way to go, it is quite tricky with the very few examples that use old API's. I hear that people find it frustrating to get going with the Graph API.

This blog post describes how you can make use of Azure AD in Office/SharePoint Apps, what API's to use and how to authenticate your App. I have been using a technique for a while now and it is still not widely popular, most likely because it is not documented anywhere. I have been presenting on it for a while now:

  • Microsoft InTouch conference 2014
  • EUSPC 2014 in Barcelona
  • SharePoint Days 2014 in Slovenia
  • JSNext 2014 in Bulgaria

Scenarios

  • You are building a SharePoint App that needs to read user data that does not exist in the User Profiles in SharePoint Online
  • You need to get a list of members in a group in Azure Active Directory in a provider-hosted SharePoint App that will run in Office 365
  • You need to reach to other directory objects in Azure AD like Roles, Conference Rooms, Computers, etc.
  • You DON'T have an Azure subscription (you don't need one!)

Background

The first key point to understand: every Office 365 tenant has an Azure Active Directory instance in the background. This was never well-known and it took some time in the industry before the mass population got a grasp of that fact. DirSync helped, but terminology definitely changed, and so did the Azure landscape.

One of first and best posts out there that highlighted this was by fellow MVP Chris O'Brien: http://www.sharepointnutsandbolts.com/2014/04/using-azure-instance-behind-your-office-365-tenant.html His does a great job to show you how you can fiddle with your Office 365 users with a trial Azure subscription.

The second key point: SharePoint Apps get "registered" as Applications (Service Principals) in Azure AD. I will show you how to see that further below.

And the third point: You *don't need* an Azure subscription to work with Azure AD, you can use PowerShell. You will miss out on the awesome web portal, but you can still do your job. Many blog posts show how to do it through the Azure portal, but most don't have an Azure subscription.

Azure Active Directory – a few words

For those not so familiar with Azure AD, it is just a directory in the cloud J There are tons of examples of how Azure AD delivers significant value, but here we focus on what is different from Active Directory on-premises that is relevant to Apps.

Instead of using LDAP to communicate with AD, when using Azure AD we use HTTP-based authentication standards and packet flow: SAML-P, OAuth 2.0, WS-Federation. That's all you need to know for now.

Again, all Office 365 (Multi-tenant) tenants have an instance of Azure AD in the background, so if you are doing anything with Office 365 development, you will eventually come across this.

 

The Graph API

So no LDAP, no DirectorySearcher, no old ways to interrogate the directory. The Azure AD team has built what is called the Graph API.

The terminology is confusing, but if you've been in the SharePoint/Office world that has always been the case. I am sometimes confused myself:

This blog post is specifically about the Azure AD Graph API and how you can use it in SharePoint Apps.

So, why would you care about all this?

As we're moving from On-premises to more and more development in Office 365, you will eventually hit the need to get information from Active Directory that is not in neither the User Profiles, nor attainable through the Office Graph GQL search interface. You will need to do stuff in AD that you just can't do through other API's, for example getting a user's country or Office 365 license information through the User Profiles CSOM API.

Steps to give SharePoint Apps permission to Azure AD

So now with the background out of the way, let's dig into it. As I mentioned previously, you don't need an Azure subscription to read Azure Active Directory data – your Office 365 tenant gives you everything you need.

Our goals:

  • Register a SharePoint App with your tenant -> get a ClientId and ClientSecret
  • Give permissions to the App to call Active Directory using the Graph API
  • Show some code

Registering a SharePoint App with a tenant

I use this technique with our clients when we develop something that is a one-off case, and mainly when we build console applications or windows services that do periodic work on SharePoint Online tenants. I use AppRegNew.aspx and you could read more about it here: https://msdn.microsoft.com/en-us/library/office/jj687469(v=office.15).aspx

You can also find more samples where I use this technique in OfficeDev Patterns & Practices: Core.UserProfiles.Sync Governance.EnforceContentTypeRetention and a few others

  1. Open https://[tenantname].sharepoint.com/_layouts/15/appregnew.aspx
  2. Generate your ClientId and ClientSecret, and fill in the other fields:

If you are just building a console app with no user interaction, the AppDomain & Redirect URI could be just "localhost" & "https://localhost".

Confirm and copy your ClientId and ClientSecret. You could also use AppInv.aspx to give your app permissions to SharePoint data. See one of the OfficeDev PnP samples for more info on that.

Give your App access to Active Directory

This is where the real fun begins.

After you used AppRegNew.aspx, you might wonder where that App configuration goes… Let's have a look.

  1. To use PowerShell with Azure Active Directory you need to get the Azure AD modules: (also described here: Core.UserProfiles.Sync )

http://msdn.microsoft.com/en-us/library/azure/jj151815.aspx is the official MSDN page.

Open the Windows Azure Active Directory PowerShell module (or you can just import the modules):

  1. Connect to your tenant:

Connect-SPOService -Url https://onebitsoftware-admin.sharepoint.com -Credential admin@onebitsoftware.onmicrosoft.com

  1. Purely for academic purposes, poke around:

To prove that SharePoint Apps get registered as Azure Active Directory service principals, run this command:

## Set the app Client Id, aka AppPrincipalId, in a variable

$appId = "06277b15-fc38-4df8-bf93-a76c9f9e5dc2"

 

## get the App Service Principal

Get-MsolServicePrincipal -AppPrincipalId $appId

 

You will get this:

Notice "AppPrincipalId" -> this is the ClientId, there is just a huge element of bad and misaligned terminology.

But the point is made, AppRegNew.aspx registers a SharePoint App as an Azure AD service principal. The Service Principal Names are taken from the AppDomain property and the client Id. The Display Name is what you put in the AppRegNew.aspx form.

NOTE: SharePoint Apps will not appear in the Azure web portal, there are reasons for this and it is normal. See this: Application Objects and Service Principal Objects https://msdn.microsoft.com/en-us/library/azure/dn132633.aspx

  1. Give your App access

Again, for academic purposes, run Get-MsolRole:

This is a list of all roles in AD that you could assign. In our case the "Directory Readers" role is what we need. So let's give that role to our App:

## Set the app Client Id, aka AppPrincipalId, in a variable

$appId = "06277b15-fc38-4df8-bf93-a76c9f9e5dc2"

 

## get the App Service Principal

Get-MsolServicePrincipal -AppPrincipalId $appId

 

## Get the Directory Readers Role

$directoryReaderRole = Get-MsolRole -RoleName "Directory Readers" ##get the role you want to set

 

##Give the app the Directory Reader role

Add-MsolRoleMember -RoleMemberType ServicePrincipal -RoleObjectId $directoryReaderRole.ObjectId -RoleMemberObjectId $appPrincipal.ObjectId

 

You are DONE!

To validate, run this:

##Confirm that the role has our app

Get-MsolRoleMember -RoleObjectId $directoryReaderRole.ObjectId

 

And you will see:

Notice Yammer?? That's how Yammer gets data from Azure AD J This gives you significant info on how things work in AD.

Test access and get going with some code


So, now you need to test, then write the actual code for the SharePoint App.

First, some reading:

http://blogs.msdn.com/b/aadgraphteam/archive/2014/12/12/announcing-the-new-version-of-graph-api-api-version-1-5.aspx

https://msdn.microsoft.com/en-us/library/azure/dn835125.aspx

To test your app authentication, use the Graph Explorer: https://graphexplorer.cloudapp.net/

Type in your tenant UPN followed by /Users to get all users:

When you click Get you will get a login prompt:

Principal Id is the same as "ClientId" and "AppPrincipalId" (bad terms!)

"Symmetric Key" is "ClientSecret".

Click log in and you will get your results J Beware of caching issues!!

Add the Graph Client Library to a project

Now that your authentication is set up, grab the Graph Client Library through Nuget:

https://www.nuget.org/packages/Microsoft.Azure.ActiveDirectory.GraphClient/

That is pretty much all you need! You should keep your assemblies fresh, however beware of the changes, "GraphClient" & "GraphConnection" are old API's, "ActiveDirectoryClient" is the object in 2.0.

Code samples

There's not a hell of a lot of code samples out there, but there are a few to help you get going. I put together an update to the OfficeDev PnP sample "AzureAd.GroupMembership" so check it out:

Core.UserProfiles.Sync - https://github.com/OfficeDev/PnP/tree/dev/Solutions/Core.UserProfiles.Sync - this example gets the Country from Azure AD and syncs it to SPO User Profiles, where that field is unavailable.

(no need for me to paste the code here)

 

The Azure AD Graph Team have good samples too:

http://blogs.msdn.com/b/aadgraphteam/archive/2014/12/12/announcing-azure-ad-graph-api-client-library-2-0.aspx

https://github.com/AzureADSamples/ConsoleApp-GraphAPI-DotNet

https://github.com/AzureADSamples/webApp-GraphAPI-DotNet

That should be enough to get you going, good luck J Please feel free to reach out to me and ask questions, I would be glad to help. You might find me junking in the Yammer OfficeDev Patterns & Practices group.

Comments (4) -

  • Edin Kapic

    2/9/2015 9:01:35 AM | Reply

    Very good article, Radi! There's a lot of "mystery" still surrounding Azure AD and it's our job to make it clearer, especially as everything points out that it will be the one-stop place for authentication/authorization for Office 365 Apps.

  • Alex

    11/2/2015 8:52:32 PM | Reply

    Many thanks for making easy for us newcomers to FO365 and Azure wordl Smile

    One question..if I would like to build SharePoint Online App that is hosted on SharePoint Online, is this the method that I would use to get access to all users data in Azure AD?

    Tnaks
    Alex

  • Adnan Khan

    11/5/2015 9:57:15 PM | Reply

    Hi Radi,  Great post.   Any idea if graph api can be used to query AD extension attributes.   I'm not seeing extension attributes in Graph Explorer.

  • Note

    4/27/2016 12:33:42 PM | Reply

    Thank you. This is the best article I found relating to the Graph API.

Add comment

Loading