Configurer votre fournisseur d'identités pour l'accès aux services Erasmus via eduGAIN

1. Contexte et Introduction

Dans le cadre de la digitalisation du programme Erasmus, il est prévu d'intégrer progressivement les services de mobilité (OLA, application mobile Erasmus+, etc.) dans la fédération eduGAIN afin de permettre : (a) aux étudiants de s'authentifier avec le compte de leur établissement d'origine ; (b) aux services de recevoir les informations nécessaires sur les étudiants en mobilité (ESI, infos de contact, établissement de rattachement, etc.).

Comme illustré par le schéma ci-dessous, les services Erasmus sont aujourd'hui rendu disponibles dans eduGAIN via un composant de type Proxy, point d'accès unique qui permet une mise en relation facilitée avec les fournisseurs d'identités (IdPs) des établissements enregistrés dans cette même fédération.
Ce composant présente également l'avantage pour les services d'éviter de s'enregistrer individuellement dans eduGAIN (seul le proxy y est enregistré en tant que service) et de pouvoir gérer plusieurs protocoles de fédération (i.e. un service de mobilité basé sur OpenIDConnect pourra ainsi utiliser eduGAIN basée sur SAML pour l'authentification des utilisateurs).

2. Objet du document

Ce document décrit comment configurer un fournisseur d'identités (appelé plus succinctement IdP dans la suite de ce document) pour accéder aux services Erasmus via la fédération eduGAIN.
Il est destiné à l'administrateur technique d'un IdP dont l'établissement participe au programme de mobilité Erasmus.

3. Configurer eduGAIN pour votre IdP

Si l'IdP de votre établissement est déjà enregistré et opérationnel dans la fédération eduGAIN, vous pouvez passer directement au chapitre suivant

3.1 Jeu d'attributs recommandé dans eduGAIN

Un IdP utilisant eduGAIN doit pouvoir transmettre le jeu d'attributs suivant :

Attribut Description succincte
eduPersonTargetedID Identifiant de personne unique, opaque, ciblé et non-réattribuable
Exemple: https://idp.univ-exemple.fr!https://service.univ-exemple.fr!jx1SM1we3Bn8Yg0XQ=
eduPersonPrincipalName Identifiant de personne globalement unique
Exemple: jdupont@univ-exemple.fr
displayName Nom complet d'affichage (peut contenir des accents)
Exemple: Jean Dupont
commonName (cn) Nom complet sans accent d'une personne (nom suivi du prénom)
Exemple : Dupont Jean
mail Adresse de courrier électronique institutionnelle
Exemple: jean.dupont@univ-exemple.fr
eduPersonAffiliation Statut de la personne vis-à-vis de l'établissement (peut être multi-valuée)
Exemples : student ou student;member
eduPersonScopedAffiliation <edupersonaffiliation>@<domaine DNS établissement> (peut être multi-valuée)
Exemple : student@univ-exemple.fr ou student@univ-exemple.fr;member@univ-exemple.fr
schacHomeOrganization Nom de domaine DNS de l'établissement
Exemple: univ-exemple.fr
schacHomeOrganizationtype Type d'établissement (voir les valeurs possibles ici)
Exemple : urn:schac:homeOrganizationType:int:university

3.2 Configuration de l'IdP

Les exemples de configuration donnés ci-dessous s'appliquent uniquement à un IdP Shibboleth en version 3.x. et supérieure.

Il s'agit ici d'appliquer les modifications de configuration suivantes sur votre IdP:

  1. Configurer le chargement des méta-données eduGAIN ;
  2. Configurer la transmission du jeu d'attributs recommandé dans eduGAIN.

3.2.1 Configurer le chargement des métadonnées eduGAIN

Dans le fichier metadata-providers.xml, ajouter à la configuration existante la directive permettant de charger le fichier de métadonnées eduGAIN main-sps-edugain-metadata.xml, comme illustré dans l'exemple ci-dessous :

Fichier /opt/shibboleth-idp/conf/metadata-providers.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/metadata-providers.xml (cliquez pour déplier)

