Shibboleth

==== Configuration ====

=== Metadata de la fédération ===

La fédération fournis un fichier de metadata contenant l'ensemble des informations techniques des acteurs de la fédération d'identité. Ce fichier de metadata est téléchargé régulièrement par le service, validé à l'aide du certificat de signature de la fédération et chargé par le service.

Pour configurer les metadata de la fédération, il faut :

• éditer le fichier conf/relying-party.xml :
  • Mettre l'attribut includeAttributeStatement de <rp:ProfileConfiguration xsi:type="saml:ShibbolethSSOProfile" ~~> à true
  • Dé-commenter le bloque <metadata:MetadataProvider id="URLMD" ~~> et l'adapter comme suit :

            <metadata:MetadataProvider id="URLMD" xsi:type="metadata:FileBackedHTTPMetadataProvider"
                              metadataURL="https://metadata.federation.renater.fr/renater/main/main-all-renater-metadata.xml"
                              backingFile="/opt/shibboleth-idp245/metadata/main-all-renater-metadata.xml">
                <metadata:MetadataFilter xsi:type="metadata:ChainingFilter">
                    <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil" 
                                    maxValidityInterval="P0Y0M0DT0H0M0.000S" />
                    <metadata:MetadataFilter xsi:type="metadata:SignatureValidation"
                                    trustEngineRef="shibboleth.MetadataTrustEngine"
                                    requireSignedMetadata="true" />
                        <metadata:MetadataFilter xsi:type="metadata:EntityRoleWhiteList">
                        <metadata:RetainedRole>samlmd:SPSSODescriptor</metadata:RetainedRole>
                    </metadata:MetadataFilter>
                </metadata:MetadataFilter>
            </metadata:MetadataProvider>

    • Dans le bloque précédent, faite tout particulièrement attention :
      • à la valeur de l'attribut metadataURL qui correspond à l'URL de téléchargement du fichier des metadata de la fédération
      • à la valeur de l'attribut backingFile qui correspond au chemin local sur le serveur de stockage du fichier des metadata de la fédération
      • à la valeur de l'attribut maxValidityInterval qui correspond à la durée maximale de validité des metadata : dans le cadre de la fédération Renater, cet attribut doit valoir P0Y0M0DT0H0M0.000S (=n'expire jamais).
  • Dé-commenter le bloque <security:TrustEngine id="shibboleth.MetadataTrustEngine" ~~> et l'adapter comme suit :

        <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
            <security:Credential id="MyFederation1Credentials" xsi:type="security:X509Filesystem">
                <security:Certificate>/opt/shibboleth-idp245/credentials/renater-metadata-signing-cert-2016.pem</security:Certificate>
            </security:Credential>
        </security:TrustEngine>

    • Dans le bloque précédent, faite tout particulièrement attention au contenu de la balise <security:Certificate> qui correspond au chemin local de stockage du fichier contenant le certificat utilisé pour validé la signature des metadata de la fédération
• Télécharger le fichier https://metadata.federation.renater.fr/renater/main/main-all-renater-metadata.xml dans le dossier metadata et faite le appartenir à l'utilisateur du service Tomcat
• Télécharger le fichier https://metadata.federation.renater.fr/certs/renater-metadata-signing-cert-2016.pem dans le dossier credentials

=== Attributs ===

== Récupération des attributs ==

La configuration de la récupération des attributs est défini dans le fichier conf/attribute-resolver.xml. Éditer ce fichier pour :

• Dé-commenter les bloques de définitions des attributs standards :
  • <!-- Schema: Core schema attributes-->
  • <!-- Schema: inetOrgPerson attributes-->
  • <!-- Schema: eduPerson attributes -->
• Ajouter la définition de l'attribut eduPersonTargetedID :

          <resolver:AttributeDefinition id="eduPersonTargetedID"
                  xsi:type="ad:SAML2NameID" nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
                  sourceAttributeID="persistentID">
                  <resolver:Dependency ref="storedId" />
                  <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
                  <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" />
          </resolver:AttributeDefinition>

