Skip to content
Gatewyse

SSO Integration

Gatewyse supports enterprise SSO via OpenID Connect (OIDC) and SAML 2.0. When SSO is enabled for a tenant, users authenticate through your identity provider (IdP) and are automatically provisioned in the gateway.

Prerequisites

  • Admin access to Gatewyse
  • An identity provider that supports OIDC or SAML (e.g., Okta, Azure AD, Google Workspace)

Supported SSO Provider Types

The tenant SSO configuration accepts exactly two provider types:

  • oidc — OpenID Connect (works with any OIDC-compliant IdP, e.g. Okta, Microsoft Entra ID / Azure AD, Google Workspace)
  • saml — SAML 2.0

You select one of these in the Settings UI; the specific vendor (Okta, Azure AD, Google, etc.) is configured by pointing the oidc type at that IdP’s issuer URL.

Option A — OIDC Configuration

Step 1 — Set Environment Variables

Configure the following environment variables on the gateway server:

Terminal window
# Base URL for SSO callbacks (must be reachable by the IdP)
SSO_CALLBACK_BASE_URL=https://gateway.example.com


# Admin dashboard URL (used for post-login redirects)
ADMIN_URL=https://admin.example.com

In production, SSO_CALLBACK_BASE_URL must always be set to prevent Host header injection.

Step 2 — Register the Application in Your IdP

In your identity provider (e.g., Okta):

  1. Create a new OIDC application (Web type).
  2. Set the Sign-in redirect URI to: https://gateway.example.com/api/auth/sso/callback
  3. Set the Sign-out redirect URI to: https://admin.example.com/login
  4. Note the Client ID, Client Secret, and Issuer URL.
  5. Ensure the application grants openid, email, and profile scopes.

Step 3 — Configure the Tenant

In the admin dashboard, navigate to Settings for your tenant and enable SSO:

  1. Set SSO Provider to oidc.
  2. Enter the Issuer URL — for Okta this looks like https://your-org.okta.com.
  3. Enter the Client ID and Client Secret from the IdP application.
  4. Optionally override Scopes (default: openid email profile).
  5. Toggle SSO Enabled to on.
  6. Save.

Step 4 — Test the Login Flow

  1. Open the admin dashboard login page.
  2. Click Sign in with SSO and enter your tenant slug.
  3. The gateway redirects to GET /api/auth/sso/:tenantSlug/initiate, which builds the OIDC authorization URL and redirects to your IdP.
  4. Authenticate at the IdP.
  5. The IdP redirects back to GET /api/auth/sso/callback with an authorization code.
  6. The gateway exchanges the code for tokens, extracts the user profile (email, name), and auto-provisions the user if they do not exist.
  7. JWT tokens are set as HttpOnly cookies, and you are redirected to the dashboard.

Option B — SAML Configuration

Step 1 — Set Environment Variables

Same as OIDC: set SSO_CALLBACK_BASE_URL and ADMIN_URL.

Step 2 — Register the Application in Your IdP

In your SAML IdP (e.g., Okta or Azure AD):

  1. Create a new SAML 2.0 application.
  2. Set the ACS (Assertion Consumer Service) URL to: https://gateway.example.com/api/auth/sso/saml/acs
  3. Set the Entity ID / Issuer to a unique identifier, for example ai-gateway-prod.
  4. Configure attribute mappings for email, firstName, lastName.
  5. Download or copy the IdP Certificate (X.509 PEM format).
  6. Note the SSO URL (IdP entry point).

Step 3 — Configure the Tenant

  1. Set SSO Provider to saml.
  2. Enter the Entry Point — the IdP’s SSO URL.
  3. Enter the Issuer — the Entity ID you configured.
  4. Paste the Certificate (PEM format, without BEGIN/END headers).
  5. Toggle SSO Enabled to on.
  6. Save.

