====== Metadata-Fede ======


===== Reference =====

Starting point:
https://spaces.internet2.edu/display/SHIB2/Metadata

Documentation de la fédération Renater (FR)
https://federation.renater.fr/technique/metadata?s[]=metadata

Fédération à Deux
https://federation.renater.fr/docs/fiches/fedadeux

Discussion I had on the shibboleth-users list:
https://mail.internet2.edu/wws/arc/shibboleth-users/2009-11/msg00399.html

===== Objectif =====

Notre institut adhère à la [[https://federation.renater.fr/|fédération national Renater]], afin de partager avec la communauté de l'enseignement supérieur et la recherche en France. Pour des usages plus privés (intranets) au sein de [[http://www.institut-telecom.fr|L'Institut Telecom]] nous avons definis en parallele de la fédération Renater une fédération Institut Telecom. Cette page décrit les aspects techniques de la constitution de cette fédération aux travers notament de la définition de metadata .

===== Principes Metadata =====

Metadata = méta-données "in french !" 

cf [[https://federation.renater.fr/technique/metadata?s|intro]]: "Les méta-données sont un fichier XML signé électroniquement listant tous les fournisseurs d'identités et les ressources de la fédération. Il est utilisé par tous les logiciels de fédération des fournisseurs d'identités et les ressources de la fédération pour se faire mutuellement confiance. "  

===== Locations =====

Pour échanger des données et se faire confiance, les briques techniques (IdP & SP) d'une fédération doivent partager un fichier (XML) décrivant chacune de ses briques. 
Depuis les versions 2.x de shibboleth, il est facile d'accéder aux metadata des briques IdP & SP.

  * SP: le "handler Metadata" du SP y donne un accès direct en ligne: http://sp.domain.eu/Shibboleth.sso/Metadata 
  * IdP: le fichier idp.metadata.xml est automatiquement constitué à l'installation.

   $ls -l /opt/shibboleth-idp/metadata/idp-metadata.xml
   -rw-r--r-- 1 tomcat root 5866 oct 20  2008 /opt/shibboleth-idp/metadata/idp-metadata.xml

===== Structure =====

Afin de constituer un fichier "central" ( a partager entre toutes les acteurs), il suffit de concaténer toutes ces metadata individuels en suivant un certaines terminologie et syntaxe XML .

    * header xml + description
    * optionels certificats, PKI 
    * Providers IdP, SP .

Au dela de la simple concaténation des idp-metadata.xml + SP (URL.../Metadata) il faut rassembler ces <EntityDescriptor> entre 2 balises principales <EntitiesDescriptor>  </EntitiesDescriptor> qui constitut l'ensemble des acteurs de la fédération.
le tout agrémente de commentaires appropriés, cf exemples ci-dessous

==== Exemple ====

  * header
<code>
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!-- FedeIT Jehan V0.5.7 25/11/2009 IDP: Evry,Lille,Paris 1.3 SP:www-public,intranet3 PKIIT2 -->
<EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" Name="https://federation.institut-telecom.fr/" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>
</code>



   * Certificats pour PKI(optionel)

<code>
<!-- AC PKIIT2,  3 levels hierarchie   -->
    <Extensions>
        <shibmd:KeyAuthority VerifyDepth="5" xmlns:shibmd="urn:mace:shibboleth:met
adata:1.0">

<!-- AC IT_ROOT_CA2 , root = level1 here-->
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                            <ds:X509Certificate>
MIIH4TCCBcmgAwIBAgIJAIQtSXlZWjxSMA0GCSqGSIb3DQEBBQUAMGcxPTA7BgNV
...
bgCBc+s=
                </ds:X509Certificate>
        </ds:X509Data>
</ds:KeyInfo>

<!-- AC TI_CA2 level2 sub-CA-->
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                        <ds:X509Certificate>
MIIHkzCCBXugAwIBAgIBAjANBgkqhkiG9w0BAQUFADBnMT0wOwYDVQQDEzRJbnN0
...
zmLouQa8jrPeNp8JDTPgTp2GvXyH6Rw=
                </ds:X509Certificate>
        </ds:X509Data>
</ds:KeyInfo>

<!-- AC TMSP_CA2 level3 sub-sub-CA -->
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                        <ds:X509Certificate>
MIIHrDCCBZSgAwIBAgIBATANBgkqhkiG9w0BAQUFADCBgzE+MDwGA1UEAxM1SW5z
...
dIN5iWlZyevQ1wnf1V1gLoGwYfKZnBgHx++2gbzSCXcOSmGefB+Xy2+TM6VrrFRg
                </ds:X509Certificate>
        </ds:X509Data>
</ds:KeyInfo>

        </shibmd:KeyAuthority>
    </Extensions>
</code>

   * IdP

<code>
<!-- Actual providers go here.  -->
    <!-- identity provider Evry https://shibidp1.it-sudparis.eu/idp/shibboleth -->


<EntityDescriptor entityID="https://shibidp1.it-sudparis.eu/idp/shibboleth" xmlns=
"urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig
#" xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" xmlns:xsi="http://www.w3.org/20
01/XMLSchema-instance">

    <IDPSSODescriptor protocolSupportEnumeration="urn:mace:shibboleth:1.0 urn:oasi
s:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">

        <Extensions>
            <shibmd:Scope regexp="false">it-sudparis.eu</shibmd:Scope>
        </Extensions>

        <KeyDescriptor>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIDSDCCAjCgAwIBAgIVAJv2l61sKf1VgzgHPgGRdmvIdBeGMA0GCSqGSIb3DQEB
...
SA354+sPezlzSyImVbYaHH6naLQuFV7cmUNPOQ==

                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>

        <ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:1.0:bindings:S
OAP-binding" Location="https://shibidp1.it-sudparis.eu:8443/idp/profile/SAML1/SOAP
/ArtifactResolution" index="1"/>

        <ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:S
OAP" Location="https://shibidp1.it-sudparis.eu:8443/idp/profile/SAML2/SOAP/Artifac
tResolution" index="2"/>
        <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDF
ormat>

        <SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnReques
t" Location="https://shibidp1.it-sudparis.eu/idp/profile/Shibboleth/SSO"/>

        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-PO
ST" Location="https://shibidp1.it-sudparis.eu/idp/profile/SAML2/POST/SSO"/>

        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-PO
ST-SimpleSign" Location="https://shibidp1.it-sudparis.eu/idp/profile/SAML2/POST-Si
mpleSign/SSO"/>

        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Re
direct" Location="https://shibidp1.it-sudparis.eu/idp/profile/SAML2/Redirect/SSO"/
>
    </IDPSSODescriptor>

    <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:S
AML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">

        <Extensions>
            <shibmd:Scope regexp="false">it-sudparis.eu</shibmd:Scope>
        </Extensions>

        <KeyDescriptor>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIDSDCCAjCgAwIBAgIVAJv2l61sKf1VgzgHPgGRdmvIdBeGMA0GCSqGSIb3DQEB
...
SA354+sPezlzSyImVbYaHH6naLQuFV7cmUNPOQ==

                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>

        <AttributeService Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-bindi
ng" Location="https://shibidp1.it-sudparis.eu:8443/idp/profile/SAML1/SOAP/Attribut
eQuery"/>
        <AttributeService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Loca
tion="https://shibidp1.it-sudparis.eu:8443/idp/profile/SAML2/SOAP/AttributeQuery"/
>

        <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDF
ormat>

    </AttributeAuthorityDescriptor>

</EntityDescriptor>
</code>

Puis décalration des autres IDP de la fédération "privée", il s'agit du même enchainement de metadata d'IdP (idp-metadata.xml) comprit dans des balises <EntityDescriptor ... </EntityDescriptor>

<code>
    <!-- Lille IDP -->
<EntityDescriptor entityID="https://idp.telecom-lille1.eu/idp/shibboleth"
...
</EntityDescriptor>
<!-- IDP paris shib 1.3 -->

<EntityDescriptor entityID="urn:mace:get.fr:federation:idp.telecomp.fc5">
                <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:S
AML:1.1:protocol urn:mace:shibboleth:1.0">
...
        </EntityDescriptor>

</code>

   * SP

enfin on déclare les SP, en ajoutant les metadata recuperées par l'URL d'acces (exemple http://sp.domain.eu/Shibboleth.sso/Metadata)

<code>
<!-- Services Providers -->

<!-- www-public webspace Evry SP -->

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_eed01b30
c4760e60c193590cebdffd48" entityID="https://www-public.it-sudparis.eu">

  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:prot
ocol urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:1.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

        <ds:X509Data>
          <ds:X509Certificate>MIIDCTCCAfGgAwIBAgIJAKkJ5YK4FZlHMA0GCSqGSIb3DQEBBQUA
MCExHzAdBgNV
...
9lpUQ1jyqa6GVpntdg==
                </ds:X509Certificate>
        </ds:X509Data>

      </ds:KeyInfo>
    </md:KeyDescriptor>

        <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>

    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:bro
wser-post" Location="https://www-public.it-sudparis.eu/Shibboleth.sso/SAML/POST" i
ndex="1"/>
  </md:SPSSODescriptor>

                        <ContactPerson contactType="technical">
                        <SurName>Procaccia</SurName>
                        <EmailAddress>jehan.procaccia@it-sudparis.eu</EmailAddress
>
                        </ContactPerson>
</md:EntityDescriptor>

<!-- SP Evry intranet -->

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_fa4151bf
4d83ed563ea9bc85681b3b0e" entityID="https://intranet.it-sudparis.eu">
...
</md:EntityDescriptor>

</EntitiesDescriptor>
</code>

Attention, bien fermer la fin du fichier XML des metadata par un </EntitiesDescriptor> .

Attention également a la façon dont sont téléchargés les metadata des SP, suivant qu'il le sont en http ou https, les diffrentes "Locations" contenu dans les metadata du SP en seront affecté, cf la discussion que j'ai eu a ce sujet sur la liste shibboleth-users:
https://mail.internet2.edu/wws/arc/shibboleth-users/2009-11/msg00399.html

===== Distribution =====

Pour l'instant un simple "wget" du fichier (metadata.it.xml) sur chacun des acteurs.
A completer par une mise a jour automatique sur les SP, les IdP se chargeant déjà d'une mise à jour automatique (déclaration d'une URL dans relying-party.xml).

Il faudra aussi signer ce fichier !, à completer ....

===== Chargement =====

==== IdP ====

Sur les IdP, il faut declarer les sources de metadata dans "relying-party.xml", le  "type=ChainingMetadataProvider" permet de participer à plusieurs fédération, dans l'exemple ci-dessous 3 fédé => Renater, Renater-test, IT:

<code>
  <!-- ========================================== -->
    <!--      Metadata Configuration                -->
    <!-- ========================================== -->
    <!-- MetadataProvider the combining other MetadataProviders -->
    <MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata">

        <!-- Load the IdP's own metadata.  This is necessary for artifact support. -->
        <MetadataProvider id="IdPMD" xsi:type="ResourceBackedMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" >
            <MetadataResource xsi:type="resource:FilesystemResource" file="/opt/shibboleth-idp/metadata/idp-metadata.xml" />
        </MetadataProvider>
 <!-- Example metadata provider. -->
        <!-- Reads metadata from a URL and store a backup copy on the file system. -->
        <!-- Validates the signature of the metadata and filters out all by SP entities in order to save memory -->
        <!-- To use: fill in 'metadataURL' and 'backingFile' properties on MetadataResource element -->
        
      <!-- MetaData fede Renater -->
        <!-- https://federation.renater.fr/technique/configurations -->
        <MetadataProvider id="renaterMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
                          metadataURL="https://services-federation.renater.fr/metadata/renater-metadata.xml"
                          backingFile="/opt/shibboleth-idp/metadata/renater-metadata.xml">
            <MetadataFilter xsi:type="ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
                <MetadataFilter xsi:type="RequiredValidUntil" xmlns="urn:mace:shibboleth:2.0:metadata"
                                maxValidityInterval="0" />
                <MetadataFilter xsi:type="SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata"
                                trustEngineRef="shibboleth.MetadataTrustEngine"
                                requireSignedMetadata="true" />
                    <MetadataFilter xsi:type="EntityRoleWhiteList" xmlns="urn:mace:shibboleth:2.0:metadata">
                    <RetainedRole>samlmd:SPSSODescriptor</RetainedRole>
                </MetadataFilter>
            </MetadataFilter>
          </MetadataProvider>
          
                 <!-- MetaData fede Test Renater -->
        <MetadataProvider id="renaterTestMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
                          metadataURL="https://services-federation.renater.fr/metadata/renater-test-metadata.xml"
                          backingFile="/opt/shibboleth-idp/metadata/renater-test-metadata.xml">
            <MetadataFilter xsi:type="ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
                <MetadataFilter xsi:type="RequiredValidUntil" xmlns="urn:mace:shibboleth:2.0:metadata"
                                maxValidityInterval="0" />
                <MetadataFilter xsi:type="SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata"
                                trustEngineRef="shibboleth.MetadataTrustEngine"
                                requireSignedMetadata="true" />
                <MetadataFilter xsi:type="EntityRoleWhiteList" xmlns="urn:mace:shibboleth:2.0:metadata">
                    <RetainedRole>samlmd:SPSSODescriptor</RetainedRole>
                </MetadataFilter>
            </MetadataFilter>
        </MetadataProvider>

 <!-- Example metadata provider Fédé IT => exemple from Fédé a 2 : https://federation.renater.fr/cs/fiches/fedadeux  -->

        <!--<MetadataProvider id="fedadeuxMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" > -->
        <MetadataProvider id="fedeIT" xsi:type="ResourceBackedMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" >
                <MetadataResource xsi:type="resource:FilesystemResource" file="/opt/shibboleth-idp/metadata/metadata.it.xml" />
<!--                          metadataURL="https://www-public.it-sudparis.eu/Shibboleth.sso/Metadata"
                          backingFile="/opt/shibboleth-idp/metadata/wpublic-metadata.xml"> -->
       </MetadataProvider>
    </MetadataProvider>
    
    
    <--! for signed Metadata files -->
   <!-- ========================================== -->
    <!--     Security Configurations                -->
    <!-- ========================================== -->
 <security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
        <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.key</security:PrivateKey>
        <security:Certificate>/opt/shibboleth-idp/credentials/idp.crt</security:Certificate>
    </security:Credential>
 
     <!-- Trust engine used to evaluate the signature on loaded metadata. -->
    <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
        <security:Credential id="CruTestCredentials" xsi:type="security:X509Filesystem">
            <security:Certificate>/opt/shibboleth-idp/credentials/federation.cru.fr.crt
</security:Certificate>
        </security:Credential>
    <!-- Confiance certificat metaData REnater -->
        <security:Credential id="renaterCredentials" xsi:type="security:X509Filesystem">
            <security:Certificate>/opt/shibboleth-idp/credentials/metadata-federation-renater.crt</security:Certificate>
        </security:Credential>
    </security:TrustEngine>
   <!-- DO NOT EDIT BELOW THIS POINT -->

    
</code>

==== SP ====

Sur le SP c'est le fichier shibboleth2.xml qui declare les metadata a charger, Sur l'exemple ci-dessous, seule la fédé IT est chargée:

<code>
 <!-- Chains together all your metadata sources. -->
        <MetadataProvider type="Chaining">
         <MetadataProvider type="XML" uri="http://shibidp1.it-sudparis.eu/metadata/metadata.it.xml"
                  backingFilePath="/etc/shibboleth/metadata.it.xml" reloadInterval="7200">
                </MetadataProvider>
        </MetadataProvider>

        <!-- Chain the two built-in trust engines together. -->
        <TrustEngine type="Chaining">
            <TrustEngine type="ExplicitKey"/>
            <TrustEngine type="PKIX"/>
        </TrustEngine>
</code>