Authentication & SSO

UIGraph supports built-in email and password authentication alongside organization-scoped single sign-on. An organization can configure multiple OpenID Connect (OIDC), OAuth 2.0, and SAML 2.0 identity providers.

SSO providers are configured at runtime under Settings > SSO. Their configuration is stored in the UIGraph database, not in provider-specific environment variables.

Supported methods

Method	Status	Notes
Email and password	Active	Available as a fallback even when an organization has SSO providers.
OIDC / OAuth 2.0	Active	Generic OIDC, Microsoft Entra ID, Okta, and selected OAuth providers.
SAML 2.0	Active	SP-initiated login, SP metadata, signed assertion validation, and optional signed AuthnRequests.
LDAP	Not available	Configuration storage exists, but LDAP authentication is not implemented.
SCIM 2.0	Not available	User and group provisioning endpoints are not implemented.

note

UIGraph does not currently provide an enforced SSO-only mode. The password option remains available on the sign-in screen.

Forgotten passwords

A self-hosted installation has no self-service password reset. Selecting Forgot password? on the sign-in screen tells the user to contact their workspace admin, and no reset email is sent.

A server administrator sets a new password for the user instead. Send it to them over a channel you trust and ask them to change it after signing in.

Before configuring SSO

Prepare the following:

• An externally reachable HTTPS installation.
• A correct UIGRAPH_PUBLIC_URL. UIGraph derives OIDC callback URLs and all SAML service-provider URLs from it.
• A correct UIGRAPH_FRONTEND_URL when the browser-facing frontend differs from the public API base URL.
• An organization administrator account.
• A test user at the identity provider that will not lock the administrator out.

The API's general UIGRAPH_SECRET_KEY must already be configured. UIGraph uses that master key to encrypt OIDC client secrets and generated SAML SP private keys in the database. It is not an SSO-specific setting.

See SSO Security & Operations before enabling a provider for all users.

Organization-scoped providers

Every provider belongs to one organization and has a unique slug within that organization. The organization ID and provider slug are part of its public login URLs.

For an organization ID of <orgID> and a provider slug of <slug>:

Purpose	URL
Start login	${UIGRAPH_PUBLIC_URL}/api/v1/auth/orgs/<orgID>/login/<slug>
OIDC callback	${UIGRAPH_PUBLIC_URL}/api/v1/auth/orgs/<orgID>/callback/<slug>
SAML ACS	${UIGRAPH_PUBLIC_URL}/api/v1/auth/orgs/<orgID>/saml/<slug>/acs
SAML SP metadata	${UIGRAPH_PUBLIC_URL}/api/v1/auth/orgs/<orgID>/saml/<slug>/metadata

The provider detail screen displays the exact callback or SAML URLs to copy. Prefer those generated values over constructing URLs manually.

Provider slugs:

• Must contain 2 to 63 characters.
• May contain lowercase letters, digits, and single hyphens between words.
• Cannot be changed after provider creation.

Sign-in flow

The sign-in screen uses a three-stage flow:

1. The user enters an email address.
2. UIGraph finds organizations associated with the email's domain and existing organization memberships.
3. The user selects an organization when more than one is available.
4. UIGraph lists the enabled SSO providers for that organization.
5. The user chooses a provider or selects password login.

Organization discovery is rate-limited to 20 attempts per email address in a 15-minute window.

An organization discovery domain and a provider's allowed-domain list serve different purposes:

• The organization domain makes the organization discoverable from the initial email screen.
• Allowed domains restrict which returned identity-provider email addresses may complete login through a particular provider.

See Provisioning, Domains & Roles for account creation and authorization behavior.

OIDC and OAuth 2.0

UIGraph uses the authorization-code flow:

1. UIGraph creates a one-time login state with a 10-minute expiry and an OIDC nonce.
2. The browser is redirected to the provider's authorization endpoint.
3. The provider returns an authorization code and state to the organization-scoped callback URL.
4. UIGraph consumes the state, exchanges the code, checks the ID-token nonce when an ID token is returned, and requests the UserInfo endpoint.
5. UIGraph merges the returned claims and completes login using the configured email, name, subject, and groups claim names.

Supported provider types are:

Type	Use for	Configuration
entra	Microsoft Entra ID	Supply the tenant ID; UIGraph derives the endpoints.
okta	Okta	Supply the Okta domain; UIGraph derives the endpoints.
generic	OIDC and compatible OAuth providers	Supply authorization, token, and UserInfo endpoints.

GitHub can be configured as a generic provider even though it is not OIDC. If GitHub's profile response hides the user's email, UIGraph requests the primary verified address from /user/emails. This requires the user:email scope.

See OIDC & OAuth Provider Examples for complete configurations.

OIDC token validation limitation

UIGraph currently decodes ID-token claims and validates the nonce, but does not validate the ID-token signature, issuer, audience, expiry, or authorized-party claims. UserInfo claims overwrite claims with the same name, but role mappings can also reference other merged claims. Review the implications in SSO Security & Operations.

SAML 2.0

UIGraph acts as a SAML service provider and supports SP-initiated login:

1. UIGraph creates a one-time login state and SAML request ID with a 10-minute expiry.
2. The browser is redirected to the IdP using an HTTP-Redirect AuthnRequest.
3. The IdP posts the SAML response to the provider's ACS URL.
4. UIGraph validates the response signature, audience, time constraints, recipient, and request ID.
5. UIGraph reads the email, name, NameID, and mapping attributes before completing login.

IdP-initiated login and SAML Single Logout are not supported. See Configure SAML 2.0 for setup and troubleshooting.

Account and role handling

OIDC and SAML use the same completion flow:

1. The provider-returned email is normalized and checked against the provider's allowed domains.
2. UIGraph finds an existing account by email.
3. If no account exists, it is created only when Allow new users to sign up is enabled.
4. Role mapping rules are evaluated from top to bottom; the first match wins.
5. If no rule matches, the provider's default admin, editor, or viewer role is used.
6. Membership in the provider's organization is created or updated with sso as its source.
7. The provider subject or SAML NameID is stored as an identity link when available.

Role mappings are recalculated on every successful SSO login. They affect organization roles only; SSO mappings do not assign resource-specific permissions.

Sessions and logout

Both password and SSO login create a server-side session and an HttpOnly uigraph_session cookie:

• Sessions expire after 30 days.
• Cookies use SameSite=Lax.
• The Secure flag is enabled when UIGRAPH_PUBLIC_URL uses HTTPS.
• UIGRAPH_COOKIE_DOMAIN can scope the cookie across subdomains when required.

POST /api/v1/auth/logout deletes the current server-side session and clears the browser cookie. Logging out of UIGraph does not log the user out of the identity provider.

Current limitations

• Password login cannot be disabled per organization.
• Users cannot reset their own password. A server administrator has to do it for them.
• OIDC ID-token cryptographic and standard claim validation is incomplete.
• SAML login must be initiated from UIGraph.
• SAML Single Logout is unavailable.
• Organization discovery domains are not ownership-verified.
• LDAP authentication is unavailable.
• SCIM provisioning and deprovisioning are unavailable.
• Identity-provider deactivation does not immediately revoke an existing UIGraph session.
• UIGraph currently logs the complete set of attributes returned during SSO login.

Next steps

• Configure SAML 2.0
• OIDC & OAuth Provider Examples
• Provisioning, Domains & Roles
• SSO Security & Operations
• API Environment Variables