​

SAML single sign-on

Experimental, off by default. SAML sign-in and SCIM provisioning sit behind the saml-scim beta feature: turn it on under Settings, Beta features or with APP_EXPERIMENTAL=saml-scim. While off, the routes answer 404, the settings page and the sign-in button are hidden, and a “require single sign-on” setting is not applied. The service provider is the sign-in library’s native SAML implementation; Levelrail adds a stricter response check, account policy and role mapping around it. It is tested against a signing test identity provider, not yet against a live Okta, Entra ID or Keycloak tenant (see What has not been verified).

​

Before you start

• An https dashboard URL. Set it under Settings, General. Identity providers post sign-in responses to it, and the SP entity ID and assertion consumer service (ACS) URL are built from it, never from the request’s Host header. When the dashboard URL changes, the connection’s URLs follow at its next use.
• The control plane master key. The service provider signing key is generated at the first start with a master key and stored encrypted with it. Without one, SAML stays off and the settings page says so.
• Root. Every SSO setting needs a root session or token.

​

Set up a connection

1. Open Settings, Single sign-on and choose Add SAML connection. Give it the name people will see on the button and save it.
2. Open Configure. Copy the three service provider values into a new SAML app at your IdP:

   Value	Where it goes
   Entity ID (audience)	https://<dashboard>/api/v1/auth/saml/<id>/metadata
   ACS URL	https://<dashboard>/api/v1/auth/saml/<id>/acs, HTTP-POST binding
   Metadata URL	Same as the entity ID. Many IdPs can import it directly

3. Back in the sheet, paste the IdP metadata URL or XML and choose Import metadata. That fills the IdP entity ID, sign-in URL and signing certificate. When the metadata lists several signing certificates, the newest one valid today is kept.
4. Pick who may sign in (see Accounts), turn on Show on the sign-in page and save.

levelrail-cli sso saml create "Okta" --default-role role_viewer --jit
levelrail-cli sso saml import-metadata saml_abc --url https://example.okta.com/app/xyz/sso/saml/metadata
levelrail-cli sso saml update saml_abc --enabled --sync-roles
levelrail-cli sso saml metadata saml_abc > sp-metadata.xml
levelrail-cli sso saml list

​

What is checked on every sign-in

• InResponseTo names the AuthnRequest this browser started, and the assertion carries a bearer confirmation for that same request. Each request ID is single use, expires after ten minutes, and is bound to the browser by a secure cookie. This is what refuses IdP-initiated, forwarded and replayed responses: the library on its own accepts IdP-initiated responses and does not check InResponseTo.
• The assertion names this connection’s entity ID as its audience. An assertion without an audience restriction is refused.
• The response carries a valid XML signature from the stored IdP certificate, the issuer is the configured IdP entity ID, Destination and the bearer Recipient are this connection’s ACS URL, NotBefore and NotOnOrAfter hold (three minutes of clock skew), and the response and assertion are no older than 90 seconds.

• The same signature, issuer, audience and time checks, plus: the assertion itself must be signed. A response that is signed only on the outer element is refused.

​

Accounts and roles

1. A subject (NameID) already linked to an account through this connection.
2. An existing account with the same email. The subject is linked to it.
3. A new account, only when Create accounts on first sign-in (--jit) is on. Without it, people need an account first (for example an invite).

​

How this maps onto the library

​

Group to role mappings

levelrail-cli sso mappings set --map Admins=role_admin:100 --map Engineering=role_operator:10 --map everyone=role_viewer
levelrail-cli sso mappings list

​

Require single sign-on

​

Break-glass access

sudo APP_DATA_DIR=/var/lib/levelrail-data /usr/local/bin/levelrail recover-admin --username admin

​

IdP setup guides

​

Okta

1. Applications, Create App Integration, SAML 2.0.
2. Single sign-on URL: the ACS URL. Check Use this for Recipient URL and Destination URL.
3. Audience URI (SP Entity ID): the entity ID.
4. Name ID format: EmailAddress. Application username: Email.
5. Attribute statements: email = user.email, displayName = user.displayName. Set the connection’s email attribute to email and name attribute to displayName.
6. Group attribute statements: name groups, filter Matches regex .* (or a narrower filter). Set the connection’s groups attribute to groups.
7. Finish, then on the Sign On tab copy the Metadata URL and import it.

​

Microsoft Entra ID

1. Enterprise applications, New application, Create your own application, then Set up single sign on, SAML.
2. Basic SAML Configuration: Identifier (Entity ID) = the entity ID, Reply URL (ACS) = the ACS URL. Leave Sign on URL empty.
3. Attributes & Claims: keep the default email claim, which matches the default email attribute. Add a group claim and set the connection’s groups attribute to http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. Choose Cloud-only group display names to receive names, or put the group object IDs in your mappings.
4. Copy the App Federation Metadata Url from the SAML Certificates section and import it.
5. Assign users or groups to the application, or Entra refuses them.

​

Keycloak

1. In the realm, Clients, Create client, type SAML, Client ID = the entity ID.
2. Valid redirect URIs: the ACS URL. Master SAML Processing URL: the ACS URL.
3. Keys tab: turn Client signature required off unless you upload the service provider certificate.
4. Signature and Encryption: keep Sign assertions on. Signing only the document is refused.
5. Client scopes, dedicated scope, Add mapper: a User Property mapper for email (SAML attribute name email) and a Group list mapper with attribute name groups and Full group path off. Set the connection’s attribute names to match.
6. Import https://<keycloak>/realms/<realm>/protocol/saml/descriptor.

​

What has not been verified

• Sign-in against a live Okta, Entra ID or Keycloak tenant. The tests sign responses with a local test IdP built on the same SAML library.
• Encrypted assertions.
• An IdP certificate rotation: a connection holds one signing certificate, so the new certificate has to be imported at the moment the IdP switches.

​

Troubleshooting

​

API