<!-- Chargement des métadonnées de la Fédération Education-Recherche -->
<MetadataProvider id="RenaterProdMetadata"
                  xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/main-sps-renater-metadata.xml"
                  metadataURL="https://metadata.federation.renater.fr/renater/main/main-sps-renater-metadata.xml"> 
 
    <MetadataFilter xsi:type="SignatureValidation"
        requireSignedMetadata="true"
        certificateFile="%{idp.home}/credentials/renater-metadata-signing-cert-2016.pem">
    </MetadataFilter>
    <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
    </MetadataFilter>    
</MetadataProvider>
 
<!-- Chargement des métadonnées eduGAIN -->
<MetadataProvider id="RenaterEdugainMetadata"
                  xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/main-sps-edugain-metadata.xml"
                  metadataURL="https://metadata.federation.renater.fr/edugain/main/main-sps-edugain-metadata.xml"> 
 
    <MetadataFilter xsi:type="SignatureValidation"
        requireSignedMetadata="true"
        certificateFile="%{idp.home}/credentials/renater-metadata-signing-cert-2016.pem">
    </MetadataFilter>
    <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
    </MetadataFilter>
</MetadataProvider>


3.2.2 Configurer la transmission du jeu d'attributs recommandé dans eduGAIN

Adaptation du fichier attribute-resolver:
Le fichier attribute-resolver.xml définit tous les attributs diffusables par votre IdP et pour chacun la source de données associée.
Pour eduGAIN, vous devez enrichir ce fichier pour prendre en compte les attributs schacHomeOrganization et schacHomeOrganizationType non prévus par défaut. Dans la plupart des cas les valeurs de ces deux attributs seront constantes pour tous vos utilisateurs ; vous pouvez donc les définir au moyen d'un DataConnector de type Static comme illustré dans l'exemple ci-dessous :

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

<!-- ========================================== -->
<!--      Attribute Definitions                 -->
<!-- ========================================== -->
 
<!-- Définition attribut schacHomeOrganization -->
<AttributeDefinition id="schacHomeOrganization" xsi:type="Simple">
    <InputDataConnector ref="staticAttributes" attributeNames="schacHomeOrganization"/>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:schacHomeOrganization" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.9" friendlyName="schacHomeOrganization" encodeType="false" />
</AttributeDefinition>	
 
<!-- Définition attribut schacHomeOrganizationType -->
<AttributeDefinition id="schacHomeOrganizationType" xsi:type="Simple">
    <InputDataConnector ref="staticAttributes" attributeNames="schacHomeOrganizationType"/>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:schacHomeOrganizationType" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.10" friendlyName="schacHomeOrganizationType" encodeType="false" />
</AttributeDefinition>	
 
<!-- ========================================== -->
<!--      Data Connectors                       -->
<!-- ========================================== -->
 
<!-- Connecteur de données statique  -->
<DataConnector id="staticAttributes" xsi:type="Static">
    <Attribute id="schacHomeOrganization">
        <Value>univ-exemple.fr</Value>
    </Attribute>
    <Attribute id="schacHomeOrganizationType">
        <Value>urn:schac:homeOrganizationType:int:university</Value>
    </Attribute>
</DataConnector>


Adaptation du fichier attribute-filter:
Pour que votre IdP soit capable de transmettre le jeu d'attributs recommandé, éditez le fichier attribute-filter.xml et ajoutez une nouvelle politique de filtrage AttributeFilterPolicy en vous basant sur l'un des deux fichiers exemple ci-dessous (selon que vous souhaitiez transmettre ce jeu d'attributs à l'ensemble des services enregistrés dans eduGAIN ou à un service en particulier).

Exemple 1 : diffusion du jeu d'attributs recommandé à l'ensemble des services enregistrés dans eduGAIN

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

 <!-- Transmission du jeu d'attributs recommandé à l'ensemble des services enregistrés dans eduGAIN -->
<AttributeFilterPolicy id="releaseToAnyEduGainSPs">
 
    <PolicyRequirementRule xsi:type="InEntityGroup" groupID="https://federation.renater.fr/edugain/" />
 
    <AttributeRule attributeID="eduPersonTargetedID">
        <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonPrincipalName">
        <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="displayName">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="commonName">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="mail">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonAffiliation">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonScopedAffiliation">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="schacHomeOrganization">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="schacHomeOrganizationType">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
</AttributeFilterPolicy>


Exemple 2 : diffusion du jeu d'attributs recommandé à un service donné enregistré dans eduGAIN

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

