Exécuter une étape de connexion

POST /fapi/v1/transactions/current/steps/{step} · appelé depuis l'hôte de connexion de l'environnement

Exécute une étape de la transaction en cours. Cette version accepte les étapes identifier et password. Chaque étape d'identifiants en échec renvoie le même 401 invalid_credentials, de sorte que la réponse ne révèle jamais si un compte existe. Lorsque l'étape du mot de passe termine la transaction, les cookies de session __Host-idp_session (et, si nécessaire, __Host-idp_device) sont définis et le cookie de transaction est supprimé.

Requête

En-têtes :

Chemin : step, le nom de l'étape (identifier, password, sso_start).

À l'étape otp_send, next_steps[].methods liste les méthodes sans mot de passe autorisées par la politique effective (email_otp, magic_link) ; un client ne propose que celles-ci.

Corps (les champs dépendent de l'étape ; next_steps[].fields les énumère) :

Réponse

200 OK avec la transaction après l'étape. Une transaction completed n'a pas de csrf_token.

Lorsque l'environnement exige un second facteur et que l'utilisateur n'en a pas encore, un utilisateur encore dans le mfa.enrollment_grace_days de l'environnement se connecte malgré tout et la réponse completed contient mfa_enrollment : required_by (RFC 3339, fin de la période de grâce, calculée par le serveur) et methods (webauthn, totp : les facteurs que l'utilisateur peut inscrire maintenant, dans l'ordre de l'écran). Affichez la date et laissez l'utilisateur continuer ; l'inscription se fait dans les paramètres du compte. Le champ est absent lorsqu'il n'y a pas de période de grâce, que l'utilisateur respecte la politique, ou que l'inscription est exigée immédiatement. Le min_acr d'une application et le acr_values demandé ne sont jamais reportés par la période de grâce.

SSO d'entreprise (découverte du domaine)

Lorsque l'étape identifier reçoit une adresse e-mail dont le domaine appartient à une connexion d'entreprise, la connexion se poursuit avec cette connexion. Seule la partie après @ est utilisée pour la découverte.

• Une seule connexion : la transaction passe à federated_redirect et la réponse contient redirect_url, l'adresse de démarrage du fournisseur d'identité. Naviguez vers cette adresse dans la fenêtre de premier niveau. L'adresse contient un jeton à usage unique : ne le stockez pas et ne le journalisez pas.
• Plusieurs connexions : la transaction reste dans identifier_pending et la réponse liste sso_connections (connection_id, display_name, protocol). Affichez display_name sous forme de texte et envoyez le choix de l'utilisateur avec l'étape sso_start (identifier et connection_id). Une connexion non proposée pour le domaine renvoie 422 validation_failed.
• Aucune connexion, ou découverte temporairement indisponible : la connexion normale se poursuit, de sorte qu'une panne ne bloque jamais les autres méthodes de connexion. sso_start est un choix explicite et renvoie 503 temporarily_unavailable à la place.

Lorsque la demande de connexion désigne une organisation qui exige le SSO, la transaction ne propose que les connexions de cette organisation : les étapes du mot de passe et du code par e-mail ne sont pas proposées, et la clé d'accès ne reste disponible que si l'organisation dispose de comptes d'urgence (break-glass). La création de la transaction démarre déjà l'unique connexion (federated_redirect avec redirect_url) ou en liste plusieurs dans sso_connections ; envoyez le choix avec sso_start et connection_id seuls, identifier est facultatif ici. Sous cette exigence, la découverte ne revient pas à d'autres méthodes : lorsque la connexion d'entreprise est inaccessible, l'étape renvoie 503 temporarily_unavailable. Il en va de même lorsque le domaine de l'e-mail appartient à une organisation qui exige le SSO pour ses domaines vérifiés.

Après le fournisseur d'identité, le navigateur revient vers /u/sso/complete sur l'hôte de connexion ; la page hébergée termine la connexion.

Lier la connexion d'entreprise à un compte existant

Lorsqu'une connexion d'entreprise ne garantit pas les adresses e-mail et que l'adresse qu'elle affirme est déjà vérifiée sur un compte de l'environnement, la connexion d'entreprise n'ouvre pas de session. Le navigateur revient vers la page de connexion hébergée avec une nouvelle transaction dont l'objet contient account_link : connection_name et, lorsque la connexion appartient à une organisation, organization_name. Indiquez à l'utilisateur qu'il possède déjà un compte et qu'il doit s'y connecter pour lier la connexion ; ne nommez jamais le compte. Dans cette transaction, sso_start et magic_link ne sont pas proposés, et l'étape identifier n'oriente pas vers une connexion d'entreprise.

L'utilisateur se connecte au compte existant avec ses propres méthodes ; un utilisateur qui a un second facteur inscrit doit le fournir. L'étape qui termine la transaction n'ouvre aucune session : la connexion est liée au compte, et la réponse est une nouvelle transaction en federated_redirect avec redirect_url pour la même connexion. Naviguez vers cette transaction dans la fenêtre de premier niveau ; la connexion d'entreprise se termine alors normalement. Si la connexion d'entreprise ne peut pas démarrer, la nouvelle transaction est identifier_pending et une connexion ordinaire suit.

Une finalisation avec un autre compte, sans le second facteur inscrit, ou avec une connexion plus ancienne que la demande de liaison, ne lie rien et n'ouvre aucune session : 409 transaction_state_conflict. Une demande de liaison expirée (10 minutes) ou déjà utilisée renvoie 410 transaction_expired. Une demande de liaison est utilisée une seule fois, quel que soit le résultat. Pour refuser, appelez POST /fapi/v1/transactions/current:cancel.

Politique de l'organisation

Lorsque la demande d'autorisation est liée à une organisation, la politique de connexion de l'organisation est vérifiée à nouveau après le premier facteur et juste avant l'ouverture de la session :

• L'adresse IP du client ne figure pas dans la liste d'autorisation de l'organisation : 403 ip_not_allowed.
• Les facteurs de la transaction ne respectent pas la politique de l'organisation (une méthode que l'organisation n'autorise pas, un facteur manquant, ou une clé de sécurité ou une clé d'accès hors de la liste d'AAGUID autorisés par l'organisation) : 403 no_allowed_method.
• La politique de l'organisation ne peut pas être lue : 503 temporarily_unavailable. La connexion échoue en mode sécurisé et ne continue jamais sans la politique.

Aucune session n'est ouverte. Un refus lors de la finalisation de la transaction supprime le cookie de transaction ; un 503 après le premier facteur laisse la transaction en place, et l'étape peut être relancée. Le corps d'erreur ne nomme jamais l'organisation, l'utilisateur ni l'adresse IP.

Transactions sans interface liées à DPoP

Pour une transaction démarrée avec un en-tête DPoP, envoyez une nouvelle preuve avec la même clé (htm POST, htu l'URL de l'étape) au lieu de Idp-Csrf-Token ; aucun cookie n'est utilisé. L'étape qui termine la transaction renvoie authorization_response une seule fois :

{
  "state": "completed",
  "authorization_response": { "code": "<code>", "state": "<your state>", "iss": "https://example.keenauth.app" },
  "next_steps": [],
  "schema_version": 1,
  "expires_at": "2026-11-02T10:15:00Z"
}

Vérifiez que state et iss correspondent, puis échangez le code à /oauth2/token avec votre code_verifier et une preuve DPoP issue de la même clé. Une preuve issue d'une autre clé renvoie invalid_grant. Si la demande d'autorisation ne peut pas aboutir à un code (consentement, conditions légales, choix d'organisation ou nouvelle connexion nécessaires, ou accès refusé), l'étape renvoie 403 authorization_failed et le membre error contient le code d'erreur OAuth ; aucun code n'est émis.

Erreurs

Exemple

curl -X POST https://example.keenauth.app/fapi/v1/transactions/current/steps/identifier \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Idp-Csrf-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier":"jane@example.com"}'

Données personnelles

Ce point de terminaison traite des données personnelles : profil de l'utilisateur final et identifiants. Données personnelles dans les API KeenAuth décrit ce qui est stocké, la durée de conservation et la suppression. Ne transmettez aucune catégorie particulière de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.