OpenFrame Documentation
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
Flamingo Raises $4.5M Seed Round · Led by Vertex Ventures, bringing total funding to $6.7M to build the open, AI-native layer for IT and security.
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
Authentication And Sso Flows is the browser-facing portion of the OpenFrame authorization server that supports tenant discovery, password registration and recovery, invitation acceptance, and provider-based single sign-on. It is supplied by the com.openframe.oss:openframe-authorization-service-core library at version 7.0.11 and runs in this repository through the openframe-authorization-server service.
The module separates flow initiation from OIDC callback completion. Controllers validate requests and establish a short-lived, signed flow cookie. After the identity provider returns, SsoFlowSuccessHandler selects the handler whose stored state matches the returned OAuth state. The selected handler either binds an existing account to the authenticated server session, creates an account, or pauses at a consent screen before creation.
| Capability | Entry points | Primary components |
|---|---|---|
| Tenant and email discovery | GET /tenant/discover, GET /tenant/email-available, GET /tenant/email-domain-allowed |
TenantDiscoveryController |
| Password tenant registration | POST /oauth/register |
TenantRegistrationController |
| Invitation registration | POST /invitations/accept |
InvitationRegistrationController |
| Password reset | POST /password-reset/request, POST /password-reset/confirm |
PasswordResetController |
| SSO provider discovery | GET /sso/providers/invite, GET /sso/providers/registration |
SsoDiscoveryController |
| Email-less provider login and signup | GET /oauth/login/sso, GET or POST /oauth/login/sso/complete |
SsoLoginController, LoginSsoHandler |
| Invitation SSO and consent | GET /invitations/accept/sso, GET /oauth/join/pending, GET /oauth/join/complete |
InvitationRegistrationController, InviteSsoHandler, SsoJoinController |
| Callback dispatch and identity hardening | OIDC authentication-success callback | SsoFlowSuccessHandler, MicrosoftLoginEmailGate, SsoIdentityCapture |
The endpoints listed here are implemented by the library code, not independently reimplemented by the tenant repository. OAuth authorization endpoints, token issuance, signing keys, dynamic clients, and tenant-context filters are configured by adjacent authorization-server components and are outside this module’s direct scope.
flowchart LR
Browser["Browser or Mobile Client"] --> Gateway["OpenFrame Gateway"]
Gateway --> AuthServer["Authorization Server"]
AuthServer --> Discovery["Discovery and Registration Controllers"]
AuthServer --> SsoStart["SSO Start Controllers"]
SsoStart --> FlowCookies["Signed Flow Cookies"]
SsoStart --> Provider["OIDC Provider"]
Provider --> SuccessHandler["SSO Flow Success Handler"]
SuccessHandler --> InviteHandler["Invite SSO Handler"]
SuccessHandler --> LoginHandler["Login SSO Handler"]
SuccessHandler --> PlainLogin["Tenant Scoped Login"]
InviteHandler --> JoinGate["SSO Join Consent Gate"]
LoginHandler --> JoinGate
InviteHandler --> Session["Authorization Server Session"]
LoginHandler --> Session
JoinGate --> Session
PlainLogin --> Session
AuthServer --> IdentityStore["Users Tenants and SSO Identity Links"]
Session --> Continue["OAuth Continue Redirect"]
At deployment, the gateway maps the /sas/** route to the authorization server. The module therefore receives its browser-facing requests through the platform gateway, while its library classes use authorization, tenant, user, invitation, SSO configuration, and identity services to read and modify persisted platform state.
TenantDiscoveryController lowercases the supplied email before tenant lookup. Availability first checks for an active account, avoiding an unnecessary external disposable-domain check when the address is already taken. The separate domain-policy endpoint evaluates only email policy, enabling immediate UI feedback.TenantRegistrationController registers a tenant then signs its owner into the authorization-server session when the active owner can be found. This allows continuation without a second login, while email verification remains a subsequent process.InvitationRegistrationController provides both JSON invitation acceptance and an SSO initiation endpoint. Before SSO initiation it clears authentication state and competing SSO flow cookies, writes the invitation flow cookie, and redirects to provider authorization.PasswordResetController delegates reset-token creation and password replacement to PasswordResetService. A reset request returns 202 Accepted; confirmation returns 204 No Content.SsoDiscoveryController exposes the effective providers for an acceptable invitation’s tenant, or the system defaults when a person is beginning tenant registration.SsoLoginController starts an email-less SSO login under the onboarding pseudo-tenant. It uses an of_sso_login cookie to preserve provider, OAuth state, redirect target, and mobile context across the redirect. Its pending endpoint reads the identity from the authenticated authorization-server session, or an opaque signup ticket for mobile.SsoFlowSuccessHandler is the callback router. It compares the returned OAuth state with each active flow handler’s expected state. If no flow is active, it applies the Microsoft email gate, optionally auto-provisions a plain tenant-scoped login, preserves the normal Spring Security success behavior, captures an Apple web token where applicable, and records a trusted federated identity link. A stale, tampered, or replayed flow clears SSO cookies and uses the standard authorization error responder.InviteSsoHandler completes invitation acceptance using provider-supplied identity data. It can defer new-member creation to the join consent gate, binds the resulting platform user to the active SSO session, and clears the invitation flow cookie only after successful completion.LoginSsoHandler completes email-less provider login. It gives an existing subject link precedence over the provider email claim, requires trusted email routing for first association, refuses the generic provider if a tenant has its own provider application, checks that the tenant is active, and only then persists the identity link and binds the session.SsoJoinController exposes a pending view and a consent-required completion endpoint for invitation and shared-domain auto-provisioning. It reads identity only from the authenticated OIDC session and rejects consent completion unless agreeTerms is true.MicrosoftLoginEmailGate is an optional defense for generic Microsoft tenant-scoped login. A tenant-owned Microsoft application is accepted as authoritative. For a generic application, an existing subject link to the same tenant and email is sufficient; otherwise, the configured email trust policy must verify the routing claim. The gate is intentionally disabled by default pending correct xms_edov claim configuration.SsoIdentityCapture records subject-to-user links only after a successful tenant-scoped login with a positive trust signal: a tenant-specific provider application or a provider claim accepted by the email trust policy. Capture is best effort and cannot change the login result.sequenceDiagram
participant User as User
participant Browser as Browser
participant Auth as Authorization Server
participant IdP as OIDC Provider
participant Handler as Login SSO Handler
participant Store as User and Tenant Services
User->>Browser: Choose SSO provider
Browser->>Auth: GET /oauth/login/sso
Auth->>Auth: Create login flow cookie
Auth-->>Browser: 303 provider authorization redirect
Browser->>IdP: Authenticate
IdP-->>Auth: Authorization callback with state
Auth->>Auth: Match state to login flow handler
Auth->>Handler: Handle authenticated OIDC session
Handler->>Store: Look up subject identity link
alt Existing linked identity
Store-->>Handler: Platform user
else First association
Handler->>Handler: Require trusted provider email
Handler->>Store: Find active user by email
end
Handler->>Store: Validate provider and tenant status
Handler->>Store: Persist subject identity link
Handler->>Auth: Bind platform user to session
Auth-->>Browser: Redirect to OAuth continue
The handler’s decision order is security-sensitive:
of_sso_login payload, obtains the provider identity, and requires an email.For an unrecognized, trusted provider identity, the continuation differs by client type:
openframe.sso.login.signup-continue-url is configured, the handler redirects to that configured continuation page. If it is blank, the flow fails with an account-not-found error./oauth/signup-continue with the ticket and encoded redirect target. The mobile client can retrieve pending identity information using GET /oauth/login/sso/pending?ticket=... and completes tenant creation using POST /oauth/login/sso/complete.The ticket completion endpoint ignores identity fields supplied by the client. It reads email, names, provider, subject, and verification status from the pending ticket; it requires only the ticket plus tenant name and domain from the request. A ticket already bound returns the same tenant identifier, while actual ticket redemption and single-use enforcement occur at token minting.
flowchart TD
Start["Invitation SSO Request"] --> Clear["Clear Prior Authentication State"]
Clear --> Cookie["Write Invitation Flow Cookie"]
Cookie --> Provider["Redirect to OIDC Provider"]
Provider --> Callback["Authentication Success Callback"]
Callback --> Match{"State Matches Invite Flow?"}
Match -->|"no"| Reject["Clear Flow Cookies and Return Error"]
Match -->|"yes"| NewMember{"New Member and Join Gate Enabled?"}
NewMember -->|"yes"| Stamp["Stamp Invitation ID in Session"]
Stamp --> Confirm["Redirect to Join Confirmation"]
Confirm --> Consent{"Terms Accepted?"}
Consent -->|"no"| Stop["Reject Completion"]
Consent -->|"yes"| Create["Create Invited User from Session Identity"]
NewMember -->|"no"| Create
Create --> Bind["Bind Platform Principal to SSO Session"]
Bind --> Continue["Clear Cookie and Continue to Tenant"]
The invitation start endpoint clears authentication state and other SSO flow cookies, validates the invitation request through SsoInvitationService, stores its signed payload in of_sso_invite, and issues a 303 See Other provider redirect.
For a new member, InviteSsoHandler can defer creation when openframe.sso.join-confirm-url is set. It records the invitation identifier in the server session before redirecting to the confirmation UI. SsoJoinController requires that the invitation cookie identifier matches the session stamp before it displays data or creates the account. This prevents a session from completing a stolen, stale, or unrelated invitation cookie. It also obtains email, names, and picture from the authenticated OIDC session rather than browser input.
Existing invite recipients, or environments without a join confirmation URL, proceed immediately. The handler creates the invited user according to the invitation, including the requested tenant switch behavior, binds that user as the session principal, and redirects through OAuth continuation.
A provider callback that has no active invitation, registration, or email-less login flow is treated as an ordinary tenant-scoped SSO login. The success handler applies this sequence:
MicrosoftLoginEmailGate when its feature flag and provider conditions apply.SsoOidcUserService.autoProvisionForTenantLogin for eligible tenant-scoped login.SsoIdentityCapture determines the login had a positive trust signal.A callback with a flow cookie but no handler matching the returned state is never downgraded to a plain login. The module removes flow cookies and reports an expired-session error instead.
| State or data | Authority | How this module uses it |
|---|---|---|
| OAuth state and flow context | Signed SSO flow cookie | Selects the callback owner and carries provider, redirect, and mobile metadata. |
| OIDC subject, email, names, picture, claims | Authenticated authorization-server OIDC session | Creates or identifies users after provider authentication. |
| Invitation identifier | Flow cookie plus server-session stamp for consent flow | Identifies the invitation and binds a consent completion to the initiating session. |
| Signup ticket | Server-side SignupTicketService state |
Transfers pending mobile signup identity without depending on browser-session cookies. |
| Platform user and tenant | User, invitation, tenant, and registration services | Determines account ownership, tenant membership, status, registration, and session principal. |
| Provider configuration | SSOConfigService |
Discovers effective providers and distinguishes tenant-owned provider apps from generic apps. |
| Federated identity link | SsoIdentityService |
Makes provider subject the preferred future lookup key once the association is trusted. |
Controllers use bean validation for JSON bodies, model attributes, and email parameters. Controller initiation paths catch broad flow failures where a browser redirect is expected and route them through AuthErrorResponder, preserving the error code for the frontend flow. In contrast, JSON/XHR-style pending endpoints report expired session conditions as 409 Conflict, allowing the client to present an error before returning to login.
Notable response behavior includes:
POST /password-reset/request returns 202 Accepted.POST /password-reset/confirm returns 204 No Content.POST /invitations/accept and POST /oauth/register return 200 OK with the created domain object.GET /oauth/join/complete requires a top-level navigation because successful completion redirects to /oauth/continue.| Configuration | Effect |
|---|---|
openframe.sso.join-confirm-url |
Enables the consent-page redirect for new invitation members and, with the login flag, shared-domain auto-provisioning. |
openframe.sso.login.join-confirm-enabled |
Enables the join confirmation diversion for email-less shared-domain first login only when the join confirmation URL is also configured. |
openframe.sso.login.signup-continue-url |
Enables web continuation into tenant registration for unknown email-less SSO identities. |
openframe.sso.microsoft.require-verified-email |
Enables verified-email enforcement for generic Microsoft tenant-scoped login. It should be activated only after the required provider claim is present in issued tokens. |
Maintain the following invariants when changing this module:
The authorization-server application in this repository assembles the library implementation. The source code documented above is maintained in OpenFrame OSS Library: