If you’ve ever come across the problem of not being able to access certain information outside of sharePoint then you’ll probably need to take a look at Microsoft Graph, the multi-platform API repository for connecting all of Microsoft tenancy services together with other internal and external services.

Let’s take the scenario of needing to use an Active Directory security group for setting and obtaining permissions without wanting to use a SharePoint group, why would you not want to use a SharePoint group you say? Well, in most environments the Service Desk or Helpdesk will have access to update AD groups but not SharePoint groups; they will also probably already have procedures in place for updating security groups when on-boarding a new user or someone leaves, so using an AD group instead of a SharePoint group in a situation were the users will constantly be changing is more efficient as it allows greatly control for the Service Desk and less need to constantly update SharePoint groups.

So, in this scenario we have a SharePoint system setup for manage an award system in the company – we’ve called this system our “Executives Award for Recognition” in the previous tutorials. In this system we have it setup to send out an e-mail containing links to each nomination to allow the members of a company panel of staff members the ability to vote on each nomination.

Now we have previously been using a SharePoint group to send out the e-mail, but as we already have a distribution list for that group within Active Directory we want to instead connect to Azure Active Directory and pull out a list of users that are stored within that group – in this example the group we will be working with is “Staff Forum Member”

So first things first we need to setup a method of connecting to Azure, to do this we need to follow a few steps, first we need to setup an app within each tenancy we need access to – this will be the app we use to prove we have access to the tenancy and what level of access we have.

Note: you may need a domain admin to help with these steps depending on your level of access

Step 1 – Setup App in tenancy

1. Navigate to https://portal.azure.com
2.  Click on “Azure Active Directory” in the left menu
3. Click on “App registrations”
4. Click on “New application registration”

1. Give your app a name – this is just for your reference and to make it easy to identify what it is used for
2. As we are using a web API and not some software or services installed on a local machine we will be selecting “Web app / API” and not “Native”
3. If you had a login page you were using (especially in the case of native apps) you could specify that here, as we do not have anything point this to your SharePoint tenancy home page “https://tenancy.sharepoint.com”
4. Click on “Create”

NOTE: if you see the below error message then you will need to speak to a domain admin to have them setup the app for you as you do not have permissions to create app registrations

Step 2 – Grant permissions to App

1. In Azure portal go back in to App registrations via the Azure Active Directory menu and find the app you have just created and then click on the Display Name to open the menu for the app
2. We will need the Application ID later on, this is important but for now click on “Settings”
   
3. Click on “Required permissions” and then click on “Add” then click on “Select an API” now find the option “Microsoft Graph”
   
4. The next screen will ask you to set the permissions the app will need within Office Graph – in our situation we only need read-access to the Azure Active Directory service so we will choose the following options:
   1 – Read all users’ relevant people lists
   2 – Read all groups
   3 – Read directory data
   4 – Read all users’ full profiles
5. Now click “Save”

You may have noticed some of the options above say “Yes” with a tick under the column “Requires Admin”, this means an admin from the tenancy need to explicitly grant the app permission at least once to access those resources.

The easiest way to do this is to create a link that you can send the administrator to click on

Step 3 – Create a pass key (secret code)

Now we need to create a pass key that will be used as a password for our App to access our tenancy(s), so back in the Settings screen for the App click on “Keys”.

In the Passwords section enter the text client_secret in description field, in the expires field select a duration for how long this password will be valid for before a new key has be generated and then in the Value field enter a new password to use (recommend using a random password generator like the one KeePass provides) – MAKE A NOTE OF THIS PASSWORD AS YOU WILL NOT BE SHOWN IT AGAIN AND CANNOT RETRIEVE IT IF YOU LOOSE IT

Step 4 – Connect to OAuth service

Next we are going to use OAuth to setup a connection to the tenancy to obtain a token that we can use to gain temporary access to the Graph API (Full details of this is available here at Microsoft docs), this works by creating a handshake with the Office 365 authentication service passing a client_id and client secret (this will be explained in a moment) then using these credentials the Office 365 authentication service will check if we have permission to access the resource, and if we do then it will send us a token we can use for all subsequent requests to the graph service.

The following steps all involve sending and receiving http requests so you will need some software to do this, my two favourite ones to use are PostMan and Fiddler – I will be using Postman for this article

First we need a URL that we can send a POST request to to authenticate us against, this is in the format shown below:

https://login.microsoftonline.com/tenancyID/oauth2/token

Where can I get the tenancy ID from?

In Azure portal go back in to Azure Active Directory menu and then click on “Properties”, the tenancy ID is shown as “Directory ID” in the properties page and even has a handy copy button next to it

Second we will need to send some data in the body of the request, this will consist of four parameters

grant_type = this is always set to client_credentials as we are sending the credentials to be used
client_id = this is our unique App ID
client_secret = this is a unique pass key we previously created
resource = this is the service we are requesting the security access for

The format of the string is that shown below:

grant_type=client_credentials&client_id=YOURappID&client_secret=THISisTHEsecretPASSWORDinSTEP3=&resource=https://graph.microsoft.com

The headers will need to have the Content-type with the value application/x-www-form-urlencoded

[{“key”:”Content-Type”,”value”:”application/x-www-form-urlencoded”}]

Remember to set the HTTP request to POST, this is what Postman looks like:

Now click “Send” and if everything was setup correctly you will receive a 200 OK response with some token details as shown below