Enterprise SSO

Bulwark supports SAML 2.0 and OIDC identity provider connections for enterprise customers who authenticate via their own identity infrastructure — Okta, Azure AD, Google Workspace, Ping Identity, and others.

How It Works

Enterprise SSO replaces Bulwark's hosted login page with a redirect to the customer's IdP. Bulwark acts as the service provider (SAML) or relying party (OIDC), validating assertions from the IdP and creating or updating Bulwark user records.

User enters email on login page
  ↓
POST /api/v1/auth/sso/detect (email domain lookup)
  ↓
GET /api/v1/auth/sso/{id}/authorize (redirect to IdP)
  ↓
User authenticates at IdP (Okta, Azure AD, etc.)
  ↓
IdP posts assertion to Bulwark ACS (SAML) or redirects with code (OIDC)
  ↓
Bulwark validates assertion, provisions or updates user
  ↓
Bulwark issues session, redirects to application

SAML Connections

For SAML, Bulwark is the service provider. You configure your IdP with:

  • SP Entity ID: https://api.bulwarkauth.com/api/v1/auth/sso/{id}/metadata
  • ACS URL: https://api.bulwarkauth.com/api/v1/auth/sso/{id}/acs
  • Name ID format: emailAddress

Bulwark validates:

  • The assertion signature using the IdP certificate
  • NotBefore and NotOnOrAfter time bounds
  • The Audience restriction matches the SP Entity ID
  • The InResponseTo attribute matches the original AuthnRequest ID

OIDC Connections

For OIDC, Bulwark acts as the relying party. The connection requires:

  • Issuer URL — used for OpenID Connect discovery
  • Client ID and Client Secret — registered with the IdP
  • Scopes — typically openid profile email plus any groups scope

Bulwark fetches the IdP's discovery document at setup time and refreshes it periodically.

Email Domain Detection

SSO routing is based on the email domain. When a user enters [email protected], Bulwark looks up the acme.com domain and finds the associated SSO connection. Multiple domains can be mapped to a single connection, and a domain can only belong to one connection per tenant.

Domain detection is exposed as a public API endpoint so that login UIs can implement seamless redirect without hardcoding connection IDs.

JIT Provisioning

Just-in-time provisioning automatically creates a Bulwark user record the first time someone authenticates via SSO. The user's email, name, and any mapped attributes are populated from the IdP assertion.

If the user already exists (matched by email), their profile is updated with the latest values from the IdP on every login. This keeps display names and group memberships current without requiring a separate SCIM sync.

JIT provisioning can be disabled per connection. With it off, only pre-provisioned users (via SCIM or the admin API) can authenticate through SSO.

Group-to-Role Mapping

IdP groups or roles can be mapped to Bulwark roles:

"group_role_mapping": [
  { "group": "IT-Admins", "role": "admin" },
  { "group": "Engineering", "role": "member" },
  { "group": "Contractors", "role": "viewer" }
]

For SAML, groups are sourced from a configurable attribute (e.g. http://schemas.xmlsoap.org/claims/Group). For OIDC, groups come from a claim in the ID token (e.g. groups).

Mapping is evaluated on every login. A user who is removed from a group in the IdP loses that role on their next sign-in.

SP-Initiated vs. IdP-Initiated

Bulwark supports both flows:

  • SP-initiated: User starts at your application, is redirected to Bulwark, which redirects to the IdP. This is the standard flow and supports CSRF protection via the state parameter.
  • IdP-initiated: User starts from a bookmark or app tile in Okta/Azure AD. Bulwark accepts unsolicited assertions and OIDC responses. IdP-initiated flows can be restricted per connection if your security policy requires it.

SSO Enforcement

To require SSO for all users with a matching domain, enable SSO enforcement on the connection. Enforced connections block password-based login for matching email domains — users must authenticate through the IdP. MFA configured in the IdP satisfies Bulwark's MFA requirements.