Single Sign-on-API

Teilt der Einstiegsseite mit, wie sich eine E-Mail-Adresse anmeldet oder registriert. sso, required und provider_name werden allein von der Domain der Adresse bestimmt, anhand der verifizierten Domains von Organisationen, die eine aktivierte Identitätsanbieter-Verbindung haben: sso ist true, wenn eine solche Organisation die Domain besitzt. required ist true, wenn diese Organisation Single Sign-on verlangt, was die Anmeldung per Passwort und Passkey für die Domain ablehnt (createDashboardSession antwortet mit sso_required); ihre Break-Glass-Administratoren behalten die Passkey-Anmeldung. provider_name ist der Anzeigename der Verbindung und nur vorhanden, wenn sso true ist. account ist true, wenn eine aktive Person die Adresse besitzt, ob verifiziert oder nicht, und false, wenn niemand sie besitzt: Die Seite meldet die Person an, wenn account true ist, und bietet die Registrierung an (POST /api/signups), wenn account false und sso false ist.

Pro Client-Adresse begrenzt.

Startet eine Single-Sign-on-Anmeldung über den Identitätsanbieter der Organisation, zu der die Domain der Adresse gehört, und antwortet mit der Adresse des Anbieters, zu der die Seite navigiert. Die Antwort setzt das Cookie __Host-screenrig-sso (HttpOnly, Secure, SameSite=Strict, Path=/, 10 Minuten), das diesen Browser an die Anmeldung bindet.

Bei einer OIDC-Verbindung wird der Authorization-Code-Flow mit PKCE S256, einer Nonce und response_mode form_post angefordert; eine SAML-Verbindung erhält einen AuthnRequest per HTTP-Redirect.

Der Anbieter antwortet per POST an /api/sso/oidc/{connection_id}/callback oder /api/sso/saml/{connection_id}/acs der Verbindung, und die Anmeldung endet bei /api/sso/finish. return_to ist ein Pfad unter /dashboard/, auf dem die Anmeldung landet; fehlt er, landet sie auf /dashboard/. invitation_token ist eine Einladung, die die Anmeldung annimmt, sobald die Person angemeldet ist. prompt none fordert vom Anbieter eine stille Anmeldung an, die bei /dashboard/#sso_error=interaction_required endet, wenn die Person handeln muss; prompt login lässt den Anbieter die Person erneut authentifizieren.

Eine Adresse, deren Domain keine aktivierte Verbindung hat, ist not_found. Pro Client-Adresse begrenzt.

Die OIDC-Redirect-URI einer Verbindung. Der Identitätsanbieter sendet von einer anderen Website hierher per POST (response_mode form_post), sodass kein Dashboard-Cookie ankommt. Die Route meldet niemanden an: Sie antwortet mit einer Seite, die dieselben Felder und die Verbindungs-ID vom Dashboard-Origin aus, wo das Transaktions-Cookie ankommt, per POST an /api/sso/finish sendet.

Eine Antwort schließt nur eine Anmeldung ab, die diese Verbindung gestartet hat; jede andere endet bei /dashboard/#sso_error=bad_state. Wenn das Discovery-Dokument des Anbieters authorization_response_iss_parameter_supported setzt, endet eine Antwort ohne iss (RFC 9207) bei /dashboard/#sso_error=verification_failed.

Die Seite führt ein Inline-Skript aus, das durch eine Nonce geschützt ist, und enthält eine noscript-Schaltfläche; ihre Content-Security-Policy ist streng, Cache-Control ist no-store und Referrer-Policy ist no-referrer. Eine ID, die keine Verbindung hat, ist not_found.

Die SAML-Service-Provider-Metadaten einer Verbindung. Ihre entityID ist die Adresse dieser Route, und ihr Assertion Consumer Service ist /api/sso/saml/{connection_id}/acs mit dem HTTP-POST-Binding. Ein Administrator des Identitätsanbieters importiert sie oder kopiert dieselben Werte aus service_provider der Verbindung. Eine ID, die keine Verbindung hat, ist not_found.

Der SAML Assertion Consumer Service einer Verbindung. Der Identitätsanbieter sendet von einer anderen Website hierher per POST, sodass kein Dashboard-Cookie ankommt. Die Route meldet niemanden an: Sie antwortet mit einer Seite, die SAMLResponse, RelayState und die Verbindungs-ID vom Dashboard-Origin aus, wo das Transaktions-Cookie ankommt, per POST an /api/sso/finish sendet.

Eine Antwort schließt nur eine Anmeldung ab, die diese Verbindung gestartet hat. Die Seite führt ein Inline-Skript aus, das durch eine Nonce geschützt ist, und enthält eine noscript-Schaltfläche; ihre Content-Security-Policy ist streng, Cache-Control ist no-store und Referrer-Policy ist no-referrer. Eine ID, die keiner Verbindung gehört, ist not_found.

