Skip to content
Gatewyse

SSO Integration

Gatewyse supports enterprise SSO via OpenID Connect (OIDC) and SAML 2.0. When SSO is enabled for an organization — or for the deployment as a whole — 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

An 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 Organization

In the admin dashboard, open the organization this identity provider serves and enable SSO on it (or configure it on Settings for a deployment-wide provider):

  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 organization slug (or system for the deployment-wide provider).
  3. The gateway redirects to GET /api/auth/sso/:slug/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 Organization

  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/:slug/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 that organization’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 against the deployment’s seeded system roles and that organization’s custom roles, and the user’s membership in that organization is rewritten to that set. Authority is read from memberships, so the change takes effect on the next request. A user whose groups match nothing is given the base user role rather than left with no membership at all.

Configuring groupRoleMappings

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

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

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

The map belongs to one organization, not to the deployment. That is deliberate: a deployment-wide map would mean one organization’s group named Engineering and another organization’s group of the same name granting the same role, so naming a group after somebody else’s would grant their access.

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 super-admin. Scoped roles (org-admin, dept-admin, and so on) are intentionally mappable.
  • An organization’s IdP reaches its own organization and nothing else. It cannot assert an identity at deployment level or inside another organization, whatever the assertion says — and it may only claim addresses inside the email domains that organization has been granted. Claiming a domain is a deployment-level decision for exactly that reason.

SAML Single Logout (SLO)

For SAML, 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 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