Courtiers d’identité (Identity Brokering)¶

Pourquoi utiliser un courtier ?¶

Le courtage d’identité permet à Keycloak de déléguer l’authentification à un fournisseur d’identité externe (IdP) tout en présentant Keycloak comme point d’entrée commun aux applications. L’IdP externe peut parler OIDC ou SAML. L’application finale n’a ainsi pas besoin d’intégrer séparément chaque fournisseur.

Keycloak reçoit l’identité externe, applique les règles de liaison de compte, peut importer certains attributs et émet ensuite ses propres jetons ou assertions pour le client. Les identités externes ne doivent pas être automatiquement assimilées à un compte local de même email sans politique sûre.

Flux de courtage OIDC / SAML¶

L’utilisateur sélectionne un fournisseur (ou la politique déclenche une redirection).
Keycloak prépare une requête vers l’IdP externe : autorisation OIDC ou AuthnRequest SAML.
L’utilisateur s’authentifie auprès de l’IdP externe.
L’IdP retourne un code OIDC ou une réponse SAML à Keycloak.
Keycloak vérifie le résultat, applique les identity provider mappers, puis cherche une identité déjà liée.
Au premier accès, le flux First Broker Login gère la création, la liaison ou le refus d’un compte selon la configuration.
Keycloak ouvre sa session et retourne une réponse OIDC/SAML au client d’origine.

sequenceDiagram
    actor U as Utilisateur
    participant A as Application
    participant K as Keycloak (broker)
    participant E as IdP externe (OIDC / SAML)
    U->>A: Se connecte
    A-->>U: Redirection vers Keycloak
    U->>K: Demande d'authentification
    K-->>U: Redirection vers l'IdP externe
    U->>E: Authentification externe
    E-->>U: Retour OIDC code ou SAML Response
    U->>K: Callback externe
    K->>K: Valide réponse et applique mappers
    K->>K: Recherche une identité externe déjà liée
    alt Première connexion
        K->>U: Exécute First Broker Login (lien/création/vérification)
        U->>K: Confirme l'action demandée
    else Identité déjà liée
        K->>K: Retrouve l'utilisateur local lié
    end
    K-->>U: Retour OIDC / SAML vers l'application
    U->>A: Reprend la session applicative

Le flux First Broker Login est utilisé lorsqu’une identité externe arrive pour la première fois. Selon les étapes activées, Keycloak peut créer un nouvel utilisateur, demander des informations obligatoires, ou rechercher un compte existant et demander une vérification avant liaison. Une correspondance par email seule peut ouvrir une voie de prise de contrôle si l’email n’est pas vérifié ou si l’IdP n’est pas assez fiable. Définissez une règle explicite : comptes pré-provisionnés, domaine d’email approuvé et vérifié, consentement et/ou étape de réauthentification.

Les identity provider mappers transforment les claims externes en attributs ou rôles locaux. N’importez que les données requises, vérifiez les collisions de noms et contrôlez si les modifications peuvent être renvoyées vers l’IdP. Lier une identité externe à un utilisateur local est une décision d’identité et doit être auditée.

Configuration et diagnostic¶

Dans le realm, configurer un fournisseur OIDC ou SAML avec son alias, son issuer/metadata, ses endpoints, ses paramètres de client et les URL de redirection/callback attendues. Valider les certificats, signatures, issuer, audience, redirect URI et horloges. Utiliser des secrets uniques et les conserver côté serveur. Tester le premier login, un login ultérieur, une identité déjà liée, une collision d’email et une erreur de callback. Consulter concepts Keycloak et flux d’authentification.

Courtiers d’identité (Identity Brokering)¶

Pourquoi utiliser un courtier ?¶

Flux de courtage OIDC / SAML¶

First Broker Login et mappers¶

Configuration et diagnostic¶