Configurer la diffusion des attributs utilisateur pour un IdP

1. Principe

Le contrôle de la diffusion des attributs utilisateurs au sein des fédérations se fait au niveau de chaque IdP. L'administrateur de celui-ci doit en effet définir la doctrine de diffusion des attributs utilisateurs aux différents services. L'exercice est délicat, puisqu'il faut en effet trouver un équilibre entre le minimum requis pour le fonctionnement des services, et la protection des données à caractère personnel, imposée par la réglementation (voire à ce sujet nos bonnes pratiques pour le traitement des données à caractère personnel dans la Fédération Éducation-Recherche).

Un service ne recevant pas les attributs obligatoires ou nécessaires à son fonctionnement devient alors inaccessible pour vos utilisateurs. C'est pourquoi la gestion d'un fournisseur d'identité s'accompagne d'une bonne gestion de la diffusion de ces attributs, adaptée aux demandes des services consommateurs d'attributs.

Le mécanisme des filtres d'attributs (attribute filters) de l'IdP Shibboleth permet de configurer une ou plusieurs politiques techniques de filtrage des attributs, en fonction d'un certain nombre de critères. Par exemple, ne fournir aucun attribut à un SP 'A', des attributs non nominatifs à un autre et un ensemble d'attributs plus riche à un troisième. L'ensemble de ces politiques doit permettre de couvrir la doctrine de diffusion des attributs.

Néanmoins, vu le nombre de SPs présents dans la Fédération Éducation-Recherche et dans eduGAIN, et le fait qu'il s'en ajoute de nouveaux régulièrement, il est aujourd'hui impossible de maintenir manuellement l'ensemble des politiques techniques spécifiques à chacun d'entre eux, et il est nécessaire d'automatiser la procédure. C'est d'ailleurs une des obligations du cadre technique de la Fédération Éducation-Recherche, pour l'instant limitée aux seuls services nationaux, mais qu'il est préférable d'appliquer à l'ensemble des différentes catégories.

Cette fiche technique fournit plusieurs approches pour mettre en place l'automatisation de la doctrine de diffusion des attributs.
Il ne s'agit pas d'exemples prêts à l'emploi. Notamment, la liste des attributs est volontairement tronquée pour ne pas alourdir les exemples.

2. Automatisation

L'automatisation se base sur l'utilisation des métadonnées, et permet la configuration la plus efficace.

A partir de sa version 2.4.0 (Avril 2013), l'IdP Shibboleth permet de définir des règles génériques de diffusion d'attributs, en fonction des attributs utilisateurs demandés par un fournisseur de service. Ces informations sont directement issues du guichet de la fédération où l'administrateur d'un fournisseur de service renseigne la liste des attributs utilisateurs dont son service a besoin pour fonctionner.

Voici un extrait des métadonnées de la fédération, incluant la description XML des attributs attendus par un fournisseur de service :

<AttributeConsumingService index="0">
  <ServiceName xml:lang="fr">CFAU - Cahier de Liaison Electronique</ServiceName>
  <!-- Attribut mail obligatoire (isRequired="true")-->
  <RequestedAttribute
    NameFormat="urn:oasis:names:tc:2.0:attrname-format:uri"
    isRequired="true"
    Name="urn:oid:0.9.2342.19200300.100.1.3"
    FriendlyName="mail">
  </RequestedAttribute>
 
  <!-- Attribut eduPersonPrincipalName non obligatoire -->
  <RequestedAttribute
    NameFormat="urn:oasis:names:tc:2.0:attrname-format:uri"
    Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
    FriendlyName="eduPersonPrincipalName">
  </RequestedAttribute>
</AttributeConsumingService>

Ces informations publiées dans les métadonnées SAML sont exploitables pour configurer la diffusion automatique de certains attributs par votre IdP Shibboleth, en fonction des attributs demandés par les fournisseurs de service.

2.1 Scénarios proposés par ce guide

La doctrine de diffusion de votre IdP est composée de 1 ou plusieurs politiques techniques.
Dans la suite, nous détaillons les politiques techniques pouvant être mises en place dans votre IdP.

