Single sign-on with SAML or OIDC

In development

Single sign-on is implemented and tested with Okta and Microsoft Entra ID, but is still being finished and tested. It is intended for the Business and Enterprise plans. Nothing is sold yet, and plans are not final.

Organization-managed identities let a company sign in through its identity provider (IdP) with OIDC or SAML 2.0.

Before you start

Managed identities are switched on for your company by Orbit once single sign-on is available to you. You also need organization-level administration rights. Binding people by e-mail, and SCIM, need a verified domain on the connection.

Create a connection

In the organization’s Identity section choose New connection, then OIDC or SAML.

1. OIDC. Use the provider’s discovery document. Orbit stores the provider’s userinfo endpoint when discovery advertises one exact HTTPS address.

2. SAML 2.0. Enter:

   • the IdP entity id,
   • the IdP’s HTTPS SSO URL,
   • Orbit’s service-provider (SP) entity id,
   • the callback origin, which must equal the account origin,
   • the immutable subject: a persistent NameID, or a signed attribute with the exact attribute name,
   • one to four IdP signing certificates,
   • the SP request-signing certificate. Its private key is write-only: set it separately.

3. Give the IdP Orbit’s SP metadata (entity id, ACS URL, certificate) from /api/v1/auth/saml/<connectionId>/metadata. It is served once the request-signing key has been set, in any connection state, so you can configure the IdP before enabling the connection. The ACS is POST <account origin>/api/v1/auth/saml/<connectionId>/acs.

4. Run the provider test. Every configuration change invalidates the test and disables an enabled connection until a new test passes.

How people are bound to the provider

A person is bound to the provider by an immutable subject: the OIDC subject, or the SAML NameID (or a signed attribute). A bound subject never rebinds.

How	What happens
Directory creates the person with SCIM and sends the Orbit extension	The person is bound at once and signs in normally.
Directory creates the person without the extension (for example Microsoft Entra ID)	The person stays pending until the first sign-in. If the e-mail the provider sends equals the directory’s userName in a verified domain, the account is bound to that subject, enabled, and the session opens.
An existing Orbit member enrolls	They re-enter their Orbit password and the organization owner approves the enrollment.

An optional e-mail attribute for SAML names the attribute that carries the e-mail, for example email. It is read only from the signature-verified assertion, and only when exactly one such attribute has exactly one plain value. A different or missing e-mail on enrollment is refused with identity_email_mismatch.

• Microsoft Entra ID. Set “Assignment required = Yes” on the enterprise app. Guests and external accounts (B2B) never bind by e-mail.
• Okta. Okta puts email_verified in the userinfo answer, not in the ID token. Orbit asks the userinfo endpoint once when the ID token has no email_verified claim, and accepts the answer only when it matches the same subject and e-mail.

Enforce SSO

Each connection has a sign-in policy: optional or required (and off).

• With required, the accounts the connection manages cannot sign in with a password or re-authenticate locally (they get identity_sso_required). A session is valid only if it came through the connection at the current policy version.
• Switching the policy revokes sessions, API tokens and agent grants of managed accounts, except when stepping down from required to optional.
• Unmanaged accounts, service accounts, and addresses outside verified domains are not bound.
• Switching to required needs a current provider test and a recovery test by the acting owner.

Recovery owner. While any connection is required, the organization keeps at least one active owner who is human, unmanaged and has a password. Actions that would remove the last such owner are refused with identity_recovery_required. If the provider breaks, new SSO sign-ins fail but existing sessions keep working. The recovery owner signs in with the password and steps the policy down to optional without the provider.

What Orbit checks on a SAML sign-in

A signed assertion only, with exclusive canonicalization and SHA-256. One assertion with one signature over its own id, no DTD, InResponseTo equal to the request Orbit made, recipient and audience, a 10-minute condition window, authentication no older than 5 minutes (30 seconds of clock skew), and single use of every assertion id. Every SAML sign-in asks the IdP to authenticate again. Keep your server clocks in sync.

Certificate rotation

You can hold up to four IdP certificates, so the next one can be added before the old one is removed. Certificate expiry is checked at every sign-in. An expired certificate stops SAML sign-in without a warning, so watch notAfter in the connection details.

What is not there

• Single Logout. Orbit sign-out is local.
• Encrypted assertions, which are refused.
• IdP-initiated sign-in. An unsolicited response is refused.
• Group-based access. Groups sent by SCIM are stored but not mapped.

Status

In development

SAML 2.0 and OIDC sign-in, enrollment of existing members, and the required sign-in policy are in development. See also Provision people with SCIM.