Step 4 — Test the Login Flow

  1. Click Sign in with SSO on the login page.
  2. The gateway redirects to GET /api/auth/sso/:tenantSlug/initiate, which builds a SAML AuthnRequest and redirects to your IdP.
  3. Authenticate at the IdP.
  4. The IdP POSTs the SAML assertion to POST /api/auth/sso/saml/acs.
  5. The gateway validates the signed assertion, extracts the user profile, and auto-provisions the user.
  6. JWT tokens are set as HttpOnly cookies, and you are redirected to the dashboard.

User Auto-Provisioning

When a user authenticates via SSO for the first time:

  • A new user record is created with the user system role.
  • The user’s email, first name, and last name are populated from the IdP profile.
  • An ssoProviderId is stored (e.g., oidc:sub-id or saml:nameID) for future login matching.
  • Subsequent logins update the lastLogin timestamp.

IdP Group → Role Mapping

By default, SSO-provisioned users receive the base user role and their roles are managed manually. If you configure groupRoleMappings on the tenant’s SSO config, the IdP becomes authoritative for roles: the user’s roles are resolved from their IdP group claims and re-synced on every login.

How It Works

  • On login, the gateway reads the user’s group claims from the IdP:
    • OIDC — the groups claim from the ID token, falling back to the userinfo endpoint’s groups.
    • SAML — the groups attribute, falling back to http://schemas.xmlsoap.org/claims/Group or memberOf.
  • Each group name is looked up in groupRoleMappings, which maps an IdP group name to a gateway role slug.
  • The matched role slugs are resolved to the tenant’s seeded system roles and its own custom roles, and the user’s roleIds are replaced with that set.

Configuring groupRoleMappings

groupRoleMappings is a map of IdP group name to role slug on the tenant’s SSO config. For example:

{
  "Gateway-Admins": "tenant-admin",
  "Gateway-Analysts": "read-only",
  "Engineering": "user"
}

With this mapping, a user whose IdP groups include Gateway-Admins is synced to the tenant-admin role on their next login.

Behavior Notes

  • Re-sync on every login. When mappings are configured and the user matches at least one mapped group, their roles are overwritten from the IdP on each login — the IdP is the source of truth. Manual role edits are not preserved for mapped users.
  • No mapping configured leaves roles to manual admin management (the pre-existing behavior).
  • No matching group never leaves a user with zero roles — a newly provisioned user falls back to the base user role.
  • super-admin is never assignable this way. A group that maps to super-admin is ignored, so a misconfigured or malicious IdP group cannot escalate a user to platform super-admin. Tenant-scoped roles (tenant-admin, org-admin, dept-admin, and so on) are intentionally mappable.

SAML Single Logout (SLO)

For SAML tenants, the gateway supports SP-initiated Single Logout. An authenticated SAML user can hit:

GET /api/auth/sso/saml/logout

This route requires an active session (it is authenticated). It clears the local auth cookies and redirects the user’s browser to the IdP’s SLO endpoint so the IdP session is terminated too. The subject nameID is recovered from the user’s stored saml:<nameID> provider id, and the redirect target is the tenant’s configured SLO endpoint (logoutUrl), falling back to the SAML entry point when no dedicated logoutUrl is set.

Only SAML SSO users can use this route — password and OIDC users are rejected.

Automated Provisioning with SCIM

SSO only authenticates users (and optionally re-syncs their roles at login). To provision accounts out-of-band — creating, updating, deprovisioning, and role-mapping users directly from your IdP without waiting for them to log in — use the SCIM 2.0 API. See SCIM Provisioning for the endpoints and setup. Most enterprise deployments run both: SSO for login, SCIM for lifecycle management. Both enforce the same escalation guard, so neither can assign super-admin.

Security Considerations

  • SSO state is stored in Redis with a 10-minute TTL and is deleted after retrieval to prevent replay attacks.
  • SAML assertions are validated with wantAssertionsSigned: true.
  • Tokens are transmitted via HttpOnly cookies, never in URL parameters.
  • In development mode, insecure OIDC requests are permitted for local testing; in production this is disabled.

Next Steps