Set up OIDC SSO with Microsoft Entra ID

This guide walks you through configuring Microsoft Entra ID (formerly Azure AD) as the OIDC identity provider for Gluesync CoreHub. It covers the app registration process in the Azure portal, token configuration for proper user mapping, and the corresponding CoreHub configuration.

For the underlying OIDC concepts, see OIDC (OpenID Connect) Authentication.

Before you begin

You need:

  • An active Microsoft Entra ID tenant.

  • Administrative access to your Entra ID to create app registrations and enterprise applications.

  • Administrative access to your Gluesync CoreHub.

  • The HTTPS URL of your Gluesync instance (referred to below as https://gluesync.example.com).

High-level flow

  1. Register a Web application in Entra ID.

  2. Configure optional claims to ensure Gluesync can read the user’s email or username.

  3. Create App roles in Entra ID (or use Groups).

  4. Assign these roles to your users via Enterprise Applications.

  5. Configure OIDC in Gluesync CoreHub, mapping the Entra ID roles to Gluesync’s MANAGER and VIEWER roles.

Step 1 — Register the application in Entra ID

  1. Log in to the Azure Portal and go to Microsoft Entra ID → App registrations.

  2. Click New registration.

  3. Enter a name (for example, Gluesync CoreHub).

  4. Under Supported account types, choose the appropriate option for your organization (typically "Accounts in this organizational directory only").

  5. Under Redirect URI:

    • Select the platform: Web (this is mandatory for the Authorization Code Flow with PKCE).

    • Enter your callback URL: https://gluesync.example.com/oidc/callback.

  6. Click Register.

  7. On the app Overview page, note down the Application (client) ID and the Directory (tenant) ID. You will need these later.

  8. Go to Authentication. Under Redirect URIs, add a second URI of type Web: https://gluesync.example.com/ui/v2/login. Entra ID uses registered Web redirect URIs as the allowlist for post_logout_redirect_uri. CoreHub always sends this URI after logout. You do not need to set Front-channel logout URL for this flow, and Gluesync does not have a Signout URL field.

  9. Go to Certificates & secrets → New client secret. Add a description, choose an expiration, and click Add. Copy the Value of the secret immediately.

Register a new Application

Step 2 — Configure token claims (Important for Usernames)

By default, Entra ID might only send a unique alphanumeric string (the sub claim) to identify the user. To ensure Gluesync displays a readable username or email, you must expose optional claims.

  1. In your App registration, go to Token configuration.

  2. Click Add optional claim.

  3. Select ID token.

  4. Check the boxes for email and upn (User Principal Name).

  5. Click Add. (If prompted to turn on Microsoft Graph email permissions, accept it).

Step 3 — Define roles in Entra ID

Entra ID separates App Roles from Directory Groups. The recommended approach for Gluesync is to use App roles.

  1. In your App registration, go to App roles.

  2. Click Create app role.

  3. Create a role for your managers:

    • Display name: Gluesync Manager

    • Allowed member types: Users/Groups

    • Value: gluesync.manager (this is the exact string Gluesync will read).

    • Description: Manager role for Gluesync.

    • Check Do you want to enable this app role? and click Apply.

  4. Repeat the process to create a viewer role (e.g., Value: gluesync.viewer).

App Roles Overview App Roles Context

Using Groups instead of App Roles: If your organization prefers using Directory Groups ("Add groups claim"), you can do so. In Token configuration, select Add groups claim → Directory roles or Security groups. If you choose this path, you must change the roleClaimPath in Gluesync to groups (instead of roles) and map the Group Object IDs or names in the CoreHub Role Mappings.

Step 4 — Assign roles to users

  1. Go back to the main Entra ID menu and navigate to Enterprise applications.

  2. Search for and select your Gluesync CoreHub application.

  3. Go to Users and groups → Add user/group.

  4. Select the users you want to grant access to.

  5. Click Select a role and choose either the Gluesync Manager or Gluesync Viewer role.

  6. Click Assign.

Step 5 — Configure OIDC in Gluesync CoreHub

SUPER ADMIN Role Limitation By design, Gluesync allows only one SUPER ADMIN user in the entire platform. Because of this architectural rule, it is not possible to map the SUPER ADMIN role via OIDC. You must map your Entra ID roles exclusively to the MANAGER or VIEWER roles.

  1. Log in to CoreHub as the local admin user.

  2. Go to Settings → OIDC Authentication.

  3. Fill in the configuration:

Field Value

Enable OIDC

toggle on

Provider Name

Entra ID

Issuer URL

https://login.microsoftonline.com/{your-tenant-id}/v2.0 (replace {your-tenant-id} with the Directory ID from Step 1)

Client ID

from Step 1

Client Secret

from Step 1

Redirect URI

https://gluesync.example.com/oidc/callback

Scopes

openid, profile, email

Role Claim Path

roles (or groups if you used the Groups approach in Step 3)

Default Role

VIEWER

Auto-provision Users

on

Role Mappings

 
{
  "gluesync.manager": "MANAGER",
  "gluesync.viewer": "VIEWER"
}

Troubleshooting

The username appears as a strange string of characters

The strange string is the Entra ID internal sub identifier.

Fix: Ensure you completed Step 2 (adding email and upn to the Token configuration) and that your Gluesync OIDC Scopes include openid, profile, and email.

Stuck on a Microsoft error page after Logout

  • Cause: The app registration does not include the exact URI CoreHub sends as post_logout_redirect_uri.

  • Solution: In the app registration, go to Authentication and add https://gluesync.example.com/ui/v2/login as a Redirect URI of type Web. Gluesync does not take a custom Signout URL; it uses the Entra ID discovery end_session_endpoint and always redirects to /ui/v2/login.

Users receive VIEWER instead of the MANAGER role

This usually happens due to a mismatch in the role configuration:

  • If you used App roles, verify that the Role Claim Path in Gluesync is exactly roles, and the mapping keys perfectly match the Value you defined in Entra ID (e.g., gluesync.manager).

  • If you used Add groups claim, ensure the Role Claim Path in Gluesync is set to groups, and that your JSON mapping uses the exact Group names or Object IDs injected by Microsoft into the token.

  • Check if the user was actually assigned the role in the Enterprise applications menu (Step 4).