Skip to content

Sign in with SSO ​

Configure browser access on API, not web.

ORPHEUS_BROWSER_AUTHReadsTemplate managementSession commands
api_onlyBearer keyBearer keyBearer key
anonymousNo sign-inBrowser or Bearer keyBearer key
samlSSO session or Bearer keySSO session or Bearer keyBearer key

Use anonymous for an isolated local stack. All users admitted through SAML share the same history. Restrict admission at the identity provider.

Configure SAML ​

Supply these environment variables to API:

dotenv
ORPHEUS_BROWSER_AUTH=saml
ORPHEUS_PUBLIC_URL=https://orpheus.example.com
SAML_SP_ENTITY_ID=orpheus-web
SAML_IDP_METADATA_FILE=/etc/orpheus/saml/idp.xml
SAML_SP_CERT_FILE=/etc/orpheus/saml/sp.crt
SAML_SP_KEY_FILE=/run/secrets/orpheus-saml.key
BROWSER_SESSION_TTL_SECONDS=43200
  1. Create an SP certificate and matching RSA or ECDSA private key.
  2. Create a SAML client at the IdP with entity ID orpheus-web.
  3. Set ACS to https://orpheus.example.com/auth/callback, HTTP-POST binding.
  4. Validate request signatures with the SP certificate and sign responses and assertions using SHA-256.
  5. Configure a stable NameID and an AuthnStatement. In Keycloak, set saml.authnstatement to true.
  6. Export IdP metadata. Mount the XML, certificate and key into API at the configured paths.
  7. Recreate API and verify sign-in. SP metadata is available at /saml/metadata.

ORPHEUS_PUBLIC_URL is the external HTTPS web origin without a trailing slash. The worker does not need SAML files.

Logout ends the local Orpheus session. The organization-wide IdP session remains active. Keycloak configuration.

Template management from the browser ​

All SAML users can add, edit and delete templates. Local anonymous access has the same permissions. Browser writes require the exact Origin configured in ORPHEUS_PUBLIC_URL and the header X-Orpheus-CSRF: 1. Orpheus Web sends these automatically. For local access set ORPHEUS_PUBLIC_URL=http://localhost:8085 and open that address.

A different origin or missing CSRF header returns 403 invalid_origin. A valid Bearer key does not require these headers. An invalid Authorization header returns 401 even if a browser session is present.