Set up OIDC SSO with Keycloak

This guide walks you through configuring Keycloak as the OIDC identity provider for Gluesync CoreHub.

For the underlying OIDC concepts (claim path syntax, role mapping rules, login flow), see OIDC (OpenID Connect) Authentication.

Before you begin

You need:

  • A running Keycloak instance (this guide is verified against Keycloak 22+, but earlier versions with the same admin console flow work too — see the [legacy] note for pre-19 installs).

  • Administrative access to the Keycloak realm you want Gluesync to authenticate against.

  • Administrative access to your Gluesync CoreHub.

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

On older Keycloak versions (≤ 18), the admin console uses a slightly different UI and issuerUrl paths include /auth. The realm URL is https://keycloak.example.com/auth/realms/{realm-name} rather than https://keycloak.example.com/realms/{realm-name}. The setup steps below otherwise apply.

High-level flow

  1. Create (or pick) the Keycloak realm Gluesync will authenticate against.

  2. Register a confidential client for Gluesync in that realm.

  3. Create realm roles (gluesync-admin, gluesync-manager, gluesync-viewer or whatever naming you prefer).

  4. Assign roles to your users.

  5. Configure OIDC in Gluesync CoreHub, using realm_access.roles as the role claim path.

Step 1 — Choose or create the realm

  1. Open the Keycloak admin console.

  2. In the realm switcher (top-left), either select an existing realm (for example master for testing, or your tenant realm) or create a new one via Create realm.

The realm name appears in the issuer URL:

https://keycloak.example.com/realms/\{realm-name}

This is the value you will use as issuerUrl in Gluesync (Step 5).

Step 2 — Register a client for Gluesync

  1. In the selected realm, go to Clients → Create client.

  2. General settings:

    • Client type: OpenID Connect

    • Client ID: gluesync-client (any value works; remember it for Step 5)

    • Click Next.

  3. Capability config:

    • Client authentication: on (this makes the client confidential and enables Client secret).

    • Standard flow: on (this is the Authorization Code Flow).

    • Direct access grants: off (not used by Gluesync).

    • Click Next.

  4. Login settings:

    Field Value

    Valid redirect URIs

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

    Valid post logout redirect URIs

    https://gluesync.example.com/ui/v2/login

    Web origins

    https://gluesync.example.com

    Root URL / Home URL

    https://gluesync.example.com (optional, useful for the account console)

  5. Click Save.

  6. Open the Credentials tab on the client page and copy the Client secret — you will paste it into Gluesync in Step 5.

Keep Standard flow on and Implicit flow off. Gluesync only supports the Authorization Code Flow with PKCE.

Valid post logout redirect URIs must include https://gluesync.example.com/ui/v2/login. CoreHub always sends that path as post_logout_redirect_uri after Logout. Gluesync does not take a custom Signout URL in Settings → OIDC Authentication; it uses Keycloak’s discovery end_session_endpoint automatically.

Without that exact URI on the Keycloak client, Keycloak rejects the logout redirect and the user is stuck on an identity-provider error page even though CoreHub has already ended the local session.

Step 3 — Create realm roles

  1. In the same realm, go to Realm roles → Create role.

  2. Create the roles you want to expose to Gluesync. A typical setup uses three roles:

    • gluesync-admin — will map to SUPER ADMIN.

    • gluesync-manager — will map to MANAGER.

    • gluesync-viewer — will map to VIEWER.

      Save each one.

You can also use client roles (defined on the Gluesync client itself instead of at the realm level). In that case the role claim path becomes resource_access.gluesync-client.roles instead of realm_access.roles. Realm roles are simpler and recommended for most setups.

Step 4 — Assign roles to users

  1. Go to Users, select (or create) the user that will log into Gluesync.

  2. Open the Role mapping tab → Assign role.

  3. Switch the filter to Filter by realm roles and select the role created in Step 3.

  4. Click Assign.

Step 5 — Configure OIDC in Gluesync CoreHub

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

  2. Go to Settings → OIDC Authentication.

  3. Fill in:

    Field Value

    Enable OIDC

    toggle on

    Provider Name

    Keycloak

    Issuer URL

    https://keycloak.example.com/realms/{realm-name} (use /auth/realms/{realm-name} on Keycloak ≤ 18)

    Client ID

    gluesync-client (from Step 2)

    Client Secret

    from Step 2

    Redirect URI

    https://gluesync.example.com/oidc/callback — must match Step 2

    Scopes

    openid, profile, email

    Role Claim Path

    realm_access.roles (or resource_access.gluesync-client.roles if you used client roles instead)

    Default Role

    VIEWER

    Auto-provision Users

    on

    Role Mappings

    		 
    {
  "gluesync-admin": "SUPER_ADMIN",
  "gluesync-manager": "MANAGER",
  "gluesync-viewer": "VIEWER"
}

  4. Click Save.

