API Authentification unique

Indique à la page d’entrée comment une adresse courriel se connecte ou s’inscrit. sso, required et provider_name sont déterminés par le domaine de l’adresse seul, d’après les domaines vérifiés des organisations qui ont une connexion de fournisseur d’identité activée : sso est true lorsqu’une telle organisation détient le domaine. required est true lorsque cette organisation exige l’authentification unique, ce qui refuse la connexion par mot de passe et par clé d’accès pour le domaine (createDashboardSession répond sso_required) ; ses administrateurs d’urgence conservent la connexion par clé d’accès. provider_name est le nom d’affichage de la connexion, présent seulement lorsque sso est true. account est true lorsqu’une personne active détient l’adresse, vérifiée ou non, et false lorsque personne ne la détient : la page connecte la personne lorsqu’il est true et propose l’inscription (POST /api/signups) lorsqu’il est false et que sso est false.

Limité par adresse cliente.

Lance une ouverture de session par authentification unique auprès du fournisseur d’identité de l’organisation qui détient le domaine de l’adresse et répond par l’adresse du fournisseur, vers laquelle la page navigue. La réponse pose le cookie __Host-screenrig-sso (HttpOnly, Secure, SameSite=Strict, Path=/, 10 minutes) qui lie ce navigateur à l’ouverture de session.

Une connexion OIDC se voit demander le flux de code d’autorisation avec PKCE S256, un nonce et response_mode form_post; une connexion SAML reçoit une AuthnRequest HTTP-Redirect.

Le fournisseur répond par un POST vers /api/sso/oidc/{connection_id}/callback ou /api/sso/saml/{connection_id}/acs de la connexion, et l’ouverture de session se termine à /api/sso/finish. return_to est un chemin sous /dashboard/ où aboutit l’ouverture de session; en son absence, elle aboutit à /dashboard/. invitation_token est une invitation que l’ouverture de session accepte une fois la personne connectée. prompt none demande au fournisseur une ouverture de session silencieuse, qui se termine à /dashboard/#sso_error=interaction_required lorsque la personne doit intervenir; prompt login fait authentifier de nouveau la personne par le fournisseur.

Une adresse dont le domaine n’a aucune connexion activée est not_found. Limité par adresse cliente.

L’URI de redirection OIDC d’une connexion. Le fournisseur d’identité envoie ici un POST depuis un autre site (response_mode form_post), de sorte qu’aucun cookie du tableau de bord n’arrive. La route ne connecte personne : elle répond par une page qui envoie par POST les mêmes membres et l’id de la connexion à /api/sso/finish depuis l’origine du tableau de bord, où arrive le cookie de transaction.

Une réponse ne termine qu’une ouverture de session démarrée par cette connexion; toute autre se termine à /dashboard/#sso_error=bad_state. Lorsque le document de découverte du fournisseur définit authorization_response_iss_parameter_supported, une réponse sans iss (RFC 9207) se termine à /dashboard/#sso_error=verification_failed.

La page exécute un script en ligne protégé par un nonce et comporte un bouton noscript; sa Content-Security-Policy est stricte, Cache-Control vaut no-store et Referrer-Policy vaut no-referrer. Un id qu’aucune connexion ne détient est not_found.

Les métadonnées du fournisseur de services SAML d’une connexion. Son entityID est l’adresse de cette route et son service consommateur d’assertions est /api/sso/saml/{connection_id}/acs avec la liaison HTTP-POST. Un administrateur du fournisseur d’identité les importe, ou copie les mêmes valeurs depuis le service_provider de la connexion. Un id qu’aucune connexion ne détient est not_found.

Le service consommateur d’assertions SAML d’une connexion. Le fournisseur d’identité envoie ici un POST depuis un autre site, de sorte qu’aucun cookie du tableau de bord n’arrive. La route ne connecte personne : elle répond par une page qui envoie par POST le SAMLResponse, son RelayState et l’id de la connexion à /api/sso/finish depuis l’origine du tableau de bord, où arrive le cookie de transaction.

Une réponse ne termine qu’une ouverture de session démarrée par cette connexion. La page exécute un script en ligne protégé par un nonce et comporte un bouton noscript; sa Content-Security-Policy est stricte, Cache-Control vaut no-store et Referrer-Policy vaut no-referrer. Un id qu’aucune connexion ne détient est not_found.

