Skip to main content

Single Sign-On (SSO)

Okareo Standalone authenticates browser users through your Identity Provider using OpenID Connect. Your IdP decides who gets in. Your IdP policies - MFA, conditional access, session rules - apply automatically. Okareo enforces them because it delegates to your IdP, not because it reimplements them.

Okareo supports any OIDC-compliant provider, including Microsoft Entra ID, Okta, and Google Workspace.

How it works​

After a successful OIDC login, Okareo creates a browser session backed by your IdP identity.

  • No pre-registration required: Okareo does not require pre-registering SSO users. Any user who can authenticate through the IdP can access the deployment on their first login.
  • Authorization: By default, any user assigned to the IdP application can access Okareo. You can optionally require a specific claim value in the ID token -- like a group or role -- so that only authorized users get a session.

Prerequisites​

Before configuring SSO, ensure you have:

  • Administrator access to your Identity Provider. You must be able to create a new OIDC application.
  • An existing Okareo Standalone deployment. You must be able to update configuration for the Okareo UI (frontend) and Okareo Services (backend API) components. Depending on your installation, these settings may live in a Docker environment, Helm values, Kubernetes Secret, or ConfigMap.
  • HTTPS configured on your deployment. OIDC providers require a secure https:// redirect URI for the callback. If you are deploying on Kubernetes, see Configure HTTPS / TLS Termination.

Setup Overview​

If your Okareo Standalone deployment is up and running, you can follow these steps to quickly enable SSO:

  1. Create an OIDC web application in your identity provider.
  2. Add this redirect URI: 
    https://<OKAREO_UI_HOST>/auth/sso/callback
  3. Copy the issuer URL, client ID, and client secret from the IdP.
  4. Set the Okareo UI environment variables.
  5. Set the Okareo Services environment variables.
  6. Restart Okareo UI and Okareo Services.
  7. Open Okareo UI and sign in with SSO.

Configuration Guide​

Step 1: Configure The IdP App​

Create an OIDC web application or confidential client in your IdP. See Provider Setup for step-by-step guides for Microsoft Entra ID, Okta, and Google Workspace.

Use these settings:

SettingValue
Application typeWeb application or confidential client
Grant typeAuthorization Code
PKCEAllowed or enabled
Client authenticationClient secret
Redirect URIhttps://<OKAREO_UI_HOST>/auth/sso/callback
Scopesopenid email profile

Copy these values from the IdP. You will use them in Okareo Services:

Okareo variableIdP value
SSO_ISSUER_URLOIDC issuer URL
SSO_CLIENT_IDOIDC client or application ID
SSO_CLIENT_SECRETOIDC client secret value

Do not register /v0/auth/sso/callback in the IdP. That is an Okareo API endpoint called by Okareo UI after the browser returns to /auth/sso/callback.

Step 2: Configure Okareo​

Set OKAREO_STANDALONE_AUTH_MODE=sso in both Okareo UI and Okareo Services.

The environment variables required for SSO are the same across all deployment types, but how you set them depends on your orchestrator.

For Kubernetes and Helm deployments, place these values in the chart locations used by your deployment:

  • Okareo UI values go on the frontend component (frontend.extraEnv).
  • Okareo Services values go on the services component (services.extraEnv).
  • SSO_CLIENT_SECRET belongs only in the services secret or services runtime environment.

For a Helm-oriented example, see Deploy Standalone on Kubernetes.

Okareo UI Environment​

Okareo UI needs the auth mode, browser-facing URLs, and the standalone tenant token used for Okareo API calls.

frontend:
  extraEnv:
    - name: OKAREO_STANDALONE_AUTH_MODE
      value: sso
    - name: OKAREO_AIRGAP_TENANTS
      value: '[{"id":"<TENANT_ID>","name":"<DISPLAY_NAME>","token":"<JWT>"}]'
    - name: OKAREO_API_GATEWAY
      value: "https://okareo.company.internal:8000"
    - name: OKAREO_APP_DOMAIN
      value: "https://okareo.company.internal"

Okareo Services Environment​

Okareo Services needs the auth mode, matching tenant IDs, the UI URL, and the OIDC client settings.

