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 Providers

The gateway recognizes these provider types in the tenant SSO configuration:

  • oidc — Generic OpenID Connect
  • google — Google Workspace (uses OIDC)
  • microsoft — Microsoft Entra ID / Azure AD (uses OIDC)
  • okta — Okta (uses OIDC)
  • saml — Generic SAML 2.0

All OIDC-type providers follow the same code path; the provider name is used for display purposes.

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 (or okta, google, microsoft).
  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.

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

  • Configure role mapping from IdP groups to gateway roles
  • Set up Budget Management for SSO-provisioned users
  • Review SSO login events in the Audit Logs dashboard