Skip to main content

OpenID Connect (OIDC)

The Hub can authenticate users through an external OIDC provider such as Azure Entra.

Provider Configuration​

Add a provider under Settings > Security > OpenID Connect (OIDC).

Required values:

  • Provider Name for display on the sign in screen
  • Authority URL, the provider's issuer URL, e.g. https://login.microsoftonline.com/<your tenant id>/v2.0
  • Client ID
  • Client Secret. Leave this empty only if your provider allows a public client using PKCE.
  • Redirect URI: <your hub UI url>/authentication/login-callback
  • OpenID Scopes, at a minimum openid

Optional values, under Advanced:

  • Discovery Endpoint, if the provider's metadata is not at <authority>/.well-known/openid-configuration
  • Authorize Endpoint and Token Endpoint, to override the endpoints published in the discovery document

The Hub reads the provider's endpoints, issuer and signing keys from its discovery document, so most providers need only the authority URL. For an Entra authority without the /v2.0 suffix, the Hub uses the v2.0 discovery document.

Sign in uses the authorization code flow with PKCE (S256), and the provider returns the code to the redirect URI in the query string. The Hub checks the ID token's signature, issuer, audience, lifetime and nonce against the discovery document. Earlier versions had Response Type and Response Mode settings. These are no longer used.

Sign-In Flow​

After a provider is configured, a user can sign in through that provider. The first sign-in creates a local account with no roles. An administrator then assigns Hub roles, and the user signs in again with the new permissions.

The account's username is taken from the email claim. If the token has no email, or another account already uses it, the preferred_username or upn claim is used instead. If none of these are available, the username is the provider ID and the user's sub claim (<provider id>:<sub>). An account with that form of username is given a proper one the next time a token with an email or sign in name arrives.

Disabling Username and Password Sign In​

Once OIDC sign in is working you can make it the only way in, so that built in username/password credentials cannot be used to bypass your identity provider.

Edit hubservice.json (C:\ProgramData\certify\hubservice.json or /usr/share/certify/hubservice.json) and set enablePasswordLogin to false:

  "AuthSettings": {
    "enablePasswordLogin": false
  }

With this set:

  • The Hub API rejects all requests to the username/password login endpoint.
  • The Hub UI sign in page detects this when it checks the configured providers, and shows only the single sign on buttons.

The setting is applied exactly as configured and is not re-enabled automatically when no OIDC provider is available, so configure and test at least one working OIDC provider before you disable password sign in. If you do lock yourself out, set the value back to true (or remove the section) and restart the Certify Management Hub service.

Azure Entra Example​

Azure Entra Application​

Create an app registration in the Azure portal:

  • App registrations > New Registration
    • Name e.g.: Certify Management Hub (Production)
    • Select account scope, generally Accounts in this organization directory only
    • Redirect URI:
      • Select "Web" as the platform type
      • https://<your hub UI url>/authentication/login-callback
    • Note the Application ID for use later.
  • Under Certificates & secrets
    • configure a new Client secret, note Client Secret value. Secrets expire, so keep this in mind if auth fails in the future.

Hub Provider Configuration​

  • Navigate to Settings > Security > OpenID Connect (OIDC)
  • Select Add OIDC Provider
    • General > Set a name for the provider, users will see this on the Sign In page and use it to select the provider as an option.
    • Configuration :
      • Authority URL which includes your tenant ID e.g. https://login.microsoftonline.com/abcd123-768f-4006-8891-0c85aecd9fd9/v2.0 (note: don't include the /oauth2/v2.0/... suffix from a typical API call).
      • Client ID (Application ID) and Client Secret, this is used to authenticate the confirmation code passed back by Entra after it has authenticated a user.
      • Redirect URI, which is the page on the hub to redirect to once Entra has completed its auth, the host/port of the URL varies depending on your hub configuration e.g. https://hub.yourcompany.com:8443/authentication/login-callback
      • Scopes: openid profile email - these determine what info is accessible about the user. Entra only includes the email claim for users with an email address (the mail attribute), so users without a mailbox, such as separate admin accounts, get their sign in name (UPN) as their username.
    • Advanced: leave the endpoints empty. They are read from the discovery document.

Multi-Tenant Authorities​

An authority of https://login.microsoftonline.com/common/v2.0 or https://login.microsoftonline.com/organizations/v2.0 accepts users from any Entra tenant your app registration allows. The Hub checks each token's issuer against the user's own tenant (the tid claim), but it does not restrict which tenants can sign in. To allow only your organization, use your tenant ID in the authority.

First Sign-In​

  • Reload the Hub UI and select the OIDC provider to sign in with, complete sign in as normal
  • Initially your account will have no roles:
    • Sign out of the hub and Sign In as Admin, assign a role to your account under Settings > Security > [Your new account] (people +) > e.g. Hub View (which has read only permissions), Administrator or Certificate Manager, then sign out.
    • Finally, sign in via the OIDC provider again.