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.

The following documentation relates to the connector available from Version 3.0.1332

Previous versions used resource rather than scope and you can use the V1 Endpoints from Azure AD with the earlier releases.

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 redirect URI.

The Redirect URI 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.

Click Create once you are done.

Set the Permissions

Now we need to set the permission levels we want our application to have. To do this go to API Permissions and click onto Microsoft Graph (1) to edit the permissions.

At a minimum you will need read and write access to any object you want to return or edit, and the offline_access permission. 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 Update Permissions to apply them.

Note: If you are not an admin user, you will need to have certain permissions approved by an admin user before you will be able to access those objects.

Get the Client Secret (App Key)

Now we need to get the client secret to do this go to Certificates & Secrets and then New client secret. Then type in a name for the secret, for example DataSync and set an expiry as required. Click Add to add create the secret.

This will then generate you client secret. Make sure to take a copy of the value as it will not be shown again.

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

Gather the Data for the Connection

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

Client ID - You can find this on the overview page of the app.

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

Token Endpoints - This can be found by clicking onto Endpoints on the overview page, and then copying the OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2).

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 Authorisation Code to return a code and 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 and 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 reopen your saved connection and click Get Authorisation Code under the OAuth2 section of the window. This will refresh your connection and apply the permissions.

If you are not an admin user, you may not have permission to view the objects you are trying to view. If you are trying to access your contacts for example you can add me/{entity} to the ServiceAppendURL property in the propety window.