Termine une ouverture de session par authentification unique sur l’origine du tableau de bord, où arrive le cookie __Host-screenrig-sso. Le formulaire est state, la connexion pour laquelle la réponse est arrivée, et la réponse du fournisseur d’identité telle que la page de rappel l’a copiée : code, error, error_description et iss pour OIDC, SAMLResponse pour SAML (state est le RelayState).

La route lie state au cookie, refuse une réponse arrivée pour une autre connexion que celle par laquelle l’ouverture de session a démarré, vérifie le jeton ou l’assertion du fournisseur, applique les règles d’adoption et de liaison de comptes, vérifie la politique d’ouverture de session de l’organisation et répond 303.

Une ouverture de session, un renouvellement ou une réauthentification émet une session du tableau de bord avec auth_method sso, qui dure 24 heures à compter de cette ouverture de session et n’est pas prolongée par l’usage, accepte l’invitation que porte l’ouverture de session, pose le cookie __Host-screenrig-dashboard, fait expirer le cookie de transaction et redirige vers return_to, ou vers /dashboard/.

Un lien ajoute l’identité au compte de la personne connectée et conserve sa session. Un test consigne son résultat sur la connexion (last_test) et ne connecte personne. Chaque échec répond aussi 303, vers /dashboard/#sso_error=<code>, et jamais par un document de problème.

Les codes sont no_email, email_unverified, domain_not_allowed, account_exists (la personne se connecte comme auparavant et établit le lien depuis son compte), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (un renouvellement silencieux requiert la personne), provider_refused, provider_unavailable, verification_failed et deactivated (SSOErrorCode).

Lance une ouverture de session par authentification unique pour la personne connectée et répond par l’adresse du fournisseur d’identité, comme le fait POST /api/sso/starts pour une adresse, en posant le cookie __Host-screenrig-sso. intent renew renouvelle une session ouverte par authentification unique, en silence (prompt none), avant la fin de ses 24 heures; le tableau de bord le fait après 12 heures écoulées. intent reauth fait authentifier de nouveau la personne par le fournisseur (prompt login), ce qui donne à une session l’ouverture de session récente qu’exige la preuve sso. intent link rattache l’identité de la personne chez le fournisseur à son compte existant. renew et reauth exigent une session ouverte par authentification unique, et link exige une connexion activée au domaine vérifié de la personne; sinon la réponse est resource_conflict. return_to est un chemin sous /dashboard/.

Un administrateur désigné lit la connexion d’authentification unique de l’organisation : son protocole et son fournisseur, les valeurs du fournisseur de services à saisir chez le fournisseur d’identité (l’URI de redirection OIDC, l’ID d’entité SAML, les adresses du service consommateur d’assertions et des métadonnées), sa politique d’ouverture de session et le résultat du dernier test.

Le secret client n’est jamais renvoyé; client_secret_set indique si un secret est stocké. ready_to_require est true dès que l’organisation détient un domaine vérifié et qu’un test ou une véritable ouverture de session a réussi avec l’identité actuelle de la connexion (son issuer, son locataire, son ID d’entité et son kind); Require SSO n’est accepté que tant qu’il est true. L’ETag porte la révision.

Une organisation sans connexion est not_found. Toute autre personne est refusée comme sur les autres routes administrateur d’organisation. Uniquement des personnes; les agents et les identifiants porteurs n’ont pas de route.

Un administrateur désigné crée la connexion de l’organisation ou la modifie; une organisation en détient une.

If-Match porte la révision de la connexion obtenue par GET, ou 0 lorsque l’organisation n’en a aucune, et est obligatoire; une valeur obsolète donne revision_conflict avec current_revision. 201 crée et 200 modifie. proof est obligatoire : une preuve récente par clé d’accès ou mot de passe liée à une réauthentification de kind identity_provider_change avec l’ID de l’organisation comme subject_id, ou {type: sso} d’une session ouverte par authentification unique il y a 10 minutes au plus (sinon reauthentication_required).

OIDC avec le preset entra prend tenant_id et en construit l’issuer; le preset generic prend issuer. Omettre oidc.client_secret conserve le secret stocké.