Equivalent REST API payload:

{
  "enabled": true,
  "providerName": "Keycloak",
  "issuerUrl": "https://keycloak.example.com/realms/your-realm",
  "clientId": "gluesync-client",
  "clientSecret": "your-client-secret",
  "redirectUri": "https://gluesync.example.com/oidc/callback",
  "scopes": ["openid", "profile", "email"],
  "roleClaimPath": "realm_access.roles",
  "defaultRole": "VIEWER",
  "autoProvisionUsers": true,
  "roleMappings": {
    "gluesync-admin": "SUPER_ADMIN",
    "gluesync-manager": "MANAGER",
    "gluesync-viewer": "VIEWER"
  }
}

Step 6 — Verify

  1. Log out of Gluesync (or open a new private browser window).

  2. Click Login with Keycloak on the login page.

  3. Authenticate with the test user.

  4. After redirect, you should land in CoreHub. Open Settings → User Management and confirm the user appears with an OIDC badge and the resolved role.

To double-check the resolution end to end, you can decode the MOLO17 session token (visible in the browser dev tools as a cookie, or in the response of the /oidc/callback?code=…​ request) and confirm the role claim. For example, a user with the gluesync-manager realm role should produce:

{
  "iss": "MOLO17",
  "sub": "your-username",
  "role": "MANAGER"
}

Using client roles instead of realm roles

If your operational model already groups roles per application using client roles, configure Gluesync as follows:

  1. In the Gluesync client, open the Roles tab and create the roles there (instead of in Realm roles).

  2. Assign these client roles to users from Users → Role mapping → Filter by clients → pick the Gluesync client.

  3. In CoreHub, set roleClaimPath to:

    resource_access.gluesync-client.roles

    Replace gluesync-client with the actual client ID you configured in Step 2.

If your client ID itself contains dots (for example com.example.gluesync), escape them with backslashes so the claim-path parser does not split them as nested segments:

resource_access.com\.example\.gluesync.roles

See the claim-path syntax reference for details.

Local development with self-signed certificates

The Gluesync Docker Compose kit ships a Keycloak instance with a self-signed certificate. When pointing CoreHub at it, enable the Skip TLS Verification toggle in Settings → OIDC Authentication → Advanced settings.

Never enable Skip TLS Verification in production. It disables all TLS certificate validation for the OIDC discovery, token-exchange, and userinfo calls.

Troubleshooting

Failed to fetch OIDC discovery document

Users receive VIEWER instead of the expected role

  1. Check the token contents. In the Keycloak admin console, open the Gluesync client → Client scopes → Evaluate, pick the test user, and click Generate. Inspect the generated ID token / userinfo: the role you assigned should appear under realm_access.roles (or resource_access.{client-id}.roles if you use client roles).

  2. Verify roleClaimPath matches what you saw in the previous step. A roleClaimPath of realm_access.roles cannot find a role that only exists at resource_access.gluesync-client.roles.

  3. Verify the mapping keys. roleMappings keys are compared case-insensitively, but the full string must match. gluesync-manager will not match gluesync_manager.

Failed to exchange authorization code

  • Re-check the Client Secret in CoreHub against the Credentials tab in Keycloak.

  • Confirm the redirect URI configured in Keycloak exactly matches the one CoreHub sends (including scheme, host, port, and /oidc/callback).

  • If you regenerated the client secret in Keycloak, you must update it in CoreHub.

Stuck on a Keycloak error page after Logout

  • Cause: Valid post logout redirect URIs does not include the exact URI CoreHub sends as post_logout_redirect_uri.

  • Solution: On the Gluesync client, add https://gluesync.example.com/ui/v2/login to Valid post logout redirect URIs. Gluesync does not take a custom Signout URL.

Roles in the token but still falling back to default

  • Open the Keycloak Client scopes tab on the Gluesync client and confirm the roles client scope is in the Default list. By default it is, but custom scope configurations sometimes remove it. Without the roles scope, Keycloak omits realm_access.roles from the token.

For more general troubleshooting, see the troubleshooting section of the main OIDC page.