Schließt eine Single-Sign-on-Anmeldung auf dem Dashboard-Origin ab, wo das Cookie __Host-screenrig-sso ankommt. Das Formular besteht aus state, der Verbindung, für die die Antwort eingegangen ist, und der Antwort des Identitätsanbieters, wie die Callback-Seite sie kopiert hat: code, error, error_description und iss für OIDC, SAMLResponse für SAML (state ist der RelayState).

Die Route bindet state an das Cookie, lehnt eine Antwort ab, die für eine andere Verbindung eingetroffen ist als die, über die die Anmeldung gestartet wurde, verifiziert das Token oder die Assertion des Anbieters, wendet die Regeln für Kontoübernahme und Verknüpfung an, prüft die Anmelderichtlinie der Organisation und antwortet mit 303.

Eine Anmeldung, Erneuerung oder Reauthentifizierung erzeugt eine Dashboard-Sitzung mit auth_method sso (gültig 24 Stunden ab dieser Anmeldung, nicht durch Nutzung verlängert), nimmt die Einladung an, die die Anmeldung mitführt, setzt das Cookie __Host-screenrig-dashboard, lässt das Transaktions-Cookie ablaufen und leitet zu return_to oder zu /dashboard/ weiter.

Eine Verknüpfung fügt die Identität dem Konto der angemeldeten Person hinzu und behält deren Sitzung bei. Ein Test hält sein Ergebnis an der Verbindung fest (last_test) und meldet niemanden an. Jeder Fehler antwortet außerdem mit 303, auf /dashboard/#sso_error=<code>, und nie mit einem Problem-Dokument.

Die Codes sind no_email, email_unverified, domain_not_allowed, account_exists (die Person meldet sich wie bisher an und verknüpft von ihrem Konto aus), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (eine stille Erneuerung braucht die Person), provider_refused, provider_unavailable, verification_failed und deactivated (SSOErrorCode).

Startet eine Single-Sign-on-Anmeldung für die angemeldete Person und antwortet mit der Adresse des Identitätsanbieters, wie POST /api/sso/starts es für eine Adresse tut, und setzt das Cookie __Host-screenrig-sso. intent renew erneuert eine Sitzung, die über Single Sign-on angemeldet wurde, still (prompt none), bevor ihre 24 Stunden enden; das Dashboard tut dies, sobald 12 Stunden vergangen sind. intent reauth lässt den Anbieter die Person erneut authentifizieren (prompt login), wodurch eine Sitzung die kürzliche Anmeldung erhält, die der sso-Nachweis benötigt. intent link verknüpft die Identität der Person beim Anbieter mit ihrem bestehenden Konto. renew und reauth benötigen eine Sitzung, die über Single Sign-on angemeldet wurde, und link benötigt eine aktivierte Verbindung an der verifizierten Domain der Person; andernfalls lautet die Antwort resource_conflict. return_to ist ein Pfad unter /dashboard/.

Ein benannter Administrator liest die Single-Sign-on-Verbindung der Organisation: ihr Protokoll und ihren Anbieter, die Service-Provider-Werte, die beim Identitätsanbieter einzutragen sind (die OIDC-Redirect-URI, die SAML-Entity-ID sowie die Adressen von Assertion Consumer Service und Metadaten), ihre Anmelderichtlinie und das Ergebnis des letzten Tests.

Das Client-Secret wird nie zurückgegeben; client_secret_set gibt an, ob eines gespeichert ist. ready_to_require ist true, sobald die Organisation eine verifizierte Domain hat und ein Test oder eine echte Anmeldung über die aktuelle Identität der Verbindung (ihren Issuer, Mandanten, ihre Entity-ID und Art) erfolgreich war; Require SSO wird nur akzeptiert, solange es true ist. Der ETag trägt die Revision.

Eine Organisation ohne Verbindung ist not_found. Alle anderen Personen werden wie auf den übrigen Admin-Routen der Organisation abgelehnt. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route.

Ein benannter Administrator legt die Verbindung der Organisation an oder ändert sie; eine Organisation hat eine.

If-Match trägt die Revision der Verbindung aus GET oder 0, wenn die Organisation keine hat, und ist erforderlich; ein veralteter Wert ist revision_conflict mit current_revision. 201 legt an und 200 ändert. proof ist erforderlich: ein frischer Passkey- oder Passwort-Nachweis, gebunden an eine Reauthentifizierung der Art identity_provider_change mit der Organisations-ID als subject_id, oder {type: sso} aus einer Sitzung, die sich vor höchstens 10 Minuten über Single Sign-on angemeldet hat (sonst reauthentication_required).

