SSO reference

Depth behind Enterprise SSO enrollment.

SSO configuration

Under Users → Identity → SSO configuration:

Setting	What it does
Email domains (own card)	Only IdP-verified emails in these domains may enroll. Empty means any verified email. Desktop sign-in also needs the domain Verified (DNS TXT record, shown on the card).
Group → team mapping	Maps an IdP group to an Anyray team. First match wins, else the default team. At login the user picks from every mapped team plus the default.
Group → role mapping	Maps an IdP group to a console role. Several mapped groups give the most privileged one, else viewer.
Capability bundles	Optional. Names a set of capabilities the four roles cannot express, such as reading trace content without provider-key access. See capability bundles.
Group → bundle mapping	Which groups receive a bundle. Several mapped groups combine.
Default team	Optional. The team a user lands on when no mapped group matches.
Session length (hours)	How long a minted ark_ key lasts. Default 30 days, minimum 1 hour, maximum 365 days. Keys in active use renew, so only idle keys lapse. Console sign-ins stay capped at 30 days.
Re-enrollment window (hours)	Optional. How long a device may go unused before the person signs in again. Empty means 30 days. Takes effect only when set longer than the session length. Needs gateway v1.10.105+.

Roles are console permissions only. owner is a fifth, break-glass role held solely by the admin key (ANYRAY_ADMIN_TOKEN). It passes every check and is never granted through SSO.

Console roles

Role	Can do
viewer	Read-only: dashboards, spend, trace metadata. Fallback for any unmapped user.
auditor	viewer, plus read the audit log.
operator	viewer, plus change routing, model aliases, user caps, and run the playground. No audit log.
security_admin	operator and auditor, plus manage SSO/IdP config, provider and client keys, content settings, the optimizer, and updates.

Assign through Group → role mapping, one group=role per line:

Group → role mapping

platform-admins=security_admin
devops=operator

Assigning roles without groups

On first connect, the account owner gets security_admin, so someone can always administer the console. To assign by exact person, use email → role assignment in the admin API. For access no rung expresses, define a capability bundle.

If your IdP sends no group claims

Group → role and group → team resolve from the groups your IdP asserts at sign-in. If your provider sends groups only over SCIM directory sync, map by email instead, or add the group attribute to your WorkOS connection. Changes land on each user's next sign-in.

What an active IdP connection enforces

Once the connection is active, standalone enrollment stops. The Billing backend reads the tenant's SSO config before it mints or redeems any enrollment credential.

Path	After SSO is active
Mint or redeem an admin-issued, email-bound personal enl_… link	Allowed as a recovery path. The link's bound email wins over client-supplied identity.
Mint or redeem a shared enl_… link or manual enp_… token (any identity mode)	sso_required. Listing and revocation stay available.
An MDM-kind provisioning token	Mints, rotates, and enrolls regardless of SSO state. A macOS certificate token requires its profile proof; a legacy MDM token requires its endpoint evidence.
Manual certificates issued before you connected	Stop rolling forward, so they lapse at their own expiry and that developer signs in through the IdP. Nothing is cut off at the moment you connect.
Device, legacy MDM, and MDM-managed macOS certificates	Keep rolling forward, so a managed Mac never needs an end-user sign-in. Device renewal proves possession of the Mac's own key and does not recheck the shared profile certificate.
Machine-mode tokens and shared passwordless links	Blocked.

Desktop sign-in for an SSO tenant must complete through that tenant's IdP connection; an email-code login cannot enroll the device.

SSO status and identity come from durable server-side records and signed bindings. Client headers cannot claim SSO or replace the bound identity. A genuinely non-human workload uses a service key.

Launching from your IdP app tile

The SAML app you created when you connected your IdP can show as a tile in Okta, Entra ID, or any IdP with an app launcher. Launching it is IdP-initiated: your provider sends the sign-in to Anyray without Anyray having asked for it first, so the launch carries nothing that says which console it meant.

Anyray resolves that on its side. The tile lands on the sign-in lane, and once your identity is verified the organization behind it selects your own console: the most recently seen gateway that has reported a console address. Your people land on that console's sign-in, already signed in to your IdP, so the hop is silent.

If no gateway of yours has reported in during the last day, the tile lands on the Anyray billing portal instead. Once one reports in again, the tile follows it.

Use that SAML app's own tile, and leave its RelayState and sign-in URL settings empty. Don't add a separate bookmark tile for https://app.anyray.ai: a plain link opens the billing portal, not your console.

Set up inbound SCIM

The gateway's SCIM 2.0 base URL is https://<your-anyray-gateway>/scim/v2.

1

Choose a bearer token

Create a high-entropy static token in your secrets manager. The IdP sends it on every SCIM request. Anyray stores only its SHA-256 hash.

2

Configure the gateway

Set the bearer, the IdP group that grants the admin role, and any group-to-team mappings.

Configure inbound SCIM

curl -X PUT https://<your-anyray-gateway>/admin/scim/settings \
  -H "Authorization: Bearer $ANYRAY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bearerToken": "synthetic-scim-bearer-token-replace-me-0001",
    "adminGroup": "Anyray Admins",
    "groupTeamMap": {
      "Platform Engineering": "platform",
      "Anyray Admins": "platform"
    }
  }'

3

Connect the IdP

Set the SCIM base URL in the IdP with the same bearer, and enable user and group pushes. Anyray supports discovery, Users and Groups CRUD, paging, userName eq "…" filters, user activation, and group membership patches.

4

Verify provisioning

Assign a synthetic test user and mapped group in the IdP. The user appears on the Users roster with source scim, the mapped team, and the configured role.

Reading back and rotating the bearer

GET /admin/scim/settings returns whether SCIM is configured, plus the admin group and team map. It never returns the bearer or its hash. Updating mappings without bearerToken keeps the current token. Include a new bearer to rotate it.

When a team mapping change takes effect

Team mappings stay live. The gateway resolves the current mapped team on every request, with no re-enrollment. Billing-lane assignment and GET /connect/policy follow on the seat's next policy pull. Spend attribution follows on the next request, and rows recorded before a move keep the team they had.

Map values are Anyray team ids (letters, digits, and .@+:-_, up to 128 characters). Group names can be anything your IdP sends. A value outside that shape is rejected on write.

Teams from your identity provider

Your IdP's groups set each person's team, so nobody types --team at enrollment. Directory Sync and SAML resolve through the same group → team mapping, so one person can never land on two teams. Only the speed differs.

Connection	When the team refreshes
Directory Sync	On every group membership change. Your gateway picks it up in about five minutes.
SAML / SSO	At each sign-in, so by default every 30 days, per your session length.

Precedence, highest first:

1

Direct gateway SCIM

A real-time push to /scim/v2 decides whenever it has an answer.

2

Your IdP's groups

Applies when SCIM has nothing to say.

3

The team set at enrollment

--team, an enrollment link, or an MDM default team.

No level can blank someone out. A person whose groups map to no team keeps the team their key was enrolled with, and an unreachable IdP changes nothing. If someone's groups map to several teams, anyray-connect login asks them to choose, and that choice stands.

What Anyray stores

Only the resolved team id, against the person's email. IdP group names are read to work out the team and are never stored or logged. If a group push names a user that has not arrived yet, include the member's email in its display field.