Pour SAML, metadata_xml est lu pour l’ID d’entité, l’adresse d’ouverture de session et les certificats de signature du fournisseur d’identité, et idp_entity_id, idp_sso_url et certificates_pem les indiquent directement; certificates_pem remplace la liste stockée, qui en contient au plus 4 afin qu’un nouveau certificat puisse chevaucher l’ancien pendant la rotation.

Tant que Require SSO est en vigueur, un changement d’identité (issuer, locataire, ID d’entité ou kind) donne resource_conflict, et la rotation des certificats et du secret client est permise; hors de ce cas, un changement d’identité met ready_to_require à false jusqu’à ce qu’un test ou une ouverture de session réussisse. Renvoie la connexion avec son ETag. Uniquement des personnes; les agents et les identifiants porteurs n’ont pas de route.

La création de la première connexion (If-Match 0) relève de l’authentification unique, que le forfait Enterprise inclut ; une organisation dont le forfait n’inclut pas cette fonctionnalité est refusée avec feature_not_in_plan (402).

La modification d’une connexion existante, comme la rotation d’un certificat ou d’un secret client ou l’actualisation des métadonnées, ainsi que sa lecture, son test et son retrait, sont ouverts à tous les forfaits, et une connexion existante continue d’ouvrir la session des personnes.

Un administrateur désigné retire la connexion de l’organisation après une preuve récente (le corps porte proof, comme pour PUT). Le résultat est resource_conflict tant que Require SSO est en vigueur, retrait planifié compris, et not_found lorsque l’organisation n’a aucune connexion. Uniquement des personnes; les agents et les identifiants porteurs n’ont pas de route.

Un administrateur désigné lance un test d’ouverture de session par la connexion de l’organisation, pour prouver qu’elle fonctionne avant de l’exiger. Il répond par l’adresse du fournisseur d’identité vers laquelle la page navigue et pose le cookie __Host-screenrig-sso.

La réponse du fournisseur aboutit à /api/sso/finish, qui consigne le résultat sur la connexion (last_test; un succès permet à ready_to_require de devenir true) et ramène le navigateur au tableau de bord. Un test ne connecte personne. Une organisation sans connexion est not_found. Uniquement des personnes; les agents et les identifiants porteurs n’ont pas de route.

Un administrateur désigné active ou désactive Require SSO et nomme les administrateurs d’urgence. required true refuse l’ouverture de session par mot de passe et par clé d’accès pour les domaines vérifiés de l’organisation (sso_required) et exige un domaine vérifié et ready_to_require sur la connexion, sinon resource_conflict; il incrémente policy_revision. required false ne lève pas l’exigence immédiatement : il planifie le retrait 72 heures après la requête (enforcement_ends_at) et envoie un courriel à chaque administrateur, et DELETE .../sso-policy/removal l’annule. break_glass_user_ids nomme au plus 2 administrateurs désignés qui détiennent une clé d’accès, sinon invalid_request; ils conservent l’ouverture de session par clé d’accès tant que l’authentification unique est exigée, et chacune de ces ouvertures de session est auditée.

If-Match porte policy_revision et est obligatoire; une valeur obsolète donne revision_conflict avec current_revision. proof est obligatoire : une preuve récente par clé d’accès ou mot de passe liée à une réauthentification de kind sso_policy_change avec l’ID de l’organisation comme subject_id, ou {type: sso} d’une session ouverte par authentification unique il y a 10 minutes au plus.

Renvoie la politique avec son ETag. Uniquement des personnes ; les agents et les identifiants porteurs n’ont pas de route. Définir required true relève de l’authentification unique, que le forfait Enterprise inclut ; une organisation dont le forfait n’inclut pas cette fonctionnalité est refusée avec feature_not_in_plan (402). required false est toujours accepté, et Require SSO, lorsqu’il est activé, reste en vigueur jusqu’à ce qu’il soit désactivé.

Tout administrateur désigné annule un retrait planifié de Require SSO, qui reste alors en vigueur. Sans retrait planifié, rien ne change. Répond par la politique. Uniquement des personnes; les agents et les identifiants porteurs n’ont pas de route.