1. Configuring Azure

1.1 Log in to Azure.

1.2 Select Azure Active Directory from Services list. You will be provided with an Azure AD overview.

1.3 Select Enterprise Applications item from the left navigation menu:

*You will be provided with an Enterprise applications overview.

1.4 Press the Create new application button located within the top menu:

*You will be redirected to Azure AD Gallery.

1.5 Press the Create your own application button located within the top menu:

*The Create your own application popup will appear.

1.6 Enter the name of your application and select Integrate any other application you don't find in the gallery (Non-gallery) from the corresponding radio list.
Then, press the Create button on the bottom:

*You will be redirected to the Application view.

1.7 Select the Single Sign-on from the left navigation menu.

*A page with SSO method selection will appear.

1.8 Click on the SAML box:

*You will be redirected to SAML setup page.

1.9 Download the http://app.qooling.com/saml/metadata file.

1.10 Press the Upload metadata file button located within the top menu and add the file downloaded in the previous step.

*A popup with Basic SAML configuration will appear. It will be pre-filled with data from the uploaded metadata.

1.11 Check that the data is filled like on the following screenshot and press the Save button:

Now you can close the popup. You will be presented with Azure SSO setup view. Leave it open and configure Qooling to use the Azure AD integration.

2. Setting up Qooling

2.1 Log in to Qooling.

2.2 Select Integration from the navigation menu on the left. An integration overview will be displayed.

2.3 Press the New integration button on the top. A New integration popup will appear.

2.4 Select the Azure AD SSO Integration box from the list:

An Azure AD integration configuration popup will appear.

2.5 Copy the App Federation Metadata Url from the Azure SSO setup view:

2.6 Now, paste the link inside the corresponding input of Qooling popup and press the Save button. Afterward, the configuration part is completed and you can start adding users to both Azure AD and Qooling.

3. Adding users to Azure AD

To provide your Azure AD users the ability to authenticate using Azure AD SSO, you must add the users from your directory to the newly created Enterprise Application.

To do that, you should go to your enterprise application overview page in Azure and do the following steps:

3.1 Select the Users and groups from the left navigation menu.

*User and groups overview page will be displayed.

3.2 Press the Add user/group button located within the toolbar on the top.

An add assignment page will be displayed.

3.3 On the add assignment page you can see the user selection list. Press the None selected link.

A user selection popup will be displayed on the right.

3.4 Select the users that you want to add to the enterprise application and press the Select button.

Now the add assignment page should look like this:

3.5 To finish the process, press the Assign button.

4. Adding an Azure AD user to Qooling

4.1 To create a user which can authenticate using Azure AD SAML SSO you should open New user popup on Configuration page and check the Azure AD user checkbox.

Use the email provided in corresponding Azure AD user credentials as a login.

4.2 Making existing user an Azure AD user

To give the user the ability to authenticate via Azure AD SAML SSO, you need to open the user details popup. Then, press the ‘Edit button’. At the bottom of the popup you will see the Azure AD user checkbox which must be checked to enable the SSO login:

After that, you can press the Save button.

5. Setting up Automatically Provisioning

5.1 Get the Application ID

5.2 Select Provisioning from the left navigation menu.

5.3  Select Get Started

5.4 Set Provisioning Mode to Automatic

5.5 Tenant URL must be https://app.qooling.com/scim/v2/{appId}. The {appId} must be the Application ID got in 5.1.

5.6 At Qooling > Integrations, select the Generate token button and copy the token.

5.7 Paste the generated token in Secret Token field in Azure and click Test Connection. If a success message appears then select the Save button.

5.8  Open Mappings tab

Groups are ready to be provisioned.

5.9 Select Provision Microsoft Entra ID Users

5.10 Remove the attributes except for userName, active, name.givenName, name.familyName.

5.11 Select Add New Mapping and fill the fields with:
Mapping type: Expression

Expression: SingleAppRoleAssignment([appRoleAssignments])

Target attribute: roles[primary eq “True”].value

Select Ok

5.12 If the HQ Company wants to add new or existing users to some subs companies, it must be mapped by urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization. 

Attention: If this field is mapped, all the users must have the companies' names in Azure because they will be removed from the sub-companies whose names are missing in Azure AD.

If the user must be in more than one company, the companies’ names must be separated by “,”, like the example:

Once the user is successfully added, they will be part of the HQ Company, Sub Company A, and Sub Company B.

5.13 If the company wants to add the user to some divisions, it must be mapped by urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division.

If the user must be in more than one division, the divisions’ names must be separated by “,”, like the example:

5.14 Save the Attribute Mapping

5.15 Back to Overview then select Start provisioning.

The Users were created in Qooling with their roles and groups. If a group does not exist in Qooling, it will be created. If a role does not exist in Qooling, it will be considered a Limited user.

Guide User in Qooling:

Azure Provisioning user in Qooling:

6. Creating Custom Attribute

Sometimes, the existing attributes in Azure are not enough, and a custom attribute is necessary. For example, if an HQ company wants to add some companies to the  user, the existing attribute in Azure only supports 64 characters. Sometimes, creating a custom attribute with a larger size is necessary. 

In the example in topic 5.12, "companyName" was used as the source attribute. To  use a custom attribute, you must create and inform it as the source attribute. 

There are a few ways to create or use other attributes. Below are the steps for  creating and using the custom attribute via Graph API: 

6.1 You need to make some requests to Microsoft's Graph API. To make this  process easier, there is Graph Explorer (https://developer.microsoft.com/en us/graph/graph-explorer). You can log in with the same account you use to manage  data in Azure AD. 

6.2 After logging in, you can make the first request to retrieve the IDs of the  applications registered in Azure: GET  

https://graph.microsoft.com/v1.0/applications. Look for the application named  "aad-extensions-app. Do not modify. Used by AAD for storing user data" and copy  the value of the "id" field. 

If you receive a 401 return on this or the next endpoints, go to the "Modify  Permissions" tab and grant the necessary consent. 

6.3 To create the new attribute, change from GET to POST and make a request to  https://graph.microsoft.com/v1.0/applications/{id}/extensionProperties. 

Remember to change {id} to the id value you found in the previous step. Also, in  "Request Body", paste the following information: 

{ 

 "name": "customCompaniesFieldName", 

 "dataType": "string", 

 "targetObjects": ["User"] 

} 

The "Name" should contain the name you want to assign to the custom attribute. The "dataType" is the field's type. For a text attribute, use "string."  

The "targetObjects" is a list of objects in which the attribute will be created. In our  example, it is in the user. 

The attribute will be created with the name “extension_{AppId}_{attributeName}”. 

6.4 To confirm the creation of the attribute, make a GET request to  https://graph.microsoft.com/v1.0/applications/{id}/extensionProperties. Always  remember to change {id} to the id copied previously.

6.5 To set the attribute value for a user, you first need to know the user's ID. If you  don't know it, you can find it by doing a GET to  

https://graph.microsoft.com/v1.0/users/ 

6.6 Make a PATCH request to https://graph.microsoft.com/v1.0/users/{userId}. In  the "Request Body", enter the name of the attribute created and the value you want  to assign: 

{ 

 "extension_appId_attributeName": "attributeValue" 

}

6.7 In provisioning mapping, using the custom attribute as the source is now  possible. 

If you want to use a custom attribute to inform the user's companies, remember to  use the target attribute "organization", as explained in topic 5.12, as shown in the  image above.