<!-- Transmission du jeu d'attributs recommandé au service "https://sp.example.org" -->
<AttributeFilterPolicy id="releaseToSelectedEduGainSp">
 
    <PolicyRequirementRule xsi:type="Requester" value="https://sp.example.org" />
 
    <AttributeRule attributeID="eduPersonTargetedID">
        <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonPrincipalName">
        <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="displayName">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="commonName">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="mail">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonAffiliation">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="eduPersonScopedAffiliation">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="schacHomeOrganization">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
    <AttributeRule attributeID="schacHomeOrganizationType">
         <PermitValueRule xsi:type="AttributeInMetadata" onlyIfRequired="true"/>
    </AttributeRule>
 
</AttributeFilterPolicy>


Test de votre configuration :
Pour valider votre nouvelle configuration et vérifier que votre IdP transmet bien le jeu d'attributs requis au SP correspondant au proxy erasmus (identifié par l'entityID https://proxy.prod.erasmus.eduteams.org/metadata/backend.xml), vous pouvez utiliser l'outil en ligne de commande aacli. Cet outil 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 sur l'utilisation de l'outil ici.

3.3 Enregistrement de l'IdP dans la fédération eduGAIN

Une fois la configuration technique de votre IdP effectuée, vous devez l'enregistrer dans la fédération eduGAIN via le guichet de la fédération.
Le mode opératoire pour effectuer cet enregistrement depuis le guichet est décrit plus en détail sur cette page.

3.4 Validation du fonctionnement dans eduGAIN

En dernière étape, une fois l'enregistrement de votre IdP pris en compte dans les métadonnées de la fédération eduGAIN, vous pourrez valider son fonctionnement à l'aide du service eduGAIN Attribute Release Check.
Ce service vous indiquera par ailleurs si les attributs transmis par votre IdP ont le bon format.

4. Configurer la transmission des données demandées par les services Erasmus

4.1 Données requises par les services Erasmus

Les données requises par les services Erasmus et qui doivent être transmises par votre IdP incluent :

  • Le jeu d'attributs recommandé dans eduGAIN (cf. § 3.1 ci-dessus) ;
  • L'identifiant étudiant européen appelé ESI.

La spécification de l'ESI prévoit qu'il soit transporté dans la fédération via l'attribut schacPersonalUniqueCode et dans le cas des établissements français, qu'il soit construit à partir de l'INE (Identifiant National étudiant), selon la forme suivante :

schacPersonalUniqueCode: urn:schac:personalUniqueCode:int:esi:fr:[INE]

Un exemple de valeur d'ESI pour un étudiant enregistré dans un établissement français sous l'INE 1234567890G serait ainsi :

4.2 Stratégie de génération de l'ESI par la brique IdP

L'ESI est construit à partir de l'INE, matérialisé dans la norme supAnn par l'attribut supannCodeINE.
Au niveau du SI de l'établissement, cet attribut supannCodeINE devrait logiquement être présent pour tout étudiant enregistré dans le SI Scolarité de l'établissement.

Afin que votre IdP puisse générer un ESI, 2 stratégies sont possibles en fonction de l'attribut source provisionné dans le référentiel utilisateurs couplé à l'IdP :

  • Stratégie 1 : l'ESI, au travers de l'attribut schacPersonalUniqueCode est stocké dans sa forme complète dans le référentiel utilisateurs de l'IdP (ex: urn:schac:personalUniqueCode:int:esi:fr:1234567890G). Dans ce cas, l'IdP prendra cet attribut source tel quel, sans transformation avant transmission ;
  • Stratégie 2 : seul l'attribut supannCodeINE est stocké dans le référentiel utilisateurs de l'IdP. Dans ce cas, la partie gauche de l'ESI relative à l'espace de nommage (urn:schac:personalUniqueCode:int:esi:fr) est définie statiquement au niveau de l'IdP. L'IdP sélectionnera alors l'attribut source supannCodeINE dans le référentiel utilisateurs et construira dynamiquement - par concaténation - l'ESI à renvoyer au bon format.

RENATER recommande l'utilisation de la stratégie 2. Des exemples sont toutefois fournis pour les 2 cas de figure dans le chapitre suivant (cf. §4.3.1).

4.3 Configuration de l'IdP

