​

Enroll SAML SSO

​

Before you start

1. An owner role in the Orbit organization. Creating and changing SAML configuration is owner-only; admins can read the config and probe metadata but cannot save changes.
2. Your IdP’s signing certificate (X.509, PEM format). Okta shows it under the app’s Sign On tab; Entra ID under the enterprise application’s Certificates blade.
3. Your IdP’s SSO URL and entity ID. If you don’t have them handy, the metadata probe below can suggest them from a metadata URL.
4. An attribute mapping plan — decide which assertion attributes carry email and name (the canonical table below covers Okta and Entra defaults).
5. A decision on enforcement: will password sign-in stay available while you test, and when (if ever) do you flip to SSO-only? Plan a staging window before you enforce.

​

Step 1 — Discover the IdP with a metadata probe

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/saml/test-connection" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "metadataUrl": "https://your-idp.example.com/federationmetadata.xml"
  }'

• ok — true when the document fetched and looked like SAML metadata.
• suggested_sso_url — the URL from the <SingleSignOnService> element, when present.
• suggested_entity_id — the document’s entityID, when present.

​

Step 2 — Write the SAML configuration

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/saml" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ssoUrl": "https://your-idp.example.com/app/orbit/sso/saml",
    "entityId": "http://www.okta.com/exkXXXXXXXXXXXXXXX",
    "x509Cert": "-----BEGIN CERTIFICATE-----\nMIIDpCC...IdP signing cert...\n-----END CERTIFICATE-----",
    "attrEmail": "mail",
    "attrName": "displayName",
    "enabled": true,
    "enforced": false
  }'

• ssoUrl — the IdP’s sign-on endpoint (https, publicly resolvable).
• entityId — the IdP’s issuer identifier (often a URN or URL).
• x509Cert — the PEM signing certificate. Required on first setup; stored afterwards — omit it on later PATCHes to keep the existing certificate while you change other fields.
• attrEmail / attrName — the assertion attribute names Orbit reads for the sign-in’s email and display name (see the IdP table below).
• enabled — true turns SSO on. Keep enforced: false while you test.
• enforced — leave false until step 5.

​

IdP attribute defaults

​

Step 3 — Point the IdP at Orbit

• ACS URL (Assertion Consumer Service): https://api.orbit.devotel.io/auth/saml/{orgSlug}/callback
• SSO entry point: https://api.orbit.devotel.io/auth/saml/{orgSlug}/login
• SP metadata to import rather than type: https://api.orbit.devotel.io/auth/saml/{orgSlug}/metadata
• Single logout URL: https://api.orbit.devotel.io/auth/saml/{orgSlug}/logout

​

Step 4 — Test the flow end-to-end

1. Open https://api.orbit.devotel.io/auth/saml/{orgSlug}/login in a fresh browser profile (SP-initiated login — the standard path).
2. Orbit 302-redirects to your IdP. Authenticate as a test user assigned to the Orbit app.
3. The IdP POSTs the signed assertion to /auth/saml/{orgSlug}/callback; on success you land in the dashboard with a session.

• The email matches an Orbit member — the assertion’s mapped email attribute must match an existing member of the organization. If it doesn’t, invite that person first.
• Attribute mapping is the first failure to check — a successful IdP login followed by an Orbit error almost always means the assertion’s attribute names don’t line up with attrEmail / attrName. Inspect the raw assertion in your IdP’s SAML tracer and compare the claim names.
• IdP-initiated login also works — users clicking the Orbit tile inside Okta/Entra post directly to the ACS callback without the SP-initiated redirect. It works once the app is assigned; SP-initiated is still the recommended entry point because the slug determines the organization.

​

Step 5 — Enforce SSO

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/saml" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "enforced": true }'

​

Rotate or revoke the certificate

​

Common failures

​

See also

• Wire SCIM provisioning — sync membership and roles from the same IdP; the attribute table and token flow mirror this guide.
• Settings → Security console — the dashboard walkthrough of the same surface this guide covers by API.
• Authenticate Orbit API requests — the public SAML login endpoints and the API key/session distinction.
• Settings API — the full single sign-on endpoint table (GET / PATCH / test-connection).
• Troubleshooting: authentication gates — every SSO rejection code and its fix.