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
Security And Tenant Context is the authorization server's request-bound security foundation. It runs in the OpenFrame Authorization Server service and is supplied by the com.openframe.oss:openframe-authorization-service-core library, version 7.0.11. The module resolves the active tenant before authentication, preserves that identity through clustered login flows, constructs tenant-specific OAuth and OpenID Connect behavior, and prevents tenant configuration from leaking across requests.
The implementation is sourced from the OpenFrame OSS Library. The tenant-context filter itself is referenced by the supplied configuration but its implementation is outside this module's supplied component set; the behaviors below distinguish explicit code from that integration point.
flowchart LR
Browser["Browser or OAuth Client"] --> Edge["Gateway or Direct Request"]
Edge --> TenantContext["Tenant Context Filter"]
TenantContext --> TenantPrefix["Tenant Forwarded Prefix Filter"]
TenantPrefix --> ForwardedHeaders["Forwarded Header Filter"]
ForwardedHeaders --> SecurityChains["Spring Security Filter Chains"]
SecurityChains --> DefaultChain["Login and External SSO Chain"]
SecurityChains --> AuthorizationChain["Authorization Server Chain"]
DefaultChain --> DynamicClients["Dynamic Client Registration Repository"]
AuthorizationChain --> TenantKeys["Tenant Key Service"]
AuthorizationChain --> UserService["Tenant Scoped User Service"]
SecurityChains --> RedisSessions["Redis Session Repository"]
TenantKeys --> Jwt["Tenant Signed JWT"]
UserService --> Jwt
DynamicClients --> ExternalIdp["External OpenID Connect Provider"]
The filter order declared by TenantFilterConfig is significant: Spring Session runs first, followed by the tenant-context filter, then TenantForwardedPrefixFilter, and then Spring's ForwardedHeaderFilter. The ordering ensures a tenant can be recovered from an existing session before forwarding metadata is consumed and before either security chain makes authorization decisions.
| Component | Role | Security significance |
|---|---|---|
AuthorizationServerConfig |
Defines the order-one authorization-server chain, JWT infrastructure, token generation, password encoding, and programmatic authentication manager. | Binds JWKS, issued claims, user lookup, and token minting to the active tenant. |
SecurityConfig |
Defines the order-two chain for form login and external OpenID Connect login. | Applies narrowly scoped CSRF protection, controls public routes, handles failures, and validates tenant-specific identity tokens. |
DynamicClientRegistrationRepository |
Loads an external identity-provider client registration for the current tenant. | Avoids using another tenant's client credentials or provider configuration during an SSO flow. |
SessionConfig |
Configures Redis-backed sessions, namespaced Redis keys, fixed cookie naming and path, and tolerant session-attribute deserialization. | Allows login state to survive restart and horizontal scaling while avoiding deserialization failures after compatible upgrades. |
TenantFilterConfig |
Registers prefix and forwarded-header filters relative to the tenant-context filter. | Establishes the request-processing order on which tenant-aware behavior depends. |
TenantForwardedPrefixFilter |
Adds a tenant prefix for selected authorization-server paths when no forwarded prefix exists. | Makes issuer calculation reflect the tenant-qualified public URL without overwriting upstream forwarding metadata. |
The active tenant is obtained through TenantContext. AuthorizationServerConfig requires it for JWKS lookup, custom JWT claims, password-user lookup, and the active-tenant admission check. A missing tenant on a JWKS request is treated as an error rather than selecting a shared or arbitrary signing key.
DynamicClientRegistrationRepository has a deliberate fallback strategy:
TenantContext.null.DynamicClientRegistrationService for a registration identified by both provider name and tenant identifier. Invalid registrations are logged and treated as unavailable.This supports OpenID Connect callback processing, where the callback must recover the same tenant-specific registration established at the beginning of the browser flow.
sequenceDiagram
participant Browser
participant Filters as "Tenant Filters"
participant Session as "Redis Session"
participant Clients as "Dynamic Client Repository"
participant Provider as "External Provider"
Browser->>Filters: Start SSO login request
Filters->>Session: Read existing session state
Filters->>Filters: Resolve tenant context
Filters->>Clients: Find provider registration
Clients->>Clients: Resolve tenant from context or session
Clients->>Provider: Use tenant specific client configuration
Provider-->>Browser: Redirect with authorization response
Browser->>Filters: Return to callback
Filters->>Session: Recover tenant and authorization state
Filters->>Clients: Resolve the same tenant registration
AuthorizationServerConfig installs the higher-priority chain for Spring Authorization Server endpoints. It allows multiple issuers, enables OpenID Connect defaults, requires authentication for matched endpoints, ignores CSRF for those endpoints, disables CORS, and configures JWT resource-server support.
The JWT encoder and decoder share a JWKSource. For each request, the source requires a nonblank tenant identifier and obtains that tenant's active RSA key from TenantKeyService. The selected key is returned as a JWK set, so signing and verification use tenant-specific key material.
The token generator composes three generators:
JwtGenerator for JWTs, with the module's claim customizer;OAuth2AccessTokenGenerator for access-token generation; andOAuth2RefreshTokenGenerator for refresh-token generation.The same generator is passed to custom Apple-native and signup-ticket grant providers. Consequently, those grants use the normal persistence, signing, claims, and refresh-token path rather than an independent token implementation.
For access tokens, the customizer loads the authenticated user by lower-cased email and tenant. It then adds tenant_id, userId, and the user's effective role names. On a refresh-token grant, it attempts to update the user's last-login timestamp; failure to update that timestamp is logged without aborting token issuance.
flowchart TD
Grant["Authorization Grant"] --> Generator["Delegating Token Generator"]
Generator --> JwtGenerator["JWT Generator"]
Generator --> AccessGenerator["Access Token Generator"]
Generator --> RefreshGenerator["Refresh Token Generator"]
JwtGenerator --> Claims["Tenant and User Claims"]
Claims --> TenantKey["Tenant Active RSA Key"]
TenantKey --> Token["Signed Access Token"]
AccessGenerator --> Token
RefreshGenerator --> RefreshToken["Refresh Token"]
The user-details service first calls the tenant service to refuse login unless the current tenant is active. It then queries only active users matching both lower-cased email and tenant. Passwordless SSO-provisioned users are rejected for password login when no usable password hash exists; an empty password is never accepted as a fallback.
BCrypt is the configured password encoder. The programmatic authentication manager contains a DAO authentication provider built from that user-details service and encoder. The custom-grant providers are intentionally constructed inside the authorization-server configuration rather than exposed as Spring authentication-provider beans, preserving the DAO provider in the global authentication-manager setup.
The lower-priority SecurityConfig chain applies to all non-authorization-server requests. It permits the public routes needed for OAuth, invitations, reset and verification workflows, login, tenant discovery and registration, management paths, provider discovery, GraphQL, and static browser assets. All other requests require authentication.
Form-login CSRF protection is limited to the POST /login endpoint. CORS is disabled. A password-login failure caused by an AuthFlowException is rendered through AuthErrorResponder; ordinary authentication failures redirect to the login page with an error marker. OAuth login failures are also sent through AuthErrorResponder using the SSO login failure code.
For external OpenID Connect providers, the chain uses SsoAuthorizationRequestResolver, the dynamic registration repository, the SSO cookie codec, the tenant-aware OIDC user service, and the success handler. The ID-token decoder factory caches decoders using a key that includes provider registration identifier, client identifier, JWK-set URI, and issuer URI. This avoids Spring's registration-only cache behavior, which would otherwise let the first tenant's configuration be reused for another tenant with the same provider name.
Each generated decoder validates the standard OIDC conditions, including audience validation from OidcIdTokenValidator. It also validates a configured issuer when present and appends provider-specific validation supplied by the SSO provider registry.
Login requests span redirects and may be served by different authorization-server replicas. SessionConfig uses Spring Session with Redis instead of process-local servlet sessions. Stored attributes include the security context, CSRF token, tenant identifier, OAuth authorization request, saved authorization request, and join-invite state.
Redis session keys use the OpenFrame Redis key builder under a tenant key namespace. If the Redis tenant setting is absent, the namespace falls back to shared so service startup does not fail. The documented hash-tag behavior keeps a session's old and new keys in the same Redis Cluster slot, which supports the rename used by session-fixation protection at login.
The session cookie is named JSESSIONID and pinned to the configured servlet context path, or / when no context path is configured. Pinning avoids creating a cookie scoped only to a rewritten tenant prefix during OAuth callbacks. The default Redis serializer is JDK serialization with lenient reads: an attribute that cannot be deserialized is discarded and logged, allowing a new login rather than returning a request failure after a dependency serialization change.
TenantForwardedPrefixFilter runs after tenant context has been set and before ForwardedHeaderFilter consumes forwarding headers. For authorization-server paths containing /.well-known/, or beginning with /oauth2/ or /connect/, and for /userinfo, it injects X-Forwarded-Prefix as /{tenant} only when all of the following are true:
This is narrowly scoped to authorization-server URL generation. It prevents direct access to the authorization service from producing an issuer that lacks its tenant segment, while preserving a gateway-provided prefix when one already exists.
flowchart TD
Request["Incoming Request"] --> TenantKnown{"Tenant resolved?"}
TenantKnown -->|"no"| PassThrough["Do Not Change Headers"]
TenantKnown -->|"yes"| SasPath{"Authorization Server Path?"}
SasPath -->|"no"| PassThrough
SasPath -->|"yes"| ExistingPrefix{"Forwarded Prefix Exists?"}
ExistingPrefix -->|"yes"| PassThrough
ExistingPrefix -->|"no"| AlreadyPrefixed{"Path Already Has Tenant Prefix?"}
AlreadyPrefixed -->|"yes"| PassThrough
AlreadyPrefixed -->|"no"| AddPrefix["Add Tenant Forwarded Prefix"]
AddPrefix --> HeaderFilter["Forwarded Header Filter"]
PassThrough --> HeaderFilter
Maintainers should preserve these invariants when changing the module:
Security And Tenant Context supplies the shared security wiring and tenant propagation rules. It does not implement user provisioning, provider-specific registration strategies, invitation registration, password reset, or SSO controller endpoints; those concerns are part of the surrounding authorization-service modules. It also relies on external tenant-context, tenant-key, user, tenant-service, and dynamic-registration services whose interfaces are consumed here.