Skip to main content

Federated Single Sign-On

OSIE's built-in identity service supports federated Single Sign-On out of the box: each identity realm can connect its own OpenID Connect providers, with no additional infrastructure to deploy. That is configured from the admin dashboard — see Login options & identity providers.

This page covers a different possibility: delegating an entire portal surface — the client portal, the admin portal, or both — to a single external OpenID Connect provider, configured at deployment time. In that mode OSIE acts purely as a relying party of that provider:

  • Users, credentials, login pages, registration and multi-factor authentication are held and served by the external provider.
  • It applies platform-wide for the delegated surface: every user authenticates against the one configured issuer, and the platform operates with a single realm. Per-customer realms, per-realm identity providers, per-realm login pages and sign-up policies, and realm linking are not available on a delegated surface.
  • The client portal and the admin portal are configured independently, so one can be delegated while the other uses the built-in identity service.

This fits deployments where a central identity provider already governs all users and OSIE should not keep any identity state.

Federate customers with realms, not with the client portal

We recommend delegating only the admin portal, and keeping the client portal on OSIE's identity service. A customer that brings its own identity provider gets a realm with that provider attached, which is configured from the admin dashboard and takes effect immediately. Delegating the client portal makes one external issuer the only way any customer signs in: per-customer providers, per-realm login pages and sign-up policies, realm linking, and OSIE's own registration, password recovery, two-factor and passkey flows all stop being available, and every change becomes a redeployment.

Option 1: With Keycloak​

This configuration deploys Keycloak alongside OSIE using the Keycloak chart from Bitnami. Keycloak will be automatically available at auth.osie.mycompany.com.

values.yaml
global:
  ingress:
    enabled: true
    # Keycloak will be deployed automatically at: auth.osie.mycompany.com
    # You can change keycloak domain by setting: "keycloak.ingress.hostname"
    hostname: "osie.mycompany.com"
    ingressClassName: "nginx"
    annotations:
      # kubernetes.io/ingress.class: nginx
      cert-manager.io/cluster-issuer: letsencrypt
      # Required by Keycloak when using Nginx ingress
      nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
    tls: true

With this configuration:

  • Keycloak is deployed as part of the Helm release and manages all user accounts.
  • The ingress for Keycloak is automatically configured at auth.<your-hostname> (customizable via keycloak.ingress.hostname).
  • You can use Keycloak to federate with your existing login systems (SAML2, LDAP, Active Directory) and enable social logins (Google, Facebook, GitHub, etc.).

Upgrading or reconfiguring​

When upgrading, it is recommended to prevent the keycloakConfigCli from running again, since it is only needed during the first installation.

values.yaml
keycloak:
  keycloakConfigCli:
    enabled: false

Option 2: External OpenID Connect Provider​

If you have an existing OpenID Connect provider (e.g., Okta, Auth0, or your own Keycloak instance), you can configure OSIE to use it directly. Each portal surface is configured separately, so the admin portal can be delegated while the client portal keeps using OSIE's identity service.

values.yaml
# Admin portal
admin:
  oauth2:
    issuerUri: "https://auth.mycompany.com/realms/my-admin-realm"
    clientId: "osie-admin"

# Admin API (/admin_api/v1), when you call it with tokens from the same provider
adminApi:
  oauth2:
    issuerUri: "https://auth.mycompany.com/realms/my-admin-realm"
    clientId: "osie-admin-api"

# Client portal — see the recommendation above before delegating this surface
ui:
  oauth2:
    issuerUri: "https://auth.mycompany.com/realms/my-realm"
    clientId: "osie-ui"

With this configuration:

  • OSIE delegates authentication for the configured surfaces to your external OpenID Connect provider.
  • A surface with no issuerUri continues to authenticate against OSIE's identity service.
  • global.oauth2.issuerUri sets one issuer for all surfaces at once, and takes precedence over the per-surface values.
  • The client used for each surface must exist in your provider, with the redirect URI of that portal registered on it.

Which roles an administrator receives from the incoming token is configured with admin.oauth2.rolesClaim and admin.oauth2.roleMappings — see Admin portal with Microsoft Entra ID for a complete example.

If your provider presents a certificate signed by a private CA, add that CA to the API's trust list as described in Custom CA certificates. Otherwise the API cannot fetch the provider's signing keys and every sign-in fails.

For delegating just the admin portal to Microsoft Entra ID — including the app registration walkthrough and role mapping — see Admin portal with Microsoft Entra ID.