​
OIDC Single Sign-On

ManyLayers supports OIDC-based SSO for both API key authentication and workspace login. Connect your existing identity provider — Okta, Azure AD, Google, Keycloak, or any OIDC-compliant IdP.

​
Configuration

auth:
  oidc:
    issuer: https://login.example.com/realms/corp
    audience: manylayers
    # jwks_url: ""          # "" = auto-discovery via OIDC
    team_claim: team        # JWT claim carrying the gateway team name
    team_mapping:           # map IdP group names to gateway teams
      idp-eng-group: engineering
    role_claim: role
    admin_role: admin
    spa_client_id: myapp    # OIDC client ID for dashboard login

​
Authentication order

ManyLayers evaluates authentication in this order:
  1. API key — Authorization: Bearer ml-... prefixed keys
  2. OIDC JWT — Authorization: Bearer <jwt> validated against your configured issuer
  3. Session cookie — workspace browser sessions
  4. Personal Access Token — Authorization: Bearer ml_pat_... tokens

​
SSO login flow

  1. Your users click “Sign in with SSO” in the workspace UI
  2. The UI redirects to your OIDC provider with the configured spa_client_id
  3. After authentication, the provider redirects back with an authorization code
  4. The UI calls POST /auth/sso with the OIDC token
  5. ManyLayers validates the token, auto-provisions the user, and returns a session

​
Team and role mapping

The team_claim and role_claim extract team membership and role from the JWT. The team_mapping maps your IdP group names to gateway teams. Users with the admin_role value get full admin access.

​
SCIM 2.0 User Provisioning

SCIM enables automated user lifecycle management — provision new users and deactivate departing ones directly from your IdP without manual administration.

​
Supported operations

ResourceOperationsNotes
/scim/v2/UsersFull CRUDMaps userName to email, active to enabled status
/scim/v2/GroupsGET onlyReturns empty list; write operations return 501

​
SCIM authentication

SCIM endpoints use a Bearer token that is org-scoped and managed by org admins:
EndpointAuthDescription
GET /org/scim/tokenorg_adminGet the current SCIM token
POST /org/scim/tokenorg_adminRotate the SCIM token

​
SCIM endpoints

MethodPathDescription
GET/scim/v2/UsersList users (supports filter, startIndex, count)
POST/scim/v2/UsersCreate a user
GET/scim/v2/Users/{id}Get a user
PUT/scim/v2/Users/{id}Replace a user
PATCH/scim/v2/Users/{id}Partial update (e.g. deactivate)
DELETE/scim/v2/Users/{id}Deactivate a user

​
Example: provision a user

curl -X POST http://localhost:8180/scim/v2/Users \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "alice@example.com",
    "active": true,
    "name": {"givenName": "Alice", "familyName": "Smith"}
  }'
All SCIM responses use Content-Type: application/scim+json.

​
Next steps