Connecting Microsoft Azure AD / Entra ID to Q.wiki

Modified on Thu, 18 Apr 2024 at 11:49 AM

Attention: The following information and instructions are intended for IT professionals. They support the independent connection of Q.wiki to a Microsoft Azure Active Directory. These instructions correspond to the status as of 07.06.2022 and will not be updated with changes in Azure AD. If you are unsure, you can consult Microsoft instructions or the support of the Modell Aachen.

Limitations

With Mircosoft Azure AD, only individual users or group members can be synchronized.
Nested groups are not supported.
The Microsoft Azure AD must not be configured together with other providers (e.g. LDAP). Only the Topic Provider is always active and allows external users to register in Q.wiki.
Access to Q.wiki must be encrypted (HTTPS).
Once the Microsoft Azure AD is set up, there is no going back.
Each user must have a unique email address before the Microsoft Azure AD can be connected. The configuration dialog in Q.wiki will indicate if this requirement is not met. Via the User management in Q.wiki, the key user can change email addresses that have been assigned twice.
For security reasons, all synchronized user data has a length limit of 100 characters. Users who have a display name with more characters can therefore not be synchronized.
For customers with Q.wiki Enterprise and Employee application, the Microsoft Azure AD connection only provides the following user data:
- email
- givenName
- sn
- telephoneNumber
For Q.wiki 6.3, the following attribute is needed additionally:
- department
Plase read the section Set up provisioning on how to add this attribute.

Migration of existing Topic/LDAP users

When Azure AD is connected, the users provisioned in it are automatically migrated to the users existing in Q.wiki with a matching email address. The migrated users are updated with the data from Azure AD and managed through it from that point on.

Migrated users can log in using the Use Company Login button. Logging in with username and password is no longer possible.

Setting up a "contingency account"

In the case of an azure failure or an expired azure token, only manually administrated accounts are able to login in Q.wiki. We recommend adding a manually created user to the KeyUser group to be able to access Q.wiki and change the token. This account needs a valid email address and may not be provisioned to Q.wiki via azure, so an impersonalized address like "service@" or "it-support@" works best. If your token is already expired, please read this article: 401 Unauthorized when logging in

Connecting the Azure AD

Important: Key user rights are required in Q.wiki to perform the following steps.

In Q.wiki, open the user management under the Key User tools.
Select Connect Azure Active Directory from the three-item menu.
The configuration dialog opens (will be needed later).
Create a new Enterprise Application in Microsoft Azure AD.
Under All Services, select All.
Click on Enterprise applications.
Under Manage, select All Applications and click New application.
Select Create your own application.
Enter the name of the app and select Non-gallery.
Click Create.

Set up provisioning

Select Provisioning in the app you have created.
Click Get started.
Set Provisioning Mode to Automatic.
Enter Tenant URL (copy from configuration dialogue into Q.wiki, see above).
Enter Secret Token (generate and copy from configuration dialogue in Q.wiki).
Click Test Connection and check successful connection.
Click Save.
If Azure AD was not previously set up to provision groups, the Enabled switch for group provisioning must be activated under Mappings.
Under Settings and Notification Email, enter the person responsible who is to be notified in the event of synchronization problems.
Update website.
For Scope, the option Sync only assigned users and groups must be explicitly selected.
Set Provisioning Status to On.
Click Save.
Under Mappings click on Provision Azure Active Directory Users.
Under Attribute Mappings, all attributes that are sent to Q.wiki are listed. The default setting should already include all attributes necessary for Q.wiki. Below are listed the attributes that are used by Q.wiki. All other attributes can be deleted without hesitation.
The attributes name.givenName, name.familyName and phoneNumbers[type eq "work"].value are optional. They are only used in Q.wiki Enterprise for display in the employee profiles application.
For Version 6.3 the attribute department must be added, if it has been deleted during setup. By default, department is already listed.
Users and groups are added under Users and groups. If all users are to be provisioned, the default group All users can be used. Beware: Groups may only be used with P1 or P2 Plan. The free AD plan does not allow to use groups.

Set up authentication

Select All services and then Azure Active Directory.
Choose App registrations.
Choose All applications.
Select the previously created application for Q.wiki.
Copy the Application (client) ID and enter it in the configuration dialog in Q.wiki.
Copy the Directory (tenant) ID and enter it in the configuration dialog in Q.wiki.
Select Authentication from the menu on the left.
Select Add a platform.
Choose Web application.
Copy Redirect URI from Q.wiki configuration dialog and enter it here.
Click Configure.
Select Certificates & secrets.
Click New client secret.
Enter Description.
Click Add.
Copy the value of the generated secret and paste it into the Q.wiki configuration dialog.
Caution: Please make sure to copy the value and not the secret ID.
In the Q.wiki configuration dialog, click on Save.
Select API permissions.
Click Add a permission.
Select Microsoft Graph.
Choose Delegated permissions.
Under OpenId permissions select email, openid and profile.
Click Add a permission.
Click Grant admin consent and confirm with Yes.

After 40 minutes at the latest, the Microsoft Azure AD imports the users into Q.wiki.