OIDC mit preset entra nimmt tenant_id entgegen und bildet daraus den Issuer; preset generic nimmt issuer entgegen. Wird oidc.client_secret ausgelassen, bleibt das gespeicherte Secret erhalten.

Bei SAML wird metadata_xml auf Entity-ID, Anmeldeadresse und Signaturzertifikate des Identitätsanbieters gelesen, und idp_entity_id, idp_sso_url und certificates_pem geben sie direkt an; certificates_pem ersetzt die gespeicherte Liste, die höchstens 4 Einträge enthält, damit ein neues Zertifikat das alte während der Rotation überlappen kann.

Solange Require SSO gilt, ist eine Änderung der Identität (Issuer, Mandant, Entity-ID oder Art) resource_conflict, und die Rotation von Zertifikat und Client-Secret ist erlaubt; außerhalb davon setzt eine Änderung der Identität ready_to_require auf false, bis ein Test oder eine Anmeldung erfolgreich ist. Gibt die Verbindung mit ihrem ETag zurück. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route.

Das Anlegen der ersten Verbindung (If-Match 0) fällt unter das Single Sign-on, das der Enterprise-Plan enthält; eine Organisation, deren Plan dies nicht enthält, wird mit feature_not_in_plan (402) abgelehnt.

Das Ändern einer bestehenden Verbindung, etwa das Rotieren eines Zertifikats oder Client-Geheimnisses oder das Aktualisieren der Metadaten, sowie das Lesen, Testen und Entfernen einer Verbindung sind in jedem Plan offen, und eine bestehende Verbindung meldet weiterhin Personen an.

Ein benannter Administrator entfernt die Verbindung der Organisation nach frischem Nachweis (der Body enthält proof, wie bei PUT). Es ist resource_conflict, solange Require SSO gilt, eine geplante Entfernung eingeschlossen, und not_found, wenn die Organisation keine Verbindung hat. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route.

Ein benannter Administrator startet eine Test-Anmeldung über die Verbindung der Organisation, um zu belegen, dass sie funktioniert, bevor sie verlangt wird. Die Antwort enthält die Adresse des Identitätsanbieters, zu der die Seite navigiert, und setzt das Cookie __Host-screenrig-sso.

Die Antwort des Anbieters endet bei /api/sso/finish, das das Ergebnis an der Verbindung festhält (last_test; ein Erfolg lässt ready_to_require true werden) und den Browser zum Dashboard zurückführt. Ein Test meldet niemanden an. Eine Organisation ohne Verbindung ist not_found. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route.

Ein benannter Administrator schaltet Require SSO ein oder aus und benennt die Break-Glass-Administratoren. required true lehnt die Anmeldung per Passwort und Passkey für die verifizierten Domains der Organisation ab (sso_required) und setzt eine verifizierte Domain und ready_to_require an der Verbindung voraus, sonst resource_conflict; es erhöht policy_revision. required false hebt die Pflicht nicht sofort auf: Es plant die Entfernung für 72 Stunden nach der Anfrage (enforcement_ends_at) und benachrichtigt jeden Administrator per E-Mail, und DELETE .../sso-policy/removal bricht sie ab. break_glass_user_ids benennt höchstens 2 benannte Administratoren, die einen Passkey besitzen, sonst invalid_request; sie behalten die Passkey-Anmeldung, solange SSO verlangt wird, und jede solche Anmeldung wird protokolliert.

If-Match trägt policy_revision und ist erforderlich; ein veralteter Wert ist revision_conflict mit current_revision. proof ist erforderlich: ein frischer Passkey- oder Passwort-Nachweis, gebunden an eine Reauthentifizierung der Art sso_policy_change mit der Organisations-ID als subject_id, oder {type: sso} aus einer Sitzung, die sich vor höchstens 10 Minuten über Single Sign-on angemeldet hat.

Gibt die Richtlinie mit ihrem ETag zurück. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route. Das Setzen von required true fällt unter das Single Sign-on, das der Enterprise-Plan enthält; eine Organisation, deren Plan dies nicht enthält, wird mit feature_not_in_plan (402) abgelehnt. required false wird immer akzeptiert, und ein aktives Require SSO bleibt durchgesetzt, bis es ausgeschaltet wird.

Jeder benannte Administrator bricht eine geplante Entfernung von Require SSO ab, sodass es in Kraft bleibt. Ist keine Entfernung geplant, ändert sich nichts. Antwortet mit der Richtlinie. Nur Personen; Agenten und Bearer-Anmeldeinformationen haben keine Route.