services:
  extraEnv:
    - name: OKAREO_STANDALONE_AUTH_MODE
      value: sso
    - name: OKAREO_AIRGAP_TENANTS
      value: '[{"id":"<TENANT_ID>","name":"<DISPLAY_NAME>"}]'
    - name: OKAREO_APP_DOMAIN
      value: "https://okareo.company.internal"
    - name: SSO_ISSUER_URL
      value: "https://login.microsoftonline.com/<ENTRA_TENANT_ID>/v2.0"
    - name: SSO_CLIENT_ID
      value: "<OIDC_CLIENT_ID>"
    - name: SSO_CLIENT_SECRET
      value: "<OIDC_CLIENT_SECRET>"
    - name: SSO_SCOPES
      value: "openid email profile"
    - name: SSO_SESSION_MAX_SEC
      value: "172800"
    # Optional override for split-subdomain deployments:
    # - name: SSO_COOKIE_DOMAIN
    #   value: ".example.com"

The tenant IDs must match between Okareo UI and Okareo Services.

The Okareo UI tenant entry includes the JWT token. The Okareo Services tenant entry does not include the token.

SSO authenticates the browser session. The standalone tenant token still authorizes Okareo API calls after login.

Step 3: Apply The Change​

Restart the Okareo UI and Okareo Services components to load the new environment variables. Since these are environment-only changes, you do not need to pull or deploy a new Okareo image.

Step 4: Verify SSO​

  1. Open the Okareo UI URL in a private browser window.
  2. Confirm Okareo redirects to /auth/sso/login.
  3. Click Sign in with SSO.
  4. Complete login with your identity provider.
  5. Confirm the browser returns to /auth/sso/callback.
  6. Confirm Okareo redirects into the app.
  7. Open a project page and confirm data loads.
  8. Sign out from Okareo and confirm you return to /auth/sso/login.

If login succeeds but project pages or API-backed views fail to load, check the tenant token configuration. SSO proves the user's identity. The standalone tenant token still authorizes Okareo API calls.

Provider Setup​

Microsoft Entra ID​

Use this path for Microsoft Entra ID, formerly Azure Active Directory.

  1. Open Microsoft Entra admin center.
  2. In the left sidebar, select App registrations (under Entra ID).
  3. Create a new registration for Okareo, or open the existing Okareo registration.
  4. From the app registration's Overview page, copy the Directory (tenant) ID and the Application (client) ID. You will need both below.
  5. Under Authentication, add a Web platform.
  6. Add this redirect URI: 
    https://<OKAREO_UI_HOST>/auth/sso/callback
  7. Under Certificates & secrets, create a client secret.
  8. Copy the secret Value immediately. Do not use the Secret ID.
  9. Under Token configuration, make sure users have an email claim available in the ID token or profile.
  10. Use this issuer URL format, replacing <ENTRA_TENANT_ID> with the Directory (tenant) ID from step 4: 
    https://login.microsoftonline.com/<ENTRA_TENANT_ID>/v2.0

Okareo values:

Okareo valueEntra value
SSO_CLIENT_IDApplication client ID
SSO_CLIENT_SECRETClient secret Value
SSO_ISSUER_URLhttps://login.microsoftonline.com/<ENTRA_TENANT_ID>/v2.0
Redirect URIhttps://<OKAREO_UI_HOST>/auth/sso/callback

If you want to restrict access by group or role, configure Entra to emit that claim in the ID token before you enable SSO_ALLOWED_CLAIM.

Okta​

Use this path for a custom Okta OIDC app integration. Pick the issuer based on whether you need group-based authorization:

  • Org authorization server (https://<your-okta-domain>) — basic SSO login.
  • Custom authorization server (https://<your-okta-domain>/oauth2/default) — required for SSO_ALLOWED_CLAIM group-based authorization. Custom servers expose the Groups claim builder and access policies the org server does not.

Create the app integration​

  1. Sign in to the Okta Admin Console.
  2. Go to Applications > Applications > Create App Integration.
  3. Choose OIDC - OpenID Connect, then Web Application.
  4. Name the app, for example Okareo Standalone.
  5. Under Grant type, enable Authorization Code (Okareo uses PKCE automatically).
  6. Add this sign-in redirect URI: 
    https://<OKAREO_UI_HOST>/auth/sso/callback
    For local testing, Okta also accepts an http://localhost:<port>/auth/sso/callback redirect URI. Non-localhost hosts must use HTTPS.
  7. Under Assignments, assign the app to the users who should reach Okareo (for example, Allow everyone in your organization). App assignment and the optional claim gate are independent controls.
  8. Save the app and copy the Client ID and Client secret.

Choose the issuer​

For basic login, use your org issuer:

https://<your-okta-domain>

For group-based authorization, use the custom authorization server issuer and complete the next section:

https://<your-okta-domain>/oauth2/default

Okareo values:

Okareo valueOkta value
SSO_CLIENT_IDClient ID
SSO_CLIENT_SECRETClient secret
SSO_ISSUER_URLOrg issuer, or the custom AS issuer for group auth
Redirect URIhttps://<OKAREO_UI_HOST>/auth/sso/callback

Group-based authorization (custom authorization server)​

Skip this section for basic login. To gate access by Okta group, configure the custom authorization server you set as SSO_ISSUER_URL.

  1. Go to Security > API > Authorization Servers > default.
  2. On the Claims tab, select Add Claim:
    • Name: a non-reserved name such as okareo_groups. Do not use groups — Okta reserves it and rejects the claim.
    • Include in token type: ID Token, Always.
    • Value type: Groups.
    • Filter: Starts with okareo (or Matches regex .* for all groups).
    • Include in: Any scope. The custom server has no groups scope, so leave SSO_SCOPES as openid email profile — do not add groups, or the authorize request fails with invalid_scope. The claim is emitted regardless of scope.
  3. On the Access Policies tab, make sure a policy applies to this app:
    • The policy must be assigned to All clients or include your app.
    • It must have a Rule that allows the Authorization Code grant for the intended users and scopes.
    • Without a matching rule, Okta returns 400 Bad Request / access_denied ("Policy evaluation failed") at login — see Okta access_denied.

Then set the gate on Okareo Services, using the claim name you chose:

SSO_ALLOWED_CLAIM=okareo_groups
SSO_ALLOWED_VALUES=okareo-admins

SSO_ALLOWED_VALUES matches Okta group names and is case-insensitive.

Google Workspace​

Use this path for Google Workspace or Google Cloud OAuth.

  1. Create an OAuth 2.0 client ID in Google Cloud.
  2. Choose Web application.
  3. Add this authorized redirect URI: 
    https://<OKAREO_UI_HOST>/auth/sso/callback
  4. Configure the consent screen for internal use if this deployment is for your organization only.
  5. Copy the OAuth client ID and client secret.
  6. Use this issuer URL: 
    https://accounts.google.com

Google's standard scopes are enough for basic login:

openid email profile

Custom OIDC Provider​

For any OIDC-compliant provider, confirm that:

  • OIDC discovery is available at <SSO_ISSUER_URL>/.well-known/openid-configuration.
  • The provider returns an ID token for Authorization Code flow.
  • The ID token audience matches SSO_CLIENT_ID.
  • The issuer in the token matches the issuer URL returned by discovery.

Optional Claim-Based Authorization​

By default, any user who can authenticate to the IdP application can complete Okareo SSO.

To restrict access further, configure Okareo Services to require a specific value in an ID token claim. Common claim names are groups, roles, or a custom claim configured in your IdP.

Example:

SSO_ALLOWED_CLAIM=groups
SSO_ALLOWED_VALUES=okareo-admins,ml-platform

Set these variables only on Okareo Services.

How matching works:

  • If SSO_ALLOWED_CLAIM is unset, claim-based access control is disabled.
  • If SSO_ALLOWED_CLAIM is set, SSO_ALLOWED_VALUES is required.
  • Values are trimmed, lowercased, and deduplicated before comparison.
  • The ID token claim may be a string or a list of strings.
  • Missing claims, empty claims, or malformed claim values are denied.
  • Denied users see an authorization error and no Okareo session is created.

Okareo evaluates these claims when the user completes the SSO callback. Changing claim settings does not revoke existing active Okareo SSO sessions. Existing sessions remain valid until logout, expiration, or manual session cleanup.

Before enabling this in production, decode a test user's ID token or inspect your IdP token preview to confirm the claim name and value are exactly what you expect.

User Provisioning And Lifecycle​

Okareo Standalone does not require an invite flow or pre-created Okareo user record for SSO browser login. The IdP application assignment and optional claim-based access policy decide whether a user can create an Okareo SSO session.

For onboarding, assign the user to the Okareo IdP application and, if claim-based access control is enabled, make sure the user's ID token emits one of the allowed values.

For offboarding, disable the user in the IdP, remove the user from the Okareo IdP application, or remove the group or role value required by SSO_ALLOWED_CLAIM and SSO_ALLOWED_VALUES. This blocks future SSO callbacks. Existing Okareo SSO sessions are not rechecked against the IdP on every request, so choose a session length that matches your organization's access policy.

This model keeps user lifecycle management in your IdP and avoids running SCIM or directory-sync infrastructure for standalone SSO login.

Optional Session Length​

Okareo SSO sessions default to 172800 seconds, or 48 hours.

Set this on Okareo Services to change the maximum session age:

SSO_SESSION_MAX_SEC=172800

Allowed values are 3600 through 604800, inclusive.

Shorter session lengths reduce the time between IdP-side access changes and the next required Okareo SSO login.

Use the same browser hostname for Okareo UI and Okareo API when possible. Different ports are fine.

When UI and API use sibling subdomains (for example app.example.com and api.example.com), Okareo Services infers a shared cookie domain from OKAREO_APP_DOMAIN and OKAREO_API_GATEWAY and applies it to SSO cookies. Inference uses the most specific shared suffix (.dev.example.com before .example.com) to avoid cross-environment cookie collisions.

If inference is not what you want, set an explicit override on Okareo Services:

SSO_COOKIE_DOMAIN=.example.com

Rules for SSO_COOKIE_DOMAIN:

  • Do not include scheme, path, or port.
  • Must be a real multi-label domain, not an IP address.
  • Must be a suffix of both OKAREO_APP_DOMAIN and OKAREO_API_GATEWAY hosts.

Troubleshooting​

Users Do Not See The SSO Login Page​

Likely causes:

  • OKAREO_STANDALONE_AUTH_MODE=sso is missing from Okareo UI.
  • Okareo UI was not restarted after changing the environment.
  • The user is opening an old or different UI host.

Fix:

  • Confirm Okareo UI has OKAREO_STANDALONE_AUTH_MODE=sso.
  • Confirm OKAREO_APP_DOMAIN is the URL users actually open.
  • Restart Okareo UI.

Standalone SSO mode not enabled​

The request reached an Okareo component that is not running in SSO mode.

Fix:

  • Set OKAREO_STANDALONE_AUTH_MODE=sso in both Okareo UI and Okareo Services.
  • Restart Okareo UI and Okareo Services.

Redirect URI Mismatch​

The redirect URI in your IdP does not exactly match Okareo's callback URL.

Check:

https://<OKAREO_UI_HOST>/auth/sso/callback

The scheme, host, port, and path must match exactly. If users open Okareo at a different host than OKAREO_APP_DOMAIN, the callback can fail.

Login Timed Out​

User-visible message:

Login timed out while signing in. Please try again.

Backend detail:

SSO login timed out. Please try signing in again.

Likely causes:

  • The user spent more than 10 minutes on the IdP login page.
  • The browser did not preserve the temporary login state.
  • The UI and API are on different hostnames, so the browser is not sending the SSO cookies where Okareo expects them.

Fix:

  • Start login again from /auth/sso/login.
  • Confirm OKAREO_APP_DOMAIN and OKAREO_API_GATEWAY are browser-reachable.
  • For sibling subdomains, verify inferred cookie domain is valid or set SSO_COOKIE_DOMAIN explicitly on Okareo Services.

Okta access_denied / Policy evaluation failed​

Okta error shown in the browser, before login completes:

400 Bad Request
Policy evaluation failed for this request, please check the policy configurations.
Error Code: access_denied

The custom authorization server in SSO_ISSUER_URL has no access policy rule that admits this app, so Okta rejects the authorize request.

Fix:

  • In Okta, go to Security > API > Authorization Servers > the server in your SSO_ISSUER_URL (for example default) > Access Policies.
  • Ensure a policy is assigned to All clients or to your Okareo app.
  • Ensure the policy has a Rule allowing the Authorization Code grant for the intended users and scopes.
  • This applies only to custom authorization servers (/oauth2/default). The org authorization server does not use access policies.

Failed SSO code exchange​

Okareo Services could not exchange the authorization code for tokens.

Likely causes:

  • Wrong SSO_CLIENT_ID.
  • Wrong SSO_CLIENT_SECRET.
  • Wrong SSO_ISSUER_URL.
  • Redirect URI mismatch.
  • IdP app is not configured as a web or confidential client.

Fix:

  • Re-copy the client ID and client secret from the IdP.
  • In Entra ID, use the client secret Value, not the Secret ID.
  • Confirm the issuer URL supports OIDC discovery.
curl https://<ISSUER_URL>/.well-known/openid-configuration

SSO token response missing id_token​

The IdP token response did not include an ID token.

Fix:

  • Confirm the app uses OIDC, not plain OAuth only.
  • Confirm openid is included in SSO_SCOPES.
  • Confirm the IdP app is allowed to issue ID tokens.

Invalid SSO ID token​

Okareo received an ID token but could not validate it.

Likely causes:

  • Token issuer does not match the discovered issuer.
  • Token audience does not match SSO_CLIENT_ID.
  • Token is expired.
  • IdP signing keys are unavailable.
  • The ID token is missing a required claim such as sub or nonce.

Fix:

  • Confirm SSO_ISSUER_URL is exactly the provider issuer.
  • Confirm SSO_CLIENT_ID matches the application that issued the token.
  • Confirm Okareo Services can reach the IdP discovery and JWKS URLs.

User not authorized for Okareo SSO​

The user authenticated successfully, but the optional claim-based access policy denied access.

Fix:

  • Confirm SSO_ALLOWED_CLAIM matches the claim name in the ID token.
  • Confirm SSO_ALLOWED_VALUES includes the user's claim value.
  • Confirm the IdP emits that claim in the ID token, not only in the access token or userinfo response.
  • Temporarily unset both variables to confirm the base SSO flow works.

Login Succeeds But API Calls Fail​

SSO and API authorization are separate.

Likely causes:

  • The Okareo UI OKAREO_AIRGAP_TENANTS value is missing the tenant token.
  • The tenant ID in Okareo UI does not match the tenant ID in Okareo Services.
  • OKAREO_API_GATEWAY points to the wrong API host.
  • OKAREO_API_GATEWAY uses a different hostname than the UI, breaking SSO cookie flow.
  • The standalone tenant token configuration is missing or does not match the deployment.

Fix:

  • Confirm the Okareo UI tenant JSON includes id, name, and token.
  • Confirm the Okareo Services tenant JSON includes matching id and name.
  • Confirm OKAREO_API_GATEWAY is the browser-reachable Okareo API URL.
  • If UI and API are sibling subdomains, verify SSO_COOKIE_DOMAIN (or inferred domain) covers both hosts.

Browser Returns To The Wrong Host​

OKAREO_APP_DOMAIN controls the browser callback URL and post-login redirects.

Fix:

  • Set OKAREO_APP_DOMAIN to the exact URL users use to open Okareo.
  • Set OKAREO_API_GATEWAY to the browser-reachable API URL.
  • If using split subdomains, ensure inferred cookie domain is correct or set SSO_COOKIE_DOMAIN on Okareo Services.
  • Use HTTPS for real users.
  • Restart Okareo UI and Okareo Services after changing these values.

Config Fails At Startup​

If Okareo Services reports:

Standalone SSO configuration invalid

Check these common causes:

ErrorFix
SSO_SESSION_MAX_SEC must be between 3600 and 604800Set a value from 1 hour to 7 days
SSO_ALLOWED_VALUES requires SSO_ALLOWED_CLAIMSet both variables or unset both
SSO_ALLOWED_VALUES must be set when SSO_ALLOWED_CLAIM is setProvide at least one allowed value
SSO_ALLOWED_CLAIM cannot be empty when setRemove the variable or set a real claim name
SSO_COOKIE_DOMAIN must not include scheme, path, or portUse domain only, for example .example.com
SSO_COOKIE_DOMAIN must be a multi-label domainUse at least two labels, for example .example.com
SSO_COOKIE_DOMAIN cannot be an IP addressUse DNS hostnames for split-subdomain cookie sharing
SSO_COOKIE_DOMAIN must not be a public suffixUse a specific parent domain, not .com or .co.uk
SSO_COOKIE_DOMAIN must be a suffix of OKAREO_APP_DOMAIN hostChoose a domain that matches your UI and API hosts

Security Notes​

  • Use HTTPS for any deployment accessed by real users.
  • Keep SSO_CLIENT_SECRET only in Okareo Services.
  • Treat the Okareo UI tenant JWT as a secret.
  • Use IdP application assignment or claim-based access control to limit which users can create Okareo SSO sessions.
  • Okareo logout clears the Okareo session. It does not guarantee that the user is signed out of the IdP.

For Kubernetes ingress TLS, see Configure HTTPS / TLS Termination.