• Dé-commenter le bloque de définition du connecteur à l'annuaire LDAP <resolver:DataConnector id="myLDAP" ~~> et modifier le comme suit :

      <resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory"
          ldapURL="ldap://ldap.univ.fr" 
          baseDN="ou=people,dc=univ,dc=fr" 
          principal="uid=shibboleth,ou=sysaccounts,dc=univ,dc=fr"
          principalCredential="xxxxxx">
          <dc:FilterTemplate>
              <![CDATA[
                  (uid=$requestContext.principalName)
              ]]>
          </dc:FilterTemplate>
      </resolver:DataConnector>

  • Dans ce bloque, faite tout particulièrement attention :
    • à l'attribut ldapURL qui doit contenir l'URL de connexion à l'annuaire LDAP
    • à l'attribut baseDN qui doit contenir le baseDN de recherche des utilisateurs dans l'annuaire
    • à l'attribut principal qui doit contenir le DN de l'utilisateur de connexion à l'annuaire LDAP
    • à l'attribut principalCredential qui doit contenir le mot de passe de l'utilisateur de connexion à l'annuaire LDAP
    • au contenu de la balise <dc:FilterTemplate> qui doit contenir le filtre de recherche de l'utilisateur dans l'annuaire LDAP. Dans ce filtre, le mot clé $requestContext.principalName sera remplacé par le login utilisé par l'utilisateur pour se connecter au service CAS de l'établissement
• Ajouter le bloque suivant de connexion à la base de données MySQL de stockage de l'identifiant persistant des connexions utilisateurs <resolver:DataConnector id="storedId" ~~> :

      <resolver:DataConnector id="storedId" xsi:type="dc:StoredId"
                          xmlns="urn:mace:shibboleth:2.0:resolver:dc" generatedAttributeID="persistentID"
                          sourceAttributeID="uid" salt="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
        <resolver:Dependency ref="myLDAP" />
        <dc:ApplicationManagedConnection jdbcDriver="com.mysql.jdbc.Driver" jdbcURL="jdbc:mysql://localhost/shibboleth"
                                     jdbcUserName="shibboleth" jdbcPassword="xxxxxxx" />
      </resolver:DataConnector>

  • Dans ce bloque, faite tout particulièrement attention :
    • à l'attribut salt qui doit contenir une chaîne alfa-numérique généré aléatoirement
    • à l'attribut jdbcURL qui doit contenir l'URI JDBC de connexion à la base MySQL au format jdbc:mysql://[hostname]/[db name]
    • à l'attribut jdbcUserName qui doit contenir le nom d'utilisateur de connexion à la base de données MySQL
    • à l'attribut jdbcPassword qui doit contenir le mot de passe de connexion à la base de données MySQL

Créer ensuite la base de données MySQL comme configurée et créer à l'intérieur la table shibpid avec la requête suivante :

