Enterprise SSO

Enterprise connections let an organization’s members authenticate with its identity provider. Your application integrates with Oathvera’s hosted authorization-code flow; Oathvera handles the upstream SAML or OIDC exchange.

Acceptance boundary: the profiles below are implemented configuration options, not a certification of every provider deployment. Current outbound adapter compatibility and live-provider acceptance remain open; see compatibility. Prepare the connection, then complete provider acceptance before requiring SSO for a production user population.

Set up an organization

1. Create the application and an interactive client with exact callbacks.
2. Enable Enterprise SSO in workspace authentication and permit it for the application.
3. Create the application’s organization. Decide whether membership is required and whether SSO is optional or required. Leave just-in-time membership/user creation off until authorized by the organization.
4. Add its domain under Domains, publish the generated _oathvera.<domain> TXT proof, and verify ownership. Current proofs expire after 30 days and require renewal.
5. Create a disabled SSO connection for that application and organization. Enter the provider configuration, copy Oathvera’s displayed callback or SP metadata into the provider, configure attribute mapping, and enable the connection when ready.
6. Start a fresh login from the application, use organization-name or verified-domain discovery in hosted login, and complete the provider flow and any Oathvera MFA.
7. Validate the returned identity and organization context, then enforce organization-specific API permissions.

Enterprise-domain proof establishes an organization’s email namespace. It is separate from the DNS/TLS process for a custom authentication hostname. Completing one does not complete the other.

Provider profiles

Profile	Current options
Microsoft Entra ID	SAML or enterprise OIDC with a tenant-specific issuer.
Google Workspace	SAML profile.
Okta Workforce	SAML or enterprise OIDC.
ADFS	SAML or compatible enterprise OIDC.
PingFederate	SAML or compatible enterprise OIDC.
Active Directory / LDAP	Through an organization-operated SAML/OIDC gateway; no direct LDAP bind or directory-password collection.
Custom identity provider	Must satisfy the protocol profiles below.

Connections currently retain their application and organization bindings. Configure and accept each consuming application; creating one connection does not automatically make it available to every application.

SAML profile

Oathvera sends signed HTTP-Redirect AuthnRequests and expects HTTP-POST responses. Configure the identity provider to sign both the Response and Assertion with RSA SHA-256 using the pinned RSA certificate of at least 2048 bits. The accepted profile uses one plaintext assertion and a persistent or explicitly stable unspecified NameID.

Issuer, audience, destination, recipient, request correlation, assertion lifetime and replay checks must all pass. Map the stable subject separately from email and display name. The owner supplies Oathvera’s SP signing key and certificate through the console and pins the provider certificate. Coordinate certificate rotation before expiry.

Encrypted assertions, artifact/SOAP bindings, unsolicited assertion login and SAML single logout are not part of this profile. Provider defaults that sign only one XML element are insufficient.

Enterprise OIDC profile

Configure a provider that supports discovery, authorization code, PKCE S256, state, nonce and client_secret_post for the upstream exchange. ID tokens must use RS256 or ES256. Discovery resolves and pins provider endpoints during connection configuration.

This upstream requirement is distinct from your application’s authentication to Oathvera: Oathvera confidential clients use client_secret_basic.

The provider must return verified email, unless an owner explicitly chooses to trust provider-asserted email within the organization’s verified domains. SAML requires an explicit email-trust decision. Subject, issuer, audience, authorized party, nonce and time claims remain validated regardless of that email setting.

Organization enforcement, JIT and launch

Required SSO does not silently fall back to password when the connection, membership or domain proof fails. Proof expiry blocks the affected enterprise sign-in and JIT path. Provider-asserted MFA does not automatically satisfy Oathvera’s separate MFA policy.

JIT requires explicit organization approval, an active connection and a currently verified organization domain. It cannot restore suspended memberships or assign administrator roles. Matching email cannot link an existing account; use the explicit authorized linking operation with the exact user and immutable provider subject.

Enterprise sessions include organization_id and connection_id in ID tokens and UserInfo. Validate those claims as part of your application context. Authorization checks require the exact organization that owns the requested data; a different organization must not obtain access through a shared email domain or user identity.

A separately approved IdP portal launch can return the browser to a registered HTTPS application start URL. The application must then initiate a fresh code/PKCE flow and correlated SSO round trip. This is not direct login from an unsolicited SAML assertion. Leave launch disabled unless the organization approves the configured client and start URL.

Acceptance checklist

Test a returning member, authorized JIT, an existing email without linking, a suspended member, wrong organization, expired domain proof, disabled connection, malformed/replayed assertion or callback, local MFA and certificate/secret rotation. A named provider profile without these results remains unaccepted for the deployment in question.