Périmètre d'accès - Scope

Un scope (ou "périmètre d'accès") est un mécanisme permettant à une application cliente de demander l'accès à un ensemble spécifique d'informations sur l'utilisateur lors de l'authentification avec un fournisseur d'identité (comme Keycloak, OpenID Connect, OAuth2).

Un scope contrôle quelles données seront incluses dans le token ID et/ou token d'accès retourné par Keycloak.

Comment fonctionne un scope ?

Une application (client OpenID) d'Open ENT demande l'accès à certaines informations de l'utilisateur en précisant des scopes dans sa requête d’authentification.

Keycloak (serveur OpenID) valide la requête et renvoie un token contenant uniquement les informations correspondant aux scopes autorisés. L'application récupère les données et applique les restrictions d'accès.

Dans Open ENT, les scopes de client OpenID Connect doivent être adaptés aux besoins des applications clientes qui interagissent avec Keycloak. Voici une classification des différents scopes supportés en fonction des usages courants dans les différentes applications autour d'Open ENT (Moodle, Wordpress, ....) dans le contexte éducatif et administratif :

Les différents scopes d'Open ENT

1. Scopes Standard OpenID Connect (OIDC)

Ces scopes sont définis par la spécification OpenID Connect et sont inclus par défaut dans Keycloak.

Scope	Description
`openid`	Obligatoire pour toute requête d'authentification OIDC (permet d'obtenir l'identifiant unique `sub`).
`profile`	Donne accès aux informations générales de l'utilisateur (`name`, `family_name`, `given_name`, `preferred_username`, etc.).
`email`	Permet d’accéder à l'adresse e-mail (`email`, `email_verified`).
`address`	Accès aux informations d’adresse de l’utilisateur.
`phone`	Accès aux numéros de téléphone (`phone_number`, `phone_number_verified`).

2. Scopes personnalisés pour Open ENT

Ces scopes spécifiques sont définis pour exposer certaines données académiques et administratives.

Scope	Description
`roles`	Permet d'accéder aux rôles de l'utilisateur dans le système (`ADMIN_LOCAL`, `SUPER_ADMIN`, `CLASS_ADMIN`).
`profiles`	Permet d'accéder au profils de l'utilisateur (`teacher`, `personnel`, `relative`, `student`).
`structures`	Donne accès aux informations sur l’établissement de l’utilisateur (`uai`, `nom`, `code_académie`, `type_établissement`).
`groups`	Permet d’obtenir les groupes et classes auxquels appartient l’utilisateur.
`permissions`	Définit les permissions spécifiques de l’utilisateur selon son rôle et établissement.
`student_profile`	Contient des données sur les élèves (`classe`, `sections`, `options`, `scolarité`).
`teacher_profile`	Informations spécifiques aux enseignants (`matières enseignées`, `niveaux`).
`relative_info`	Permet d’obtenir les informations liées aux responsables légaux d’un élève.

3. Scopes techniques et de gestion

Ces scopes sont utiles pour des intégrations avancées ou des contrôles d’accès spécifiques.

Scope	Description
`offline_access`	Permet aux clients d’obtenir des refresh tokens longue durée.
`ent_admin`	Donne accès aux interfaces d’administration du portail ENT.
`audit_log`	Permet l’accès aux journaux d’audit et d’activité.
`api_access`	Donne accès aux API spécifiques du système Open ENT.
`custom_attributes`	Permet d’accéder aux attributs personnalisés définis pour l’utilisateur.

4. Scope généralement utilisé

Les scopes minimalistes par défaut sont généralement : openid, profile, email, roles

Clés utilisés dans les tokens

Dans Keycloak, les scopes sont associés à clés (claims), qui sont inclus dans le token JWT retourné aux clients.

Voici le mapping des scopes vers des claims spécifiques pour Open ENT.

1. Mapping des Scopes vers des Claims

Chaque scope est associé à un ensemble de claims qui seront présents dans le token.

