Concepts fondamentaux de Keycloak¶

Pourquoi comprendre le modèle ?¶

Keycloak organise l’identité par realm. Un realm regroupe des utilisateurs, des clients et des politiques isolés logiquement des autres realms. Il constitue souvent le périmètre d’une organisation ou d’un environnement. Les utilisateurs de master ne sont pas automatiquement ceux d’un realm applicatif.

Les objets principaux¶

• Realm : espace logique contenant configuration, utilisateurs, clients, sessions, fournisseurs, thèmes et politiques. Les URL d’authentification sont généralement propres à chaque realm.
• Client : application ou service qui utilise Keycloak. Un client OIDC peut être public ou confidentiel ; un client SAML représente typiquement un SP. Les URI de redirection et paramètres doivent être limités à des valeurs précises.
• Utilisateur : compte local avec identifiants, attributs, rôles, groupes et états de compte. Un utilisateur peut aussi être représenté par une fédération externe.
• Groupe : organise des utilisateurs et peut porter des rôles et attributs hérités par ses membres. La résolution exacte suit la configuration du realm.
• Rôle de realm : permission nommée au niveau du realm, par ex. support. Rôle de client : permission propre à une application, par ex. billing:read.
• Attribution de rôle : relie un rôle à un utilisateur ou à un groupe. L’existence d’un rôle ne l’attribue pas automatiquement.
• Client scope : ensemble réutilisable de scopes, protocol mappers et paramètres OIDC/SAML. Il peut être associé à un client par défaut ou à la demande, selon sa configuration.
• Protocol mapper : transforme des données de compte/attributions en claims OIDC ou attributs/assertions SAML. Il contrôle ce qui est émis et où cela apparaît.

classDiagram
    class Realm {
      +nom
      +parametres
      +fluxAuthentification
    }
    class User {
      +username
      +email
      +attributes
    }
    class Group {
      +nom
      +attributes
    }
    class Client {
      +clientId
      +protocol
      +redirectUris
    }
    class Role {
      +nom
      +type realm ou client
    }
    class ClientScope {
      +nom
      +scopes
    }
    class ProtocolMapper {
      +source
      +claim ou attribut cible
    }
    class IdentityProvider {
      +alias
      +OIDC ou SAML
    }
    class UserFederation {
      +LDAP ou AD
      +mode de stockage
    }
    Realm "1" o-- "0..*" User : contient
    Realm "1" o-- "0..*" Group : contient
    Realm "1" o-- "0..*" Client : contient
    Realm "1" o-- "0..*" Role : définit
    Realm "1" o-- "0..*" IdentityProvider : configure
    Realm "1" o-- "0..*" UserFederation : configure
    Group "0..*" -- "0..*" User : membres
    Group "0..*" -- "0..*" Role : peut attribuer
    User "0..*" -- "0..*" Role : reçoit
    Client "0..*" -- "0..*" Role : possède rôles client
    Client "0..*" -- "0..*" ClientScope : associe
    ClientScope "1" o-- "0..*" ProtocolMapper : contient

Rôles, scopes et contenu des jetons¶

Un rôle est une étiquette d’autorisation ; l’application doit décider quoi en faire. Les rôles peuvent apparaître dans un jeton sous les claims realm_access ou resource_access selon les paramètres OIDC et les mappers. Ne supposez pas qu’un rôle est inclus dans chaque jeton.

Les client scopes permettent de réutiliser une configuration de claims sur plusieurs clients. Les protocol mappers déterminent la source d’un claim et sa destination : ID token, access token, UserInfo ou assertion SAML. Examinez les jetons de test et minimisez les données personnelles exposées. Pour les flux OIDC et SAML, voir OIDC et SAML 2.0.

Sécurité opérationnelle¶

Enregistrez des redirect URI et des URL SAML précises (ACS, entity ID) ; évitez les jokers trop larges. Gardez les secrets côté serveur, utilisez des comptes administratifs séparés, accordez les privilèges minimaux, et contrôlez les durées de session et de jeton. Le démarrage en développement est détaillé dans le guide pratique. Les utilisateurs externes sont décrits dans LDAP / AD et le courtage d’identité.