Connecting Microsoft Azure AD / Entra ID to Q.wiki

This guide is intended for IT professionals and supports the independent integration of Q.wiki with Microsoft Entra ID. If you have any questions, the documentation from Microsoft or Q.wiki Support can help.

Overview and Limitations

What This Guide Covers

This guide shows you how to connect Q.wiki to Microsoft Entra ID using SCIM (user synchronization) and OIDC (Single Sign-On). The process consists of two steps and must be performed in this order.

Important Limitations

• No nested groups: With Microsoft Entra ID, only individual users and groups can be synchronized. Nested groups (groups within groups) are not supported.
• SCIM + OIDC together: Setting up SCIM (user synchronization) is mandatory along with setting up SSO via OIDC (login). Separate configuration is not possible.
• No multi-provider operation: Microsoft Entra ID cannot be configured alongside other providers (e.g., LDAP). Manual user creation and management remains always active and allows you to register external users in Q.wiki.
• One Identity Provider per tenant: Only one Identity Provider and one tenant can be connected at a time.
• Email addresses must be unique: Each user must have a unique email address before Microsoft Entra ID can be connected. The configuration dialog in Q.wiki will notify you if this requirement is not met. You can change duplicate email addresses through user management in Q.wiki.
• Length restriction on user data: For security reasons, all synchronized user data has a length limit of 100 characters. Users with a display name longer than 100 characters cannot be synchronized.

Migrating Existing Users

When you connect Entra ID, existing Q.wiki users with a matching email address will be automatically migrated. These users will be updated with data from Entra ID and managed by Entra ID from that point on.

Migrated users log in using the Use corporate login button. Username and password login is no longer possible.

Setting Up an Emergency Account

If Entra ID malfunctions or the secret token expires, login is only possible through manually created Q.wiki accounts. For this reason, we recommend adding a manually managed account to the KeyUserGroup. This account must have a valid email address and must not be provisioned by Azure. An impersonal email address like "service@…" or "it-support@…" is suitable.

If the secret has already expired, read the article 401 Unauthorized error message when user logs in.

Step 1: Set Up User Synchronization with SCIM

SCIM ensures that users and groups from Entra ID are automatically created and updated in Q.wiki.

1. Open Microsoft Entra ID and create a new Enterprise Application.
   Important: Start with an Enterprise Application, not an App Registration!
2. Click Create your own application.
3. Enter the app name (e.g., "Q.wiki") and select Non-gallery.
4. Click Create.
5. Select Provisioning in the created app.
6. Click Get started.
7. Set Provisioning Mode to Automatic.
8. In Q.wiki, go to Tools > User Management and open Configure provisioning from the 3-dot menu.
9. Copy the Tenant URL from the dialog in Entra ID to Q.wiki and generate a secret.
10. Click Test Connection and save the settings after successful connection.
11. Enable group provisioning under Mappings.
12. Go to Settings > Notification Email and enter the email of the person responsible for receiving synchronization problem notifications.
13. Under Scope, you must explicitly select the option Sync only assigned users and groups (if available).
14. Set Provisioning Status to On and save.
15. Under Users and groups, you add users and groups. If all users are to be provisioned, you can use the default group All users.
    Important: Groups are only an option if you have an updated Azure Active Directory P1 or P2 tenant. The standard AD plan level only allows assignment of individual users to the application.
    

Users will be synchronized to Q.wiki within 40 minutes at the latest. You can proceed with Step 2 immediately – synchronization runs in the background.

Step 2: Set Up Single Sign-On with OIDC

With OIDC, provisioned users are automatically logged into Q.wiki if they are already authenticated with Entra ID or Microsoft 365. If not, they are automatically redirected to Microsoft 365 login.

1. In Q.wiki, go to Tools > User Management (Key User tools).
2. Open Connect Identity Provider (IdP) from the 3-dot menu and select Entra ID. The Q.wiki dialog will be filled during the Entra ID configuration.
3. Create a new App Registration in Entra ID.
4. Select All applications and open the Q.wiki application you created earlier.
5. Copy the Application (client) ID and Directory (tenant) ID and enter them in the Q.wiki configuration dialog.
6. Select Authentication from the left menu.
   • Click Add a platform.
   • Select Web application.
7. Copy the Redirect URI from the Q.wiki configuration dialog and enter it here.
8. Click Configure and then select Certificates & secrets.
9. Click New client secret, enter a description, and click Add.
   • Copy the Value of the generated secret and paste it into the Q.wiki configuration dialog.
     Important: Make sure to copy the value, not the secret ID!
     
10. Click Save in the Q.wiki configuration dialog.
11. Select API permissions.
    • Click Add a permission.
    • Select Microsoft Graph.
    • Select Delegated permissions.
    • Under OpenId permissions, select email, openid, and profile.
    • Click Add a permission.
    • Click Grant admin consent and confirm with Yes.
12. Provisioned users should now be automatically logged into Q.wiki.