Documentation

English

Français

English

Français

Introduction / Objective ​

This guide explains how to use Microsoft Entra ID groups to manage permissions in Wikit by leveraging App Roles. The principle:

  1. The client creates App Roles in the Entra ID "Wikit" application.
  2. The client assigns groups to these App Roles in "Enterprise applications".
  3. Entra ID automatically returns the roles in the roles claim of the OpenID Connect token.
  4. Wikit/IAM maps this claim to Wikit roles/groups.

This method is suitable for multi-tenant SaaS as App Roles are portable and application-specific.

Prerequisites ​

  • Entra ID administrator rights allowing application management (e.g., Cloud Application Administrator).
  • Wikit application already created in Entra ID (see Wikit/Entra OIDC SSO guide).
  • Redirection URL provided by Wikit, in the format: https://auth.wikit.ai/realms/{realm}/broker/{slug-organization}/endpoint
  • One or more existing Entra ID groups, containing the users to be authorized.
  • Entra ID P1/P2 license required if you assign groups to an application.

Client-side Steps (Microsoft Entra ID) ​

Steps 1 to 6 below complete your existing SSO procedure. If the Wikit application is not yet created, first follow the "OpenID Connect Configuration with Microsoft Entra ID" guide.

Step 1: Access the Azure Portal ​

  1. Log in to the Azure portal.
  2. Navigate to App registrations.

Step 2: Open the Wikit Application ​

  1. In App registrations, select the Wikit application you created (e.g., Wikit - {slug-organization}).

Step 3: Create App Roles ​

  1. In the application menu, click on App roles.

  2. Click on Create app role.

  3. Fill in the fields:

    • Display name: Readable name of the role (e.g., Wikit Admin).
    • Allowed member types: Users/Groups (mandatory for assigning groups).
    • Value: Technical value sent in the token (e.g., wikit_admin, wikit_editor, wikit_viewer).
    • Description: Short description (e.g., "Wikit administrator access").
    • Do you want to enable this app role?: Yes.

  4. Click on Apply.

  5. Repeat for each necessary role.

Reasonable assumption: Value values will be used as-is on the Wikit side. If you want a different nomenclature, provide a mapping table to Wikit (see dedicated section).

Step 4: Assign Groups to App Roles ​

  1. In Azure, go to Enterprise applications.
  2. Select the corresponding Wikit application.
  3. Menu Users and groups.
  4. Click on Add user/group.
  5. In Users and groups, select the group to associate.
  6. In Select a role, choose the App Role created in Step 3.
  7. Click on Assign.

Repeat for each group ↔ App Role pair.

Step 5: Verify that roles is emitted ​

As soon as an App Role is assigned to a user (directly or via group), Entra ID automatically adds a roles claim to the OIDC token.

You can verify this by performing a test connection and inspecting the ID token (using a tool like jwt.ms).

Connection Test ​

  1. Add a test user to a group assigned to an App Role.
  2. Connect to Wikit via Entra ID.
  3. Verify that:
    • the user can access Wikit,
    • the permissions correspond to the expected role.

If necessary, Wikit can validate the presence of the roles claim in IAM after connection.

Troubleshooting / Common Errors ​

The roles claim is missing from the token ​

  • No App Role is assigned to the user / group. → Check Enterprise applications > Users and groups. oai_citation:7‡Microsoft Learn
  • The App Role was created with Allowed member types = Applications only. → Recreate the role with Users/Groups.

Wikit permissions do not match ​

  • Incorrect Value communicated or mapped. → Verify the exact technical value of the App Role.
  • A user belongs to multiple groups assigned to different App Roles. → The token contains multiple values in roles. Wikit will apply all or a priority based on your configuration.

Group changes are not taken into account ​

  • Roles are recalculated at each authentication. → Ask the user to log out / log back in.

Points of Attention ​

  • Value Stability: Prefer generic and durable Values (e.g., wikit_admin) rather than organization-specific names.
  • Fewer Roles = Better: A simple hierarchy limits ambiguous combinations.
  • Access Management: Assigning groups to the Wikit application also controls visibility in "My applications".
  • Do not use acceptMappedClaims or advanced transformation policies for a multi-tenant app, unless explicitly needed.