CREATE TABLE `shibpid` (
  `localEntity` text NOT NULL,
  `peerEntity` text NOT NULL,
  `principalName` VARCHAR(255) NOT NULL DEFAULT '',
  `localId` VARCHAR(255) NOT NULL,
  `persistentId` VARCHAR(36) NOT NULL,
  `peerProvidedId` VARCHAR(255) DEFAULT NULL,
  `creationDate` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `deactivationDate` TIMESTAMP NULL DEFAULT NULL,
  KEY `persistentId` (`persistentId`),
  KEY `persistentId_2` (`persistentId`,`deactivationDate`),
  KEY `localEntity` (`localEntity`(16),`peerEntity`(16),`localId`),
  KEY `localEntity_2` (`localEntity`(16),`peerEntity`(16),`localId`,`deactivationDate`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

== Filtrage des accès aux attributs par les ressources de la fédération ==

Le filtrage d'accès aux attributs par les ressources de la fédération est configuré :

• d'une part dans le fichier conf/attribute-filter.xml : ce fichier dois contenir les <AttributeFilterPolicy> suivant :

    <!-- Règle permissive renvoyant l'attribut transientID à n'importe quel SP -->
    <AttributeFilterPolicy id="releaseTransientIdToAnyone">
      <PolicyRequirementRule xsi:type="basic:ANY" />
   
      <!-- identifiant utilisateur de session, opaque, généré automatiquement par l'IdP Shibboleth (anciennement appelé nameId dans la fédération du CRU) -->
      <AttributeRule attributeID="transientId">
        <PermitValueRule xsi:type="basic:ANY" />
      </AttributeRule>
   
    </AttributeFilterPolicy>
   
   
    <!-- Règle d'envoi d'un attribut de type targetedID à tout SP de la fédération Education-Recherche-->
    <AttributeFilterPolicy id="releaseTargetedID">
   
      <PolicyRequirementRule xsi:type="saml:AttributeRequesterInEntityGroup" groupID="https://federation.renater.fr/" />
   
      <!-- identifiant utilisateur opaque, persistent et spécifique à un couple SP/IdP -->
      <AttributeRule attributeID="eduPersonTargetedID">
        <PermitValueRule xsi:type="basic:ANY" />
      </AttributeRule>

• d'autre part par un ensemble de fichiers de configuration fournis par la fédération et mis à jours régulièrement. Ces fichiers de configuration sont définis dans le fichier conf/service.xml dans lequel il faut :
  • Modifier le bloque <srv:Service id="shibboleth.AttributeFilterEngine" ~~> comme suit :

        <srv:Service id="shibboleth.AttributeFilterEngine" xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine"
    configurationResourcePollingFrequency="PT1H0M0.000S"
    configurationResourcePollingRetryAttempts="3"
    >
            <srv:ConfigurationResource url="https://federation.renater.fr/renater/filtres/renater-attribute-filters-all.xml" xsi:type="resource:FileBackedHttpResource" file="/opt/shibboleth-idp245/conf/renater-attribute-filters-all.xml"/>
     
            <srv:ConfigurationResource url="https://federation.renater.fr/renater/filtres/renater-attribute-filters-community.xml" xsi:type="resource:FileBackedHttpResource" file="/opt/shibboleth-idp245/conf/renater-attribute-filters-community.xml"/>
     
            <srv:ConfigurationResource url="https://federation.renater.fr/edugain/filtres/edugain-attribute-filters-all.xml" xsi:type="resource:FileBackedHttpResource" file="/opt/shibboleth-idp245/conf/edugain-attribute-filters-all.xml"/>
     
     
            <srv:ConfigurationResource file="/opt/shibboleth-idp245/conf/attribute-filter.xml" xsi:type="resource:FilesystemResource"/>
        </srv:Service>

    • Dans ce bloque, faite tout particulièrement attention :
      • à l'attribut configurationResourcePollingFrequency qui doit contenir la fréquence de rafraîchissement des fichiers de configuration
      • à l'attribut configurationResourcePollingRetryAttempts qui doit contenir le nombre de tentative de rafraîchissement des fichiers de configuration
      • aux balises <srv:ConfigurationResource url="~~" xsi:type="resource:FileBackedHttpResource" file="~~"/> qui déclare les fichiers de configurations récupérés auprès de la fédération par le service. L'attribut url contient l'URL de téléchargement du fichier et l'attribut file le chemin de stockage du fichier

Il est nécessaire ensuite de télécharger une première fois manuellement les fichiers de configuration fournis par la fédération et de les faire appartenir à l'utilisateur du service Tomcat :

wget -O /opt/shibboleth-idp245/conf/renater-attribute-filters-all.xml https://federation.renater.fr/renater/filtres/renater-attribute-filters-all.xml
wget -O /opt/shibboleth-idp245/conf/renater-attribute-filters-community.xml https://federation.renater.fr/renater/filtres/renater-attribute-filters-community.xml
wget -O /opt/shibboleth-idp245/conf/edugain-attribute-filters-all.xml https://federation.renater.fr/edugain/filtres/edugain-attribute-filters-all.xml
chown tomcat: /opt/shibboleth-idp245/conf/renater-attribute-filters-all.xml /opt/shibboleth-idp245/conf/renater-attribute-filters-community.xml /opt/shibboleth-idp245/conf/edugain-attribute-filters-all.xml

===== Procédures =====

==== Remettre en place le couple clé privée/certificat d'une ancienne installation ====

Suite à une réinstallation, il peut être nécessaire de remettre en place un ancien couple clé privée/certificat d'une ancienne installation pour conserver celui décléré auprès de la fédération. Pour cela, il faut, alors que Tomcat est éteint :

• Récupérer les fichiers suivant dans le dossier credentials de l'ancienne installation et les mettre dans le même dossier de la nouvelle :
  • idp.crt
  • idp.key
  • idp.jks
• Éditer le fichier metadata/idp-metadata.xml et remplacer le contenu des deux balises <ds:X509Certificate> par le contenu du fichier idp.crt en ne prenant que ce qu'il y a entre les lignes -----BEGIN CERTIFICATE----- et -----END CERTIFICATE-----