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:
# 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.comIn 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):
- Create a new OIDC application (Web type).
- Set the Sign-in redirect URI to:
https://gateway.example.com/api/auth/sso/callback - Set the Sign-out redirect URI to:
https://admin.example.com/login - Note the Client ID, Client Secret, and Issuer URL.
- Ensure the application grants
openid,email, andprofilescopes.
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):
- Set SSO Provider to
oidc. - Enter the Issuer URL — for Okta this looks like
https://your-org.okta.com. - Enter the Client ID and Client Secret from the IdP application.
- Optionally override Scopes (default:
openid email profile). - Toggle SSO Enabled to on.
- Save.
Step 4 — Test the Login Flow
- Open the admin dashboard login page.
- Click Sign in with SSO and enter your organization slug (or
systemfor the deployment-wide provider). - The gateway redirects to
GET /api/auth/sso/:slug/initiate, which builds the OIDC authorization URL and redirects to your IdP. - Authenticate at the IdP.
- The IdP redirects back to
GET /api/auth/sso/callbackwith an authorization code. - The gateway exchanges the code for tokens, extracts the user profile (email, name), and auto-provisions the user if they do not exist.
- 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):
- Create a new SAML 2.0 application.
- Set the ACS (Assertion Consumer Service) URL to:
https://gateway.example.com/api/auth/sso/saml/acs - Set the Entity ID / Issuer to a unique identifier, for example
ai-gateway-prod. - Configure attribute mappings for
email,firstName,lastName. - Download or copy the IdP Certificate (X.509 PEM format).
- Note the SSO URL (IdP entry point).
Step 3 — Configure the Organization
- Set SSO Provider to
saml. - Enter the Entry Point — the IdP’s SSO URL.
- Enter the Issuer — the Entity ID you configured.
- Paste the Certificate (PEM format, without BEGIN/END headers).
- Toggle SSO Enabled to on.
- Save.
Step 4 — Test the Login Flow
- Click Sign in with SSO on the login page.
- The gateway redirects to
GET /api/auth/sso/:slug/initiate, which builds a SAML AuthnRequest and redirects to your IdP. - Authenticate at the IdP.
- The IdP POSTs the SAML assertion to
POST /api/auth/sso/saml/acs. - The gateway validates the signed assertion, extracts the user profile, and auto-provisions the user.
- 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
usersystem role. - The user’s email, first name, and last name are populated from the IdP profile.
- An
ssoProviderIdis stored (e.g.,oidc:sub-idorsaml:nameID) for future login matching. - Subsequent logins update the
lastLogintimestamp.
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
groupsclaim from the ID token, falling back to the userinfo endpoint’sgroups. - SAML — the
groupsattribute, falling back tohttp://schemas.xmlsoap.org/claims/GroupormemberOf.
- OIDC — the
- 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
userrole 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
userrole. super-adminis never assignable this way. A group that maps tosuper-adminis 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/logoutThis 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
- Configure IdP Group → Role Mapping to drive gateway roles from IdP groups
- Automate account lifecycle with SCIM Provisioning
- Set up Budget Management for SSO-provisioned users
- Review SSO login events in the Audit Logs dashboard