Le tableau suivant liste quelques unes des politiques techniques de diffusion posssibles. Nous détaillerons la #1, #2 et #3 dans la suite de cet article.
D'autres politiques sont bien évidemment possibles.

# Politique Description Avantages Inconvénients Remarques
1 Automatisation complète Les attributs demandés dans les métadonnées sont fournis Mise à jour automatique en fonction des métadonnées
Pas de modification si ajout d'une nouvelle fédération
Pas de contrôle fin sur les attributs renvoyés
2 Automatisation par fédération Les attributs demandés dans les métadonnées sont fournis
Les attributs associés à un cadre de conformité sont renvoyés (cf R&S)
Mise à jour automatique en fonction des métadonnées
Possibilité de limiter les attributs diffusable pour chaque fédération
Mise à jour du paramétrage nécessaire lors de l'ajout d'une fédération
3 R&S Les attributs associés au cadre de conformité R&S sont renvoyés : cf Spécification Research and Scholarship (R&S) Nécessaire pour afficher une conformité de votre IdP
4 ERASMUS Gère la diffusion de l'identifiant étudiant européen (ESI) : cf Transmission de l'ESI
5 TCS Gère la diffusion des attributs requis par Sectigo : cf exemple_de_fichier_attribute-filterxml
6 Paramétrage manuel par SP Une politique doit spécifiquement être mise en place pour chaque SP Contrôle très fin des attributs diffusés Pas de mise à jour automatique (si un SP a besoin d'un nouvel attribut - ou n'a plus besoin d'un attribut, la configuration devient caduque)
Difficilement maintenable
Ce type de configuration est très fortement déconseillé
7 Diffusion systématique d'un ensemble d'attributs à tous les SP L'IdP est configuré pour fournir systématiquement une liste d'attributs - quelque soit le SP Configuration extrêmement simple Ne respecte pas les données à caractère personnel Ce type de configuration est très fortement déconseillé
Dans le cadre de l'utilisation de la Fédération Éducation-Recherche, l'utilisation de la politique #1 ou #2 est obligatoire pour les SP français.

Notre recommandation en tant qu'opérateur de fédération est d'utiliser les politiques techniques suivantes :

  • #1 ou #2
  • + #3
  • + #4 si vous avez des étudiants concernés par la mobilité erasmus
  • + #5 si vous utilisez TCS et vous voulez vous authentifier chez Sectigo avec votre IdP

2.2 Exemples de politiques

Dans les exemples suivants - sauf mention contraire - la liste des attributs est volontairement tronquée et limitée aux attributs suivants :
  • mail
  • displayName
  • eduPersonPrincipalName


Pour ajouter un attribut dans la liste, il est uniquement nécessaire de connaître son attributeID.
Il s'agit de la valeur de l'attribut XML id défini dans votre Attribute Resolver dans le fichier attribute-reolver.xml. Ces noms étant à usage interne de l'IdP, il vaut mieux construire cette liste à partir de ce qui est réellement configuré sur votre serveur.

Une politique de filtrage est définie par une balise AttributeFilterPolicy, avec un attribut id.
Dans le fichier attribute-filter.xml, toutes les politiques sont incluses dans une balise AttributeFilterPolicyGroup.
Dans les exemples, la balise AttributeFilterPolicyGroup est volontairement omise.

Dans une politique de filtrage, la valeur AttributeInMetadata d'une règle PermitValueRule permet d'autoriser la diffusion d'un attribut uniquement s'il est déclaré comme demandé par le SP dans les métadonnées de la fédération. L'option onlyIfRequired permet de restreindre encore plus ce critère, en exigeant que l'attribut soit indiqué comme obligatoire.

2.2.1 Politique technique #1 : Automatisation complète

IDP_ROOT_DIR/conf/attribute-filter.xml
<!-- Diffusion d'attributs à tous les SP connus -->
<AttributeFilterPolicy id="releaseToAllSPs">
 
  <!-- ce critère correspond à n'importe quelle entité -->
  <PolicyRequirementRule xsi:type="ANY"/>
 
  <!-- Vérifiez bien le nom des attributs dans votre resolver --> 
 
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <!-- Ajouter d'autres attributs en-dessous -->
 
</AttributeFilterPolicy>

2.2.2 Politique technique #2 : Automatisation par fédération

Par rapport à l'exemple précédent, ce type de politique vous permet d'avoir une liste d'attributs diffusable dans eduGAIN plus restreinte que dans la Fédération Education-Recherche.

<!-- Politique de diffusion pour la Fédération Education-Recherche -->
<AttributeFilterPolicy id="releaseToFERSps">
 
  <!-- Ce critère correspond à toute entité enregistrée dans la fédération d'identifiant
   "https://federation.renater.fr/", c'est-à-dire la Fédération Education/Recherche -->
  <PolicyRequirementRule xsi:type="InEntityGroup" groupID="https://federation.renater.fr/" />
 
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <!-- Ajouter d'autres attributs en-dessous -->
</AttributeFilterPolicy>
 
<!-- Politique de diffusion pour eduGAIN -->
<AttributeFilterPolicy id="releaseToEdugainSps">
 
  <!-- Ce critère correspond à toute entité enregistrée dans la fédération d'identifiant 
  "https://federation.renater.fr/edugain", c'est-à-dire eduGAIN -->
  <PolicyRequirementRule xsi:type="InEntityGroup" groupID="https://federation.renater.fr/edugain/" />
 
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
  </AttributeRule>
 
  <!-- Ajouter d'autres attributs en-dessous -->
</AttributeFilterPolicy>
 
  <!-- Ajouter d'autres fédérations selons vos besoins -->

2.2.3 Politique technique #3 : Diffusion de attributs R&S

Le cadre de conformité R&S n'impose pas que tous les attributs soient transmis, mais dans la mise en oeuvre d'une politique de filtrage simple et lisible, notre recommandation est des transmettre systématiquement les attributs à tous les SP conformes.
Les attributs concernés sont :

  • eduPersonPrincipalName
  • eduPersonTargetedID
  • mail
  • displayName
  • givenName
  • surName
  • eduPersonScopedAffiliation
<!-- Diffusion des attributs du cadre R&S (cf https://services.renater.fr/federation/documentation/engagement-conformite/researchandscholarship) -->
<AttributeFilterPolicy id="releaseResearchAndScholarship">
 
  <!-- ce critère correspond à tout SP conforme à la spécification R&S -->
  <PolicyRequirementRule xsi:type="EntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://refeds.org/category/research-and-scholarship"/>
 
  <!-- diffusion de l'ePPN obligatoire -->
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- diffusion de l'eduPersonTargetedID optionnelle -->
  <AttributeRule attributeID="eduPersonTargetedID">
    <PermitValueRule xsi:type="ANY"/> 
  </AttributeRule>
 
  <!-- diffusion du mail obligatoire -->
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- soit displayName OU (givenName + sn) est obligatoire mais les 3 sont recommandés -->
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <AttributeRule attributeID="surName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- diffusion de l'eduPersonScopedAffiliation optionnelle -->
  <AttributeRule attributeID="eduPersonScopedAffiliation">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
</AttributeFilterPolicy>

3. Mise en place d'exceptions

Quelle que soit la méthode utilisée, il est possible de surcharger la configuration pour un SP spécifique par des règles de diffusion (ou non diffusion) d'attributs. En effet, un attribut n'est transmis par un IdP que si une règle Permit le prévoit et si aucune règle Deny n'empêche sa diffusion. Les règles Deny ont donc préséance sur les règles Permit.

3.1 Diffusion d'un attribut non spécifié dans les métadonnées

Il se peut qu'un SP ait besoin d'un attribut non défini dans les métadonnées. Quelques exemples :

  • Le SP n'exprime pas les attributs requis (possible dans eduGAIN) ;
  • L'attribut demandé n'est pas défini sur le guichet de la fédération (attribut trop spécifique - uniquement utilisé dans une fédération locale) ;
  • Le SP a besoin d'un identifiant à choisir parmi {eduPersonPrincipalName, eduPersonTargetedID, eduPersonUniqueId}. Le SP peut déclarer ces 3 attributs dans les métadonnées, mais n'en marquer aucun comme obligatoire. Il revient alors à l'administrateur de l'IdP d'ajouter une exception pour transmettre le bon attribut (possible dans eduGAIN).
<!-- Exemple : diffusion de l'ePPN à un service en particulier -->
<AttributeFilterPolicy id="releaseEPPNToSPFooBar">
 
  <PolicyRequirementRule
    xsi:type="Requester"
    value="https://foo.bar.com/sp"/>
 
    <AttributeRule attributeID="eduPersonPrincipalName">
      <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
 
</AttributeFilterPolicy>

3.2 Refus de diffusion d'un attribut

A contrario, il est tout à fait possible de limiter la diffusion d'attributs à un SP trop “gourmand” :

<!-- Exemple : refus de diffusion de l'email à un service en particulier -->
<AttributeFilterPolicy id="DenyMailForSp">
 
  <PolicyRequirementRule
    xsi:type="Requester"
    value="https://jenevous.faispasconfiance/"/>
 
  <AttributeRule attributeID="mail">
    <DenyValueRule xsi:type="ANY"/>
  </AttributeRule>
 
</AttributeFilterPolicy>

4. Renvoyer les attributs subject-id et pairwise-id

Si vous avez besoin de renvoyer les attributs subject-id et pairwise-id décrits dans SAML V2.0 Subject Identifier Attributes, il faut adapter les règles de filtrage de ce 2 attributs, car la demande de présence de ces attributs se fait via un Entity-Category (comme R&S).

Voici comment mettre à jour vos politiques de filtrage :

  <AttributeFilterPolicy id="releasePairwiseID">
    <PolicyRequirementRule xsi:type="OR">
      <Rule xsi:type="EntityAttributeRegexMatch" attributeName="urn:oasis:names:tc:SAML:profiles:subject-id:req" attributeValueRegex="pairwise-id|any"/>
      <!-- Vous pouvez positionner le SP de test pour des besoins de test de votre IdP -->
      <Rule xsi:type="Requester" value="https://test-sp.federation.renater.fr"/>
    </PolicyRequirementRule>
    <!-- Vérifiez bien le nom de l'attribut dans votre resolver -->
    <AttributeRule attributeID="samlPairwiseID">
      <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
  </AttributeFilterPolicy>
 
  <AttributeFilterPolicy id="releaseSubjectID">
    <PolicyRequirementRule xsi:type="OR">
      <Rule xsi:type="EntityAttributeRegexMatch" attributeName="urn:oasis:names:tc:SAML:profiles:subject-id:req" attributeValueRegex="subject-id"/>
      <!-- Vous pouvez positionner le SP de test pour des besoins de test de votre IdP -->
      <Rule xsi:type="Requester" value="https://test-sp.federation.renater.fr"/>
    </PolicyRequirementRule>
    <!-- Vérifiez bien le nom de l'attribut dans votre resolver -->
    <AttributeRule attributeID="samlSubjectID">
      <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
  </AttributeFilterPolicy>

5. Paramétrage de la diffusion des attributs pour un service non fédéré

Un IdP peut tout à fait être utilisé pour accéder à des services non fédérés. Par exemple, un établissement peut mettre en place un service utilisant SAML pour déléguer l'authentification.

Ce SP va lui aussi requérir un certain nombre d'attributs, que l'IdP doit fournir. Or, les métadonnées du SP n'intègre pas toujours la description des attributs requis. Le plus simple dans ce cas consiste à ajouter une politique spécifique pour ce SP :

<!-- Diffusion des attributs mail, givenName et surName au SP https://foo.univ-xyz.fr/sp -->
<AttributeFilterPolicy id="releaseToLocalSPFoo">
  <PolicyRequirementRule xsi:type="Requester" value="https://foo.univ-xyz.fr/sp"/>
  <AttributeRule attributeID="mail">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
</AttributeFilterPolicy>

6. Validation et débogage

Pour valider la bonne transmission de ces attributs utilisateurs, il est possible d'utiliser le fournisseur de service de test et validation RENATER qui affiche tous les attributs reçus.

Par ailleurs, l'outil en ligne de commande aacli permet de simuler une connexion à n'importe quel fournisseur de service et d'obtenir la réponse de l'IdP à celui-ci. Plus d'informations dans le support de formation.

7. Plus d'information