Enterprise SSO connections

An SSO connection wires an enterprise customer's IdP (OIDC, SAML, or DiscourseConnect) to an organization in your instance. Users from that IdP are JIT-provisioned into the org on first sign-in, with roles optionally driven by IdP claims.

{
  "object": "sso_connection",
  "id": "ssoc_…",
  "organization_id": "org_9f…",
  "type": "saml",
  "status": "active",
  "oidc_issuer": null,
  "oidc_client_id": null,
  "has_secret": false,
  "saml_idp_entity_id": "https://idp.acme.com/…",
  "saml_idp_sso_url": "https://idp.acme.com/sso",
  "has_saml_certificate": true,
  "saml_allow_idp_initiated": true,
  "allowed_domains": ["acme.com"],
  "claim_role_mappings": [{ "claim": "groups", "value": "admins", "roleKey": "org:admin" }],
  "default_role_id": null,
  "created_at": 1757000000000,
  "updated_at": 1757600000000
}

Secrets and certificates are write-only: the IdP oidc_client_secret, saml_idp_certificate, and discourse_secret are stored encrypted and never returned — reads report has_secret / has_saml_certificate markers.

Endpoints

Claim → role mapping

claim_role_mappings maps an IdP claim value to an org role key, so the IdP drives role assignment. allowed_domains routes users by email domain to this connection.

Example

const conn = await atlas.ssoConnections.create({
  organization_id: 'org_9f',
  type: 'saml',
  status: 'active',
  saml_idp_entity_id: 'https://idp.acme.com/…',
  saml_idp_sso_url: 'https://idp.acme.com/sso',
  saml_idp_certificate: '-----BEGIN CERTIFICATE-----…', // write-only
  allowed_domains: ['acme.com'],
  claim_role_mappings: [{ claim: 'groups', value: 'admins', roleKey: 'org:admin' }],
});

// Hand this SP metadata to the customer's IdP admin
const { metadata_xml, acs_url, sp_entity_id } = await atlas.ssoConnections.samlMetadata(conn.id);

Users sign in

End users start enterprise SSO from the frontend with POST /v1/client/sign_ins/sso (OIDC) or POST /v1/client/sign_ins/saml (SAML), resolved by connection id or email domain. The IdP redirects back through the callbacks documented in SAML. To let customers configure their own connection without a dashboard account, see Self-service SSO.