Before starting
Make sure the client or supplier of the connection has received the “Azure AD – client manual”. They should perform the necessary steps before you are able to do anything. If they have followed the manual correctly, you should have received the following values from them:
- Client ID
- Client Secret
- Tenant ID
- Group ID
- Resource (only applies to v1 Graph API apps – this is not discussed in the client manual, so should be requested from client/supplier if v1 Graph API is used)
Necessary steps for setting up a Graph application
- On the navigation button, click on Setup (or alternatively, in the left menu, go to Admin > Setup)
- Locate the submenu “Applications”
- Click on “Create application”
- In the Application screen, fill in the necessary details. In the “Application” field, pick the Graph API app that you want to connect to. In this manual, we will follow the “Azure AD” application. If there is a situation in which a generic Graph API application is to be used, please select “Custom Graph application”. Steps 5 and 6 will be the same for those kinds of applications.
- Press on “Generate default key value pairs” (note that you can change the version of the Graph API here. Default is version 2. If version 1 is used, make sure to request the resource value from the client/supplier)
- Below the application, you will find the created key value pairs necessary for any Graph application, divided between production, backup and test. Please fill in the values that you have received from the supplier/client in necessary fields. The mapping is as follows:
a. client_id = Client ID
b. client_secret = Client Secret
c. scope = should be set to https://graph.microsoft.com/.default (unless client/supplier has indicated differently)
d. tenant_id = Tenant ID
e. resource = Resource (if version 1 is used)
To check if your values are correct and you can connect to the client/supplier Graph API, press on “Test connection”. This connection will try and obtain an access token. If this succeeds, the connection is established successfully.
- For the Azure AD, set “Enable GetUsers” to “yes”
After doing this, some new key value pairs are generated. Necessary and optional actions are:
a. GetUsers_defaultContactCategory – In the column “value”, enter the category reference that you want contacts to be created in
b. GetUsers_defaultGroup / GetUsers_defaultProfile – In the column “Related object”, select either the Group or Profile that you want users to receive
c. GetUsers_defaultUserType – In the column “Related object”, select the license type of the users being created
d. GetUsers_groupid – Fill with the Group ID that you received from the supplier/client
e. GetUsers_scheduledScript – Enter a custom script for when the data is retrieved. Only do this is you have custom work that needs to be done for the client
f. GetUsers_selectQuery – You can add a select query to limited/extend the fields that are retrieved for the users. This only applies for custom work that needs to be done for the client
- Next to the creation of the key value pairs, a scheduled script has been created. Make the necessary changes, but be sure to at least set the “Execute as” field.
- Optionally, you can set an archive limit. This is used to prevent massive removal actions, should anything be wrong with the retrieved data
Explanation of the Azure AD connection
When a user is created from the Azure AD connection, the most important part to be aware of is that the following fields are used to determine the Azure AD users:
- Contact.externalReference
- Contact.datasource
- SystemUser.datasource
- SystemUser.externalReference
So when this connection is used, the above fields cannot be used anymore for other purposes.
The scheduled script, which retrieves the active system users, does the following:
- Finds all the contacts that were created using this application based on the reference. The field uses is the datasource
- It marks all of the system users to be removed
- It then updates all the users that were retrieved through the API
- The users that were not updated (and are still marked) are removed (if the amount falls within the archive limit)
Setting the value for “GetUsers” to “no” results in the scheduled script being deactivated.
If something goes wrong with the connection, you can find an event log underneath the application. Here, the raw information returned by the webservice is placed, so it can be analyzed fully.
Custom possibilities for clients
If there is a necessity for custom logic in regards to the users, there are some scripts which can be used. Be aware: this list is not extensive. Search for SwbApplication for a list of all the scripts, and possibly search for a script which performs the necessary actions.
- SwbApplicationIsActiveInOperationMode – Script can be used to check if an application is active in the current operation mode or not
- SwbApplicationGraphAccessToken – Script is used to collect an access token. If none exists, or it is expired, a new one will be created. Script returns the access token for the Graph API
- SwbApplicationGraphGetWebservice - With this script, you can indicate which default Graph API webservice endpoint you want. For example, if you need to retrieve the GET endpoint, you can pass “GET”
- SwbApplicationGetKeyValuePairsMap – With this script, a map of all the key value pairs is returned. That way, values can be used when necessary
- SwbApplicationGraphUpdateUser – Using this function, you can create a node with which to update a user value in Graph API. Be aware, you need to be able to edit values in Azure, which requires different rights than those mentioned in the client manual
Limitations of the Azure AD connection
There are some limitations to the Azure AD connection:
- Groups within groups are currently not taken into account. Only users within the group are transferred
- Currently, the SKIM standard (for user provisioning) is not supported
- Just in time provisioning is not possible using this connection and will have to implemented separately