Scope	Claims dans le token	Exemple de contenu
`openid`	`sub` (Identifiant unique de l'utilisateur)	`"sub": "abc123xyz"`
`profile`	`name`, `preferred_username`, `given_name`, `family_name`	`"name": "Jean Dupont"`
`email`	`email`, `email_verified`	`"email": "jean@exemple.com"`
`roles`	`realm_access.roles`, `resource_access.<client>.roles`	`"roles": ["ADMIN_LOCAL", "CLASS_ADMIN"]`
`profiles`	`realm_access.profiles`, `resource_access.<client>.profiles`	`"profiles": ["teacher", "personnel"]`
`structures`	`uai`, `nom`, `type`	`"etablissement": [{"uai": "0016643H", "nom": "Lycée Jean Moulin", "type": "Lycée"}]`
`groups`	`groups`	`"groups": ["/classe/3A", "/sport/football"]`
`permissions`	`permissions` (liste de droits spécifiques)	`"permissions": ["lecture_notes", "modification_cours"]`
`student_profile`	`classe`, `sections`, `scolarite`	`"classe": "3A", "sections": ["Théâtre", "Sport"]`
`teacher_profile`	`matières`, `niveaux`	`"matières": ["Maths", "Physique"], "niveaux": ["Première", "Terminale"]`
`guardian_info`	`responsables` (info sur les parents/tuteurs)	`"responsables": [{"nom": "Dupont", "lien": "père"}]`
`audit_log`	`last_login`, `ip_last_login`, `last_action`	`"last_login": "2024-03-15T12:00:00Z"`
`custom_attributes`	`custom` (attributs personnalisés définis dans Keycloak)	`"custom": {"theme": "dark", "notif": "true"}`

Dépendances entre les périmètres

Les périmètres d'accès peuvent être imbriqués entre eux. Voici les imbrications gérées :

✅ Imbrication des rôles sous structures Chaque établissement contient les rôles spécifiques de l'utilisateur pour cette structure.

Un SUPER_ADMIN est global. L'utilisateur est administrateur de toutes les informations dans OpenENT. Un ADMIN_LOCAL n'est pas global, il est rattaché à une structure. Un CLASS_ADMIN n'est pas global, il est rattaché à une classe.

Exemple :

Jean Dupont est professeur principal dans le lycéee Victor Hugo pour la classe 1A. Il enseigne les mathématiques en seconde et en première et la physique en première.

{
  "sub": "123456789",
  "name": "Jean Dupont",
  "structures": [
    {
      "uai": "0012345A",
      "nom": "Lycée Victor Hugo",
      "code_academie": "03",
      "type": "Lycée",
      "roles": ["CLASS_ADMIN"],
      "profiles": ["teacher"],
      "groups": ["Classe 1A", "Classe 1B"],
      "permissions": ["grade_assignments"],
      "teacher_profile": {
        "matières_enseignées": [
          {
            "matière": "Mathématiques",
            "niveaux": ["Seconde", "Première"],
            "classes": ["Classe 2A", "Classe 1B"]
          },
          {
            "matière": "Physique",
            "niveaux": ["Première"],
            "classes": ["1B"]
          }
        ],
        "main_teacher_classes": ["Classe 1A"]
      }
    },
    {
      "uai": "0098765B",
      "nom": "Collège Voltaire",
      "code_academie": "06",
      "type": "Collège",
      "roles": [],
      "profiles": ["teacher"],
      "groups": ["Classe 5C"],
      "teacher_profile": {
        "matières_enseignées": [
          {
            "matière": "Sciences",
            "niveaux": ["Cinquième"],
            "classes": ["Classe 5C"]
          }
        ]
      }
    }
  ]
}

Voici un exemple de personnel administratif travaillant dans un Centre d'Information et d'Orientation (CIO), ayant le rôle ADMIN_LOCAL dans un collège spécifique.

{
  "sub": "987654321",
  "name": "Marie Dubois",
  "structures": [
    {
      "uai": "0098765B",
      "nom": "Collège Voltaire",
      "code_academie": "06",
      "type": "Collège",
      "roles": ["ADMIN_LOCAL"],
      "profiles": ["administrative_staff"],
      "permissions": ["manage_students", "manage_teachers", "view_reports"]
    }
  ]
}

Comment fonctionne un scope ?​

Les différents scopes d'Open ENT​

1. Scopes Standard OpenID Connect (OIDC)​

2. Scopes personnalisés pour Open ENT​

3. Scopes techniques et de gestion​

4. Scope généralement utilisé​

Clés utilisés dans les tokens​

1. Mapping des Scopes vers des Claims​

Dépendances entre les périmètres​