Login and Identity
Goal
The login flow in soha is split into two layers:
- Local username and password sign-in
- Aggregated sign-in across multiple third-party identity providers
Supported third-party login provider types:
oidcfeishudingtalkwecomoauth2saml
The design goal is not merely to support a single enterprise SSO integration, but to allow the console to hold multiple enterprise identity entry points simultaneously and display enabled providers side by side on the login page.
Configuration Model
The backend settings service aggregates login configuration under identity.login_providers, containing:
providers[]defaultProviderId
Each provider entry includes at least:
idnametypeenabledredirectUrlfrontendRedirectUrl
For OAuth/OIDC-style providers, it also includes:
clientIdclientSecretissuerorauthorizeUrltokenUrluserInfoUrlscopesdefaultRolesuserIdFielduserNameFieldemailFieldroleFieldorganizationFieldsyncRolesOnLoginsyncOrgsOnLoginroleSyncModeorgSyncMode
Login-Time Role and Organization Mapping
Runnable OIDC, OAuth2, Feishu, DingTalk, and WeCom providers support supplemental bindings at login time:
roleFieldreads external role references from ID token claims or the userinfo/profile responseorganizationFieldreads external organization references from ID token claims or the userinfo/profile responsesyncRolesOnLogincontrols whether local role bindings are supplemented after a successful loginsyncOrgsOnLogincontrols whether local organization bindings are supplemented after a successful loginroleSyncModeandorgSyncModesupportappendandreplace_external
append only adds the local role or organization bindings resolved during the current login. replace_external clears external-source bindings previously written by the same provider before writing the newly resolved bindings; it never deletes local bindings manually maintained by administrators on the Users page.
Role resolution matches only existing local roles.id or roles.name records. Organization resolution matches only existing local organizations:
teams.idteams.slugteams.org_pathteams.sourceequals the provider type or provider ID andteams.external_idequals the external organization reference
Login callbacks do not automatically create local organizations or roles. Administrators must first build the organization tree under Organization Structure and populate the corresponding source and external ID for third-party organizations. Separating real-time directory synchronization from login-time authorization mapping prevents the login flow from acting as an implicit master-data import.
Application credentials such as Feishu, DingTalk, and WeCom App Key, App Secret, CorpID, and CorpSecret belong to the login provider application configuration under Login Settings, not to organization nodes. Organization nodes store only the mapping source and third-party department/organization ID; when multiple applications of the same provider type are configured, the organization source should reference the specific login provider ID rather than only the generic feishu, dingtalk, or wecom type.
Directory synchronization
Directory connections are separate from login-time role and organization mapping. Feishu connections configured as scheduled_and_realtime accept verified contact events and apply a single-object delta from the event payload. When the payload does not contain enough current data, Soha fetches only the referenced department or person instead of pulling the complete directory snapshot. Duplicate deliveries are idempotent, and older events do not overwrite a newer projection.
Scheduled or manually triggered full reconciliation remains the drift-repair fallback. Unsupported or incomplete events mark the connection as requiring reconciliation; they do not trigger a full snapshot for every webhook.
For a departure or user deletion event, Soha removes the memberships owned by that directory source. With userDisablePolicy: managed_only, it also disables an account managed by the connection and revokes its active sessions. With userDisablePolicy: never, it leaves the account enabled and removes only the directory-owned memberships. Missing or deleted organizations are archived rather than hard-deleted.
The directory connection console shows callback configuration and verification, recent queued or failed events with retry controls, the last incremental and full reconciliation times, and whether full reconciliation is required. Feishu directory events are currently supported; DingTalk and WeCom still rely on scheduled or manual full synchronization.
SAML login sources persist and use these runtime fields:
metadataUrlentityIdcertificate
The server publishes SP metadata and an ACS endpoint, then validates signatures, InResponseTo, timing, audience, recipient, and assertion replay. Imported login sources remain disabled until an operator verifies the metadata and certificates.
Configuration Source
The sole Settings configuration source for login providers is identity.login_providers.
Current rules:
- Settings maintains login providers through
/settings/identity/providers - Legacy single-OIDC setting keys are no longer read or written
- No default login provider is projected from legacy OIDC configuration
- Deleting a login provider retains existing account identity links, while disabling sign-in through that entry point
Rationale:
- Avoid generating a
defaultOIDC login provider from empty configuration - Keep a clear boundary between external login providers used to sign in to Soha and the Provider workbench
Runtime Flow
Browser Sessions and Token Storage
The browser console follows a BFF-oriented session model:
accessTokenis kept only in frontend memory forAuthorization: Bearer ...on regular API requestsrefreshTokenis written by the backend as anHttpOnlycookie; the frontend neither persists nor reads the refresh token/api/v1/auth/refreshaccepts an empty body, reads the session from the refresh cookie first, and renews the refresh cookie/api/v1/auth/logoutclears the refresh cookie; frontend sign-out must call this endpoint before clearing local state- Local development proxies
/api/v1same-origin through the Vite/apiproxy by default so the refresh cookie is not dropped on cross-site requests
After a page reload, when no in-memory accessToken is present, protected routes call the refresh endpoint to restore the session first and redirect to the login page only if recovery fails.
OIDC Provider sessions
The OIDC Provider in the internal workbench is the protocol surface through which Soha issues identities to downstream applications. It is separate from external login providers managed in Settings. It supports:
authorization_codeandrefresh_tokengrants- opaque Refresh Tokens when the client enables
refresh_tokenand the authorization request includesoffline_access - one-time Refresh Token rotation; reuse revokes the complete token family and OIDC Session
- binding Access Token, UserInfo, Introspection, and Proxy Session validity to the originating Soha Session
- effective Access Token and Refresh Token revocation through
/oauth2/revoke - RP-initiated logout through
/oauth2/logoutwithid_token_hint,post_logout_redirect_uri, andstate
Only Refresh Token hashes are persisted. A post_logout_redirect_uri must exactly match a Redirect URI registered for the client.
Browsers cannot reliably attach an Authorization header to native WebSocket, EventSource, or noVNC connections. Before opening a Pod logs stream, Pod terminal, virtualization operation stream, or VNC/noVNC session, the console exchanges the current session access token via POST /api/v1/auth/stream-ticket for a short-lived one-time ticket and passes stream_ticket in the same-origin stream URL query string. The server accepts only allowlisted paths; each ticket expires after 60 seconds, is strictly bound to its target path, and is consumed and deleted from PostgreSQL on first verification. After consuming the ticket, the server also validates session state and authz_version, ensuring role, organization, or account status changes still invalidate subsequent streaming connections.
Machine-to-Machine Calls and Runner Tokens
Browser sign-in and machine-to-machine calls follow distinct boundaries:
- The browser console uses Soha session access/refresh tokens, backed by server-side session state and
authz_versionso role, organization, and account status changes trigger refreshes - Direct API callers, CI runners, Docker runners, AI agent runners, and AI Gateway clients authenticate with Bearer tokens
- Long-lived machine tokens converge on the AI Gateway PAT/SAT model: only token hashes are stored, the principal is a user or service account, and access is constrained by
permissionKeysand scopes
During the transition, runtime.execution_runner_token remains supported for compatibility while external runner endpoints also accept service_account_token:
- Delivery execution runners require
delivery.execution-tasks.claim - Docker runners require
docker.operations.claim - AI agent runners require
ai.gateway.invokeorobserve.ai.chat
Task-scoped callback tokens are still verified by the owning execution task or agent run. A SAT only replaces the global shared entry token governing who may call claim/status/callback on a runner channel; it does not replace per-task replay protection or callback ownership checks.
1. Login Page Discovery
The login page first fetches /api/v1/auth/providers.
The response includes:
idtypenameenabledloginUrl
The frontend renders all enabled third-party login providers rather than filtering only for OIDC.
The login page also reads /api/v1/auth/login-options. When
auth.login_verification.slider_enabled is true in configuration, the frontend presents a slider interaction before password sign-in.
2. Browser Redirect
The sign-in entry point for each provider is:
GET /api/v1/auth/login/:providerID/start
The compatibility entry point is retained:
GET /api/v1/auth/oidc/login
3. Callback Handling
Unified provider callback endpoint:
GET /api/v1/auth/login/:providerID/callback
The compatibility OIDC callback endpoint is retained:
GET /api/v1/auth/oidc/callback
During callback handling, the backend:
- Validates
state - Resolves the provider type
- Exchanges the authorization code
- Fetches or constructs the user profile
- Links or creates a local user
- Writes
user_identities - Creates a session
- Generates a one-time exchange code
- Redirects back to
/login/callback?code=...
4. Frontend Session Exchange
The frontend callback page calls:
POST /api/v1/auth/oidc/exchange
This endpoint handles the final session exchange for all OAuth2-style login flows, not only OIDC.
Current Provider Status
OIDC
Fully operational.
- Discovers the issuer
- Exchanges the authorization code
- Validates the ID token
- Populates user attributes from claims or userinfo
Generic OAuth2
Fully operational when the operator configures valid:
authorizeUrltokenUrluserInfoUrl- Field mappings
Feishu
Uses the Feishu Open Platform authorization-code flow with its dedicated token exchange before fetching user profile information.
It requires the operator to verify:
- Application credentials
- Callback URL
- User profile field mappings
Default presets cover common endpoints and may require adjustment for specialized Feishu application types.
DingTalk
Uses OAuth2 authorization-code and access-token exchange, then fetches user information from the Open Platform endpoint accessible to the operator’s application.
Because user-profile APIs vary across DingTalk Open Platform application types, DingTalk is modeled as a configurable provider rather than hardcoding a single URL and field schema.
WeCom
WeCom does not follow a generic OAuth2 token-exchange flow.
The current implementation:
- Obtains
codevia web OAuth redirect - Fetches the enterprise access token on the server using the corp secret
- Exchanges
code + access_tokenforUserId
Accordingly:
tokenUrlpoints to the enterprise access-token endpointuserInfoUrlpoints to thegetuserinfoendpointclientIdmaps tocorpidclientSecretmaps tocorpsecret
By default, only the enterprise UserId is guaranteed; whether email or display name can also be populated depends on additional user-detail endpoints and field mappings configured by the operator.
SAML
The SP login flow is operational end to end.
- SP metadata:
GET /api/v1/auth/saml/:providerID/metadata - ACS:
POST /api/v1/auth/login/:providerID/acs - strict validation of signature algorithms and placement,
InResponseTo, Destination, Recipient, Audience, and time conditions - one-time assertion IDs and state consumption to prevent replay
- NameID and attribute mappings resolve into the same local user, role, and organization model
Metadata accepts only currently valid signing certificates. Rotate certificates before the previous certificate expires.
Provider workbench runtime boundary
Workbench providers are distinct from external login sources described above:
oidc: Soha acts as an OIDC Provider for downstream applications. The downstream application ownsstate,nonce, and PKCE; the workbench launches only its configured application URL.saml: Soha acts as a SAML IdP, publishes metadata and SSO endpoints, and applies application policy, MFA, and registered ACS restrictions.proxy: supports forward-auth and reverse-proxy. Reverse-proxy rejects private, loopback, and link-local targets by default; enableallowPrivateUpstreamonly for an intentional internal-service integration.
OIDC clients can combine strict redirect URI entries with RE2 regular expressions. Strict entries require exact equality; regular expressions are validated at configuration time and matched against the complete URI, not a substring. At least one strict or regular-expression entry is required.
SAML signing certificates can be rotated from the Provider workbench with a 0-30 day overlap. During overlap, metadata publishes the new active certificate and the retiring certificate so downstream service providers can refresh without downtime.
Provider secretRefs accept only soha://secrets/... references. Read APIs return configured aliases, never reference values. OIDC redirect URIs, SAML ACS URLs, and http.access_url support both HTTP and HTTPS so self-hosted operators can choose their transport boundary. HTTPS remains strongly recommended because HTTP exposes authorization codes, assertions, and session cookies to network interception. OIDC and SAML issuers use the configured access URL instead of trusting forwarded host/proto headers.
Audit and Local Identity Binding
Regardless of third-party provider type, all logins resolve into the same local identity model:
- Local
users - Local
roles - Local
sessions - Local
user_identities
When a third-party login succeeds:
- Looks up an existing binding by
provider_type + provider_id + provider_user_idfirst - Attempts to merge with an existing local user by the provider-returned email if no binding exists
- Creates a new local user if no match is found
- Assigns
defaultRoleswhen the user has no roles anddefaultRolesis configured on the provider - When
syncRolesOnLoginis enabled, bothdefaultRolesand roles resolved fromroleFieldare applied as external-source role bindings managed by that provider - When
syncOrgsOnLoginis enabled, organizations resolved fromorganizationFieldare applied as external-source organization bindings managed by that provider
The account-linking path does not independently check email_verified. Configure only providers that supply trustworthy email ownership; email-based linking does not mean Soha has independently verified that ownership.
Audit events are recorded uniformly by the platform; external providers supply identity assertions only and do not directly bypass local authorization.
Frontend and Permission Boundary
Login Settings is purely a configuration surface and does not bypass the platform permission model.
Access continues to require:
settings.identity.viewsettings.identity.manage
Visible menus, accessible routes, and invokable APIs after sign-in are still governed by the local permission snapshot and backend authorization checks rather than determined directly by an external IdP.