4.3.1 Définition de l'ESI

Stratégie 1: l'ESI (attribut schacPersonalUniqueCode) est stocké dans sa forme complète dans le référentiel utilisateurs de l'IdP

Dans le fichier attribute-resolver.xml, ajoutez une définition de l'attribut schacPersonalUniqueCode de type Simple, comme illustré dans l'exemple ci-dessous :

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

<AttributeDefinition id="schacPersonalUniqueCode" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="schacPersonalUniqueCode" />
	<AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:schacPersonalUniqueCode" encodeType="false"/>
	<AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.14" friendlyName="schacPersonalUniqueCode" encodeType="false"/>
</AttributeDefinition>


Stratégie 2: seul l'attribut supannCodeINE est stocké dans le référentiel utilisateurs de l'IdP

Dans le fichier attribute-resolver.xml, ajoutez une définition de l'attribut schacPersonalUniqueCode de type Template, utilisant l'attribut supannCodeINE présent dans le référentiel utilisateurs de l'IdP, comme illustré dans l'exemple ci-dessous :

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-resolver.xml (cliquez pour déplier)

<!-- Définition de l'ESI (attribut schacPersonalUniqueCode) -->
<AttributeDefinition id="schacPersonalUniqueCode" xsi:type="Template">
    <InputDataConnector ref="myLDAP" attributeNames="supannCodeINE" />
    <DisplayName xml:lang="fr">Identifiant Etudiant Européen (ESI)</DisplayName>
    <DisplayName xml:lang="en">European Student Identifier (ESI)</DisplayName>
    <Template>urn:schac:personalUniqueCode:int:esi:fr:${supannCodeINE}</Template>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:schacPersonalUniqueCode" encodeType="false"/>
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.14" friendlyName="schacPersonalUniqueCode" encodeType="false" />
</AttributeDefinition>


4.3.2 Transmission de l'ESI

Dans le fichier attribute-filter.xml, il s'agit ici de définir une nouvelle politique de filtrage afin que votre IdP :

  • #1. Prenne en compte uniquement les valeurs de l'attribut schacPersonalUniqueCode correspondant à l'ESI ;
  • #2. Transmette l'ESI uniquement au fournisseur de service légitime, à savoir le proxy d'authentification Erasmus (décrit au §1), identifié par l'entityID https://proxy.prod.erasmus.eduteams.org/metadata/backend.xml (N.B. : dans une optique de validation de votre configuration, il peut également être utile d'ajouter le fournisseur de services de test Renater) ;
  • #3. Transmette l'ESI uniquement pour les utilisateurs ayant un profil étudiant.

En tenant compte de ces conditions, la politique de filtrage pour transmission de l'ESI devrait ressembler à l'exemple ci-dessous :

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

Fichier /opt/shibboleth-idp/conf/attribute-filter.xml (cliquez pour déplier)

<AttributeFilterPolicy id="ReleaseESItoSelectedServices">
    <PolicyRequirementRule xsi:type="AND">
        <Rule xsi:type="OR">
            <Rule xsi:type="Requester" value="https://test-sp.federation.renater.fr" />
            <Rule xsi:type="Requester" value="https://proxy.prod.erasmus.eduteams.org/metadata/backend.xml" />
        </Rule>
        <Rule xsi:type="Value" attributeID="eduPersonAffiliation" value="student" />
    </PolicyRequirementRule>
    <AttributeRule attributeID="schacPersonalUniqueCode">
        <PermitValueRule xsi:type="ValueRegex" regex="^urn:schac:personalUniqueCode:int:esi:.*$" />
    </AttributeRule>
</AttributeFilterPolicy>


4.4 Validation de la bonne transmission de l'ESI par votre IdP

Pour vérifier que votre IdP est bien capable de fournir l'ESI, vous pouvez commencer par utiliser l'outil en ligne de commande aacli comme précédemment et simuler une connexion au SP de test RENATER (si déclaré précédemment, cf. § 4.3.2) et/ou au proxy Erasmus.
Plus d'informations sur l'utilisation de l'outil ici

Outre la ligne de commande, vous pouvez également accéder au service de test en ligne RENATER (en sélectionnant Connexion avec la fédération Education-Recherche) et vous assurer que l'ESI est bien présent dans la liste des attributs retournés :