SSO Security & Operations

SSO depends on the public URL, reverse proxy, identity-provider configuration, database, and encryption key. Review this page before enabling a provider for production users.

Production checklist

• Serve UIGraph and all authentication callbacks over HTTPS.
• Set UIGRAPH_PUBLIC_URL to the exact externally reachable base URL.
• Set UIGRAPH_FRONTEND_URL when post-login navigation uses a different frontend origin.
• Set UIGRAPH_COOKIE_DOMAIN only when the session must be shared across specific subdomains.
• Configure the API's general UIGRAPH_SECRET_KEY and protect it as a production secret.
• Register only exact callback, ACS, entity ID, and metadata URLs displayed by UIGraph.
• Restrict new-user sign-up with provider allowed domains where possible.
• Use viewer as the default role.
• Test role mappings with non-administrator users before adding administrator mappings.
• Keep a working password administrator session during rollout.
• Back up the database and encryption key according to the same recovery policy.

Public URLs and reverse proxies

UIGRAPH_PUBLIC_URL is security-sensitive configuration. UIGraph uses it to build:

• OIDC callback URLs.
• SAML ACS URLs.
• SAML entity IDs and metadata URLs.
• The Secure behavior of the session cookie.

The URL must match what the browser and IdP use, including scheme, hostname, and any port. A mismatch can cause rejected callbacks, SAML audience failures, or cookies that are not marked secure.

Terminate TLS at the reverse proxy or load balancer and ensure the public route forwards /api/v1/auth/... requests to the UIGraph API. Do not expose an alternate unencrypted callback route.

UIGRAPH_FRONTEND_URL controls where the API sends the browser after successful authentication. It defaults to the public URL.

Secret storage

OIDC client secrets and SAML SP private keys are encrypted before database storage using the API's UIGRAPH_SECRET_KEY.

• OIDC client secrets are masked when provider configuration is returned.
• SAML SP private keys are masked when provider configuration is returned.
• The SAML public certificate is included in SP metadata.
• Changing or losing the master key prevents UIGraph from decrypting existing provider secrets and keys.

Treat the database and master key as separate sensitive backup materials. Restoring only the database without the matching key does not restore usable SSO credentials.

When rotating an OIDC client secret, enter the new value in the provider configuration and test it before invalidating the old credential where the IdP supports overlap.

UIGraph does not currently provide an automated SAML SP-key rotation workflow. Creating a new provider produces a new keypair and URLs based on its slug.

Login state protections

OIDC and SAML login initiation creates a random, one-time state record in the database:

• State expires after 10 minutes.
• Consuming state deletes it atomically so it cannot be reused.
• State is bound to the organization, provider, and protocol kind.
• OIDC state includes a nonce checked against a returned ID token.
• SAML state includes the AuthnRequest ID checked during ACS validation.
• An optional post-login redirect is restricted to a local path.

The state itself is not stored in a browser cookie.

OIDC token validation

UIGraph exchanges the authorization code directly with the configured token endpoint, then calls the configured UserInfo endpoint with the access token. When an ID token is present, UIGraph currently:

• Decodes its JWT payload.
• Requires its nonce to match the login request.
• Merges its claims with UserInfo claims.
• Lets UserInfo overwrite claims with the same names.

UIGraph does not currently validate the ID-token signature through JWKS or validate its issuer, audience, expiry, or authorized-party claims.

This is especially important for role mappings: a mapping can reference a custom claim that exists only in the decoded ID token. Until full validation is implemented, do not use an ID-token-only claim to grant admin or editor unless you have separately assessed and accepted the risk. Prefer authorization claims returned by the TLS-protected UserInfo endpoint.

Always use HTTPS identity-provider endpoints. Do not configure token or UserInfo endpoints controlled by an untrusted party.

SAML validation

UIGraph validates SAML responses with the configured IdP certificate and SP configuration, including signatures, audience, time constraints, recipient, and the stored AuthnRequest ID. The ACS requires the one-time RelayState created by UIGraph.

Operational recommendations:

• Import IdP metadata over HTTPS or paste reviewed metadata XML.
• Review metadata before trusting a new certificate or endpoint.
• Plan certificate rollover before the old IdP signing certificate expires.
• Test after changing the public URL, provider slug, certificate, NameID format, or attribute mappings.
• Do not enable IdP-initiated launch tiles; UIGraph requires SP-initiated state.

Sessions

Successful password and SSO authentication creates a server-side session and an HttpOnly cookie:

Property	Current behavior
Lifetime	30 days
SameSite	Lax
Secure	Enabled when UIGRAPH_PUBLIC_URL is HTTPS
Browser access	HttpOnly

Logging out deletes the current UIGraph session and clears its cookie. It does not terminate the IdP session or perform SAML Single Logout.

Disabling or deleting a provider does not automatically revoke sessions created through it. Disabling either the IdP account or UIGraph account also does not delete sessions already issued.

Disable the UIGraph account to prevent future login. The current product does not provide an administrator endpoint to revoke all sessions for a user, so an existing session can remain usable until logout or expiry. Include that limitation in urgent offboarding procedures.

Attribute and personal-data logging

The API currently writes the complete merged OIDC claims or SAML attributes to its structured log after successful SSO login. Depending on IdP configuration, these values can contain email addresses, names, group memberships, directory identifiers, and custom attributes.

• Restrict access to API logs.
• Apply retention appropriate for identity data.
• Avoid releasing unnecessary claims to UIGraph.
• Do not map or request sensitive directory attributes that authentication does not require.

Domains and sign-up

Organization discovery domains are syntax-checked but not ownership-verified. They help users find workspaces; they are not an authentication control.

Provider allowed domains are enforced against the returned email, but UIGraph does not independently verify an email_verified claim. Use an IdP and scope configuration that returns an email whose ownership the IdP has verified.

For public OAuth providers:

• Set an allowed-domain list before enabling sign-up, or disable sign-up.
• Confirm the provider returns the intended primary email.
• Avoid broad scopes unrelated to authentication.

Safe rollout

1. Create the provider with a non-administrator default role.
2. Restrict allowed domains or disable new-user sign-up.
3. Assign one test user at the IdP.
4. Keep the existing password administrator session open.
5. Test organization discovery and provider visibility in a private browser window.
6. Verify the returned email, created membership, and default role.
7. Add role mapping rules one at a time and retest.
8. Verify failure behavior for an unassigned user and a disallowed email domain.
9. Record recovery steps before expanding IdP assignment.

Backup and recovery

SSO provider records, mappings, organization domains, identity links, and pending login states are stored in PostgreSQL. OIDC secrets and SAML private keys in those records depend on UIGRAPH_SECRET_KEY.

Back up:

• PostgreSQL using your normal application backup process.
• The exact master encryption key through your secret-management process.
• IdP application configuration or infrastructure-as-code definitions.
• Current IdP signing certificates and rollover dates.

After a restore, test one password login and one login through each active provider before declaring authentication recovered.

Current security limitations

• OIDC ID-token signature and standard claim validation is incomplete.
• SSO attributes are logged in full.
• Password login cannot be disabled.
• Discovery-domain ownership is not verified.
• email_verified is not independently enforced.
• IdP-initiated SAML and SAML Single Logout are unavailable.
• Existing sessions are not automatically revoked when an IdP or UIGraph account is disabled, and administrators cannot currently revoke all sessions for a user.
• LDAP authentication and SCIM provisioning are unavailable.

See also

• Authentication & SSO
• Configure SAML 2.0
• OIDC & OAuth Provider Examples
• Provisioning, Domains & Roles
• Operations