Graph API

Microsoft Graph API enables you to access Microsoft systems that may otherwise have been difficult to connect to such as Azure and Office applications (SharePoint, Exchange etc.) Below you will see a few walk through's of how to setup the graph API and then connect to your desired source in Data Sync.

Azure AD

Using the OData connector with Graph API we can connect to Azure AD. To do this we have a few things we need to setup first.

Create the App in Azure

Log in to your Azure account and go to Azure Active Directory > App Registrations > New Application Registration.

Now type in a unique name for the application and a sign on URL (this can be anything you like as it is not important for what we want our application to do) and leave the application type as Web app / API. Click Create once you are done.

The Sign-on URL here https://www.simego.com/oauth/code is defined to allow us to extract the authorisation code from the OAuth handshake. This is used when the OAuth authorisation flow is configured as authorization_code.

Set the Permissions

Now we need to set the permission levels we want our application to have, in the app details click Settings.

Then go to Required Permissions > Add > Select an API.

Choose Microsoft Graph and then click Select.

Now go to Select Permissions and choose the permissions for your application. At a minimum you will need read and write access to users profiles. However to view groups and other items you will need to extend these permissions to match your requirements. Check out the API Documentation to check what permissions you will need to set.

Once you are happy with the permissions click Select and then Done in the Add API blade.

To finish off registering the new app you will need to click Grant Permissions to apply the permissions you have just set.

Get the App Key (Secret Key)

Now we need to get the application key that will be the client secret. Go to Settings in the app details and then go to Keys.

Type in a description for the key, in this example we have used datasync. Then set the expiry date as required, we have chosen never expires.

Click Save and a new client secret will be generated.

NB: Make sure to make a note of the key once it has been generated as it will not be shown again. If you loose the key you will need to create a new key.

Gather the Data for the Connection

Now lets collect a few details that we will need for the connection:

App ID - This can be found by going to your app details.

Client Secret - This is the app key you made a note of earlier.

Resource - This will be: https://graph.microsoft.com.

Token Endpoint - This can be found by going to app registrations, choosing Endpoints, and then copying the OAuth 2.0 Token Endpoint.

Test the connection

To test the connection of the API returns an access token, we have used postman in the below example.

In postman we setup a POST API to the OAUTH 2.0 Token Endpoint. Which will look something like: https://login.microsoftonline.com/{AzureDirecotryID}/oauth2/token

Then under body, choose x-www-form-urlencoded and enter in the key values as below:

Now press Send, if an access token is returned the connection is successful.

Connecting in Data Sync

To connect to Azure AD with Data Sync choose the OAuth 4.0 Connector and enter in the following details:

1 - ServiceURL

The service URL for Graph API will be: https://graph.microsoft.com/v1.0

2 - OAuth2

Click on the three dots to open the connection window, and complete the required fields. Once you are done click Get Access Token to go back to the connection window.

3 - EntityURLItemConvention

Set this to be {entity}/{key} for Azure AD.

4 - Windows

Not used with OAuth authentication.

5 - Entity

Finally choose your entity from the drop down.

Click Connect & Create Library Connection to save your connection. You are now connected to Azure AD.

Troubleshooting

If you are having permission errors i.e. the error widow states 'Permission Denied' you will need to go back to your App and add permissions. Make sure to press Grant Permissions once you have made changes, and then reopen your saved connection and click Get Access Token under the OAuth2 section of the window. This will refresh your connection and apply the permissions.