ComeRilasciareAttributiShibv4

Quali attributi SAML vengono trattati all'interno della Federazione IDEM?

L'elenco completo degli attributi, le possibili valorizzazioni e la corretta sintassi sono contenuti nel documento: File:SpecificheTecnicheAttributi v3.0 20161129.pdf

Elementi chiave della configurazione Shibboleth v4 e tool di verifica

Attribute Resolver - file conf/attribute-resolver.xml

• Data Connector - tag XML <DataConnector id="myLDAP" xsi:type="LDAPDirectory" ... >
  • l'attributo XML exportAttributes deve contenere una lista di attributi recuperati direttamente dal Data Connector.
    • la lista degli attributi, separati da uno spazio, è definita in conf/ldap.properties alla voce idp.attribute.resolver.LDAP.exportAttributese va compilata sulla base di quali attributi possono essere presi dalla Directory (Active Directory / OpenLDAP). Ogni attributo della Directory per il quale non esiste in conf/attributes/ un <bean> contenente il nome dell'attributo <prop key="id">NOME-ATTRIBUTO</prop>, non può essere rilasciato a meno di tornare al vecchio meccanismo di definizione degli attributi usato dalle precedenti versioni di Shibboleth IdP.
• Attribute Definition - tag XML <AttributeDefinition xsi:type="..." id="..." > :
  • xsi:type possibili: Simple, PrincipalName, Scoped, Prescoped, RegexSplit, ScriptedAttribute, Mapped, Template, SubjectDerived, ContextDerived, Decrypted (https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631550/AttributeDefinitionConfiguration#AttributeDefinition-Plugin-Types) e SAML2NameID (anche se DEPRECATO)
  • id: identificatore dell'IdPAttribute generato dal framework SAML "Shibboleth" ad uso interno (Attribute Registry / Attribute Filter)

Attribute Registry - tutto il contenuto della cartella conf/attributes/

Attribute Filter - file conf/attribute-filter.xml e file conf/idem-attribute-filter-v4-full.xml. (https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631517/AttributeFilterConfiguration).

AACLI - command line tool integrato nell'installazione per verificare il rilascio di attributi (esempi inclusi). Inoltre è disponibile una pagina speciale di istruzioni per AACLI: VerificareRilascioAttributiAACLI

Comando xmlwf - command line tool per la verifica sintattica dei file XML

La risoluzione degli attributi

La risoluzione degli attributi (Attribute Resolver - https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631549/AttributeResolverConfiguration) è il processo di raccolta dei dati relativi ad un determinato utente dopo che questo si è autenticato sull'Identity Provider.

L'Attribute Resolver non contiene direttamente i dati utente, ma le fonti (Data Connectors - https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631564/DataConnectorConfiguration) e le definizioni (Attribute Definition - https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631550/AttributeDefinitionConfiguration) che consentono di recuperare e convertire gli attributi in oggetti "IdPAttribute" che poi verranno convertiti dall'Attribute Registry nel formato necessario alla risorsa federata che li ha richiesti.

Nelle versioni precedenti dell'IdP Shibboleth, l'Attribute Resolver era responsabile del collegamento degli AttributeEncoders alle Attribute Definition per stabilire il formato del valore di uno specifico attributo.

Questo è ancora supportato, ma un approccio migliore nella V4 consiste nell'affidarsi a un insieme comune di regole di codifica contenute nella nuova AttributeRegistryConfiguration e basate su convenzioni ragionevoli per i nomi degli oggetti IdPAttribute. Ad esempio, se si accetta semplicemente di inserire l'indirizzo e-mail dell'utente in un IdPAttribute chiamato "mail", l'Attribute Registry sa come codificarlo in SAML automaticamente utilizzando il nome indicato dallo standard [https://wiki.oasis-open.org/security/SstcSaml2AttributeX500Profile]

Per impostazione predefinita il servizio di risoluzione degli attributi si trova nel file conf/attribute-resolver.xml. In esso sono definiti gli attributi da risolvere.

È possibile specificare ed utilizzare più file "resolver" modificando il <bean> a cui fa riferimento la proprietà idp.service.attribute.resolver.resources (valore predefinito shibboleth.AttributeResolverResources nel file conf/services.xml  ) o modificando la proprietà puntando ad un <bean> con 'id' diverso.

Attribute Registry

Il servizio Attribute Registry fornisce un più avanzato sistema per configurare la relazione tra gli oggetti interni IdPAttribute, che sono (per la maggior parte) prodotti da Attribute Resolver, e il formato dei dati scambiati in SAML, CAS o in futuro OIDC.

L'Attribute Registry è stato progettato per affrontare la mappatura dei dati tra formati indipendentemente dall'Attribute Resolver, il quale si occupa principalmente di raccogliere i dati e non di codificarli.

Lo scopo dell'Attribute Registry è supportare casi d'uso aggiuntivi che non erano, se non del tutto, supportati dal vecchio design, ad esempio:

• proxy di attributi ottenuti da provider SSO esterni che non provengono da Attribute Resolver
• mappatura di SAML (o altri protocolli) in dati interni, come nel caso dei  <RequestedAttribute> nei metadati SAML
• eliminare la necessità della definizione di attributi di tipo SimpleAttributeDefinition se utilizzato esclusivamente per collegare gli Attribute Encoders.

Per approfondimenti:

https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1272054306/AttributeRegistryConfiguration

Risoluzione degli attributi in Shibboleth IdP v4 con le guide di IDEM

Se avete installato un IdP v4 seguendo le guide del servizio IDEM allora state sfruttando tutte le potenzialità del servizio Attribute Registry.

Tramite la guida di installazione viene fornito un file attribute-resolver.xml di esempio: attribute-resolver-v4-idem-sample.xml.

Per le nuove installazioni e per chi sta migrando dalla versione Shibboleth IdP v3 tale file rappresenta un'ottima base di partenza a cui aggiungere le ulteriori Attribute Definition tenendo a mente le seguenti strategie:

• Rimozione degli Attribute Encoders in fase di migrazione dalla v3
• Attributo recuperabile as-is in AD/LDAP
• Attributo recuperabile in AD/LDAP rinominando l'attributo sorgente
• Attributo non presente in AD/LDAP ma generato da un attributo sorgente tramite combinazione o trasformazione
• Attributo per il quale non sono definiti gli Encorders in Registry

Gli esempi indicati qui sotto funzionano a patto che le guide siano state seguite correttamente ed in particolare che siano state impiegate le strategie di Attribute Filter alla voce "Configure Attribute Filter Policy to release attributes to Federated Resources". Gli Attribute Filter forniti da IDEM funzionano a patto che siano impiegati in Attribute Resolver i nomi di attributi standard.

Rimozione degli Attribute Encoders in fase di migrazione dalla v3

Per definire un attributo non è più necessario, nella maggior parte dei casi, usare alcun Attribute Encoder.

Al contrario, copiare nella v4 una definizione di attributo che funzionava nella versione v3 potrebbe produrre la duplicazione del valore di quell'attributo.

Esempio di definizione ERRATA con Encoders come presente nella v3:

<!-- Definizione ERRATA che include gli Encoders, NON USARE -->

    <AttributeDefinition scope="%{idp.scope}" xsi:type="Scoped" id="eduPersonScopedAffiliation">
        <InputDataConnector ref="myLDAP" attributeNames="eduPersonAffiliation" />
        <AttributeEncoder xsi:type="SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" encodeType="false" />
        <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" friendlyName="eduPersonScopedAffiliation" encodeType="false" />
    </AttributeDefinition>

L'attributo viene rilasciato con valore duplicato:

<!--  bash /opt/shibboleth-idp/bin/aacli.sh -n test1 -r https://sp.aai-test.garr.it/shibboleth --saml2 -->

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_bd72f90a1a9eb18bf4b8aa94281d8a1a" IssueInstant="2022-05-05T13:32:39.380Z" Version="2.0">

<!-- omissis -->

    <saml2:AttributeStatement>
        <saml2:Attribute FriendlyName="eduPersonScopedAffiliation" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>member@aai-test.garr.it</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="eduPersonScopedAffiliation" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>member@aai-test.garr.it</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Inoltre, uno dei grandi vantaggi apportati da Attribute Registry è quello di eliminare la necessità di definire un attributo se questo ha un nome standard ed è recuperato, senza necessità di ulteriori trasformazioni, da un Data Connector (che già lo contiene) con l'opzione exportAttributes.

Per conoscere quali attributi sono esportabili da AD/LDAP è sufficiente usare il comando ldapsearch

Attributo recuperabile as-is in AD/LDAP

Se uno degli attributi che si vuole rilasciare è recuperabile da uno dei Data Connector già definiti nel file attribute-resolver.xml ed ha un nome standard che Attribute Registry sa codificare allora basterà inserire il nome di tale attributo nel file ldap.properties alla riga idp.attribute.resolver.LDAP.exportAttributes e questo sarà recuperato e codificato in SAML senza alcuna ulteriore definizione

# file conf/ldap.properties
idp.attribute.resolver.LDAP.exportAttributes = telephoneNumber mail givenName eduPersonOrgDN sn preferredLanguage cn

In questo esempio sono stati esportati i nomi degli attributi come definiti all'interno di AD/Ldap e dato che molti di essi hanno dei nomi standard, NON c'è bisogno di definirli in attribute-resolver.xml Ecco come verificare che gli attributi siano correttamente rilasciati:

<!--  bash /opt/shibboleth-idp/bin/aacli.sh -n test1 -r https://sp.aai-test.garr.it/shibboleth --saml2 -->

<?xml version="1.0" encoding="UTF-8"?><saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_9b165ed354c40c45c78c72967922d727" IssueInstant="2022-05-09T12:44:47.205Z" Version="2.0">
    <saml2:Issuer>https://idp.aai-test.garr.it/idp/shibboleth</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="https://idp.aai-test.garr.it/idp/shibboleth" SPNameQualifier="https://sp.aai-test.garr.it/shibboleth">CTD4BZ7GRBW2K4MDOV5UITVXPSTDFZDL</saml2:NameID>
    </saml2:Subject>
    <saml2:AttributeStatement>
        <saml2:Attribute FriendlyName="telephoneNumber" Name="urn:oid:2.5.4.20" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>+39 333 123 1231</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>test1_email@aai-test.garr.it</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="givenName" Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>Test 1</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="eduPersonOrgDN" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>dc=aai-test,dc=garr,dc=it</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="sn" Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>test1</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="preferredLanguage" Name="urn:oid:2.16.840.1.113730.3.1.39" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>it</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute FriendlyName="cn" Name="urn:oid:2.5.4.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>test1</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Attributo recuperabile in AD/LDAP rinominando l'attributo sorgente

se uno degli attributi che si vuole rilasciare è recuperabile da uno dei Data Connector già definiti nel file attribute-resolver.xml e non ha un nome standard allora è necessario creare una AttributeDefinition per rimappare il nome non standard in uno standard (senza definizione di Encoder perché ci penserà AttributeRegistry)

# file conf/ldap.properties

idp.attribute.resolver.LDAP.exportAttributes = telephoneNumber givenName eduPersonOrgDN sn preferredLanguage cn

Non è necessario inserire l'attributo e-Mail nel file ldap.properties alla riga idp.attribute.resolver.LDAP.exportAttributes in quanto l'attributo verrà rinominato nella nuova definizione qui sotto.

<!-- file attribute-resolver.xml -->

<AttributeDefinition xsi:type="Simple" id="mail">
   <InputDataConnector ref="myLDAP" attributeNames="e-Mail" />
</AttributeDefinition>

Ecco come verificare che gli attributi siano correttamente rilasciati (viene mostrato solo mail appena definito):

<!--  bash /opt/shibboleth-idp/bin/aacli.sh -n test1 -r https://sp.aai-test.garr.it/shibboleth --saml2 -->

<?xml version="1.0" encoding="UTF-8"?><saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_9b165ed354c40c45c78c72967922d727" IssueInstant="2022-05-09T12:44:47.205Z" Version="2.0">
    <saml2:Issuer>https://idp.aai-test.garr.it/idp/shibboleth</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="https://idp.aai-test.garr.it/idp/shibboleth" SPNameQualifier="https://sp.aai-test.garr.it/shibboleth">CTD4BZ7GRBW2K4MDOV5UITVXPSTDFZDL</saml2:NameID>
    </saml2:Subject>
    <saml2:AttributeStatement>
    < ... omissis ... >
        <saml2:Attribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>test1_email@aai-test.garr.it</saml2:AttributeValue>
        </saml2:Attribute>
    < ... omissis ... >
    </saml2:AttributeStatement>
</saml2:Assertion>

Attributo non presente in AD/LDAP ma generato da un attributo sorgente tramite combinazione o trasformazione

se uno degli attributi che si vuole rilasciare NON è recuperabile da un Data Connector già definito nel file attribute-resolver.xml, ma può essere ottenuto come combinazione o trasformazione di altri attributi sorgente (recuperati a loro volta da un Data Connector o già definiti in una Attribute Definition) allora sarà necessario creare una Attribute Definition per definire come l'attributo viene generato (senza definizione di Encoder perché ci penserà AttributeRegistry).

Gli algoritmi possibili per combinare o trasformare attributi sono: Simple, Scoped, Prescoped, RegexSplit, ScriptedAttribute, Mapped, Template, SubjectDerived, ContextDerived, Decrypted 4.1 . Si prega di approfondire sul wiki di Shibboleth per ottenere spiegazioni ed esempi relativi a tutti gli algoritmi esistenti: https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631550/AttributeDefinitionConfiguration

Oltre agli esempi mostrati qui sotto sono disponibili:

• eduPersonAffiliation: generato con tipo Mapped - Attributo Affiliazione
• eduPersonScopedAffiliation: generato con tipo Scoped - Attributo Affiliazione
• schacPersonalUniqueCode: generato sia con tipo Template che con tipo ScriptedAttribute - Erasmus Plus e ESI
• Define dynamically attributes for Shibboleth IdP v4 : fornisce esempi di tipo Simple, Template, Mapped, ScriptedAttribute, Scoped

Nel seguente codice l'attributo displayName viene generato con Attribute Definition di tipo Template a partire dagli attributi sorgente givenName e sn, che a loro volta sono stati recuperati da AD/Ldap senza definizione di Attributo. Per confronto vedere anche l'esempio successivo.

<!-- file attribute-resolver.xml -->

<AttributeDefinition id="displayName" xsi:type="Template">
        <InputDataConnector ref="myLDAP" attributeNames="givenName" />
        <InputDataConnector ref="myLDAP" attributeNames="sn" />
    <Template>${givenName} ${sn}</Template>
</AttributeDefinition>

Nel seguente codice l'attributo displayName viene generato con Attribute Definition di tipo Template a partire dagli attributi sorgente givenName e sn, che a loro volta sono stati definiti con Attribute Definition.

<!-- file attribute-resolver.xml -->

<AttributeDefinition id="givenName" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="nome-preso-da-AD-Ldap" />
</AttributeDefinition>

<AttributeDefinition id="sn" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="cognome-preso-da-AD-Ldap" />
</AttributeDefinition>

<AttributeDefinition id="displayName" xsi:type="Template">
    <InputAttributeDefinition ref="givenName" />
    <InputAttributeDefinition ref="sn" />
    <Template>${givenName} ${sn}</Template>
</AttributeDefinition>

Ecco come verificare che gli attributi siano correttamente rilasciati (viene mostrato solo displayName appena definito, indipendentemente dal metodo usato):

<!--  bash /opt/shibboleth-idp/bin/aacli.sh -n test1 -r https://sp.aai-test.garr.it/shibboleth --saml2 -->

<?xml version="1.0" encoding="UTF-8"?><saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_9b165ed354c40c45c78c72967922d727" IssueInstant="2022-05-09T12:44:47.205Z" Version="2.0">
    <saml2:Issuer>https://idp.aai-test.garr.it/idp/shibboleth</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="https://idp.aai-test.garr.it/idp/shibboleth" SPNameQualifier="https://sp.aai-test.garr.it/shibboleth">CTD4BZ7GRBW2K4MDOV5UITVXPSTDFZDL</saml2:NameID>
    </saml2:Subject>
    <saml2:AttributeStatement>
    < ... omissis ... >
        <saml2:Attribute FriendlyName="displayName" Name="urn:oid:2.16.840.1.113730.3.1.241" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue>Mario Rossi</saml2:AttributeValue>
        </saml2:Attribute>
    < ... omissis ... >
    </saml2:AttributeStatement>
</saml2:Assertion>

Attributo per il quale non sono definiti gli Encorders in Registry

Qualora sia necessario risolvere un attributo non standard, utilizzato ad esempio per servizi interni, è necessario aggiungere gli opportuni Encoders in quanto, con altissima probabilità, questi non sono contenuti in Attribute Registry.

Attenzione: un attributo con nome non standard non è mai incluso nei filtri distribuiti dal servizio IDEM ed è quindi necessario intervenire manualmente nel file Attribute Filter locale all'idp per abilitare il rilascio di tale attributo.

Due sono le possibili modalità per procedere:

• all'interno del file attribute-resolver.xml aggiungendo una Attribute Definition con Encoders
• aggiunta di un attributo custom in Attribute Registry all'interno della cartella conf/attributes/custom

Un buon esempio di aggiunta di un attributo custom in Attribute Registry è presente nella guida di installazione alla voce Configure Shibboleth Identity Provider to release the eduPersonTargetedID e nel file eduPersonTargetedID.properties

Il riferimento ufficiale nel wiki di Shibboleth v4 è https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1272054333/TranscodingRuleConfiguration

Casi speciali

Risolvere un attributo in base al Requester

Supponiamo che l'attributo mail in AD/Ldap contenga valori multipli. L'obiettivo di questa implementazione è recuperare per un sottoinsieme di Service Provider (in questo esempio SCARR) solo la mail istituzionale (ottenendo per l'attributo mail un solo valore). Per tutti gli altri Service Provider l'attributo mail continuerà ad essere multi valore.

Elementi della configurazione:

• Attribute Definition per attributo mail con tipo RegexSplit ed indicazione dei relyingParties per i quali il codice verrà eseguito
• Attribute Definition per attributo mail con tipo Simple ed indicazione dei relyingParties per i quali il codice non verrà eseguito

<!-- file attribute-resolver.xml -->

<!-- Per il Service Provider SCARR l'attributo "mail" viene definito recuperando solo la mail istituzionale -->

    <AttributeDefinition id="mail" xsi:type="RegexSplit" regex="(.+@dominio\.it)" relyingParties="https://scarr.garr.it/shibboleth">
        <InputDataConnector ref="myLDAP" attributeNames="mail" />
    </AttributeDefinition>

<!-- Per tutti gli altri SP eccetto SCARR l'attributo "mail" viene recuperato as-is dal DataConnector -->

    <AttributeDefinition xsi:type="Simple" id="mail" excludeRelyingParties="https://scarr.garr.it/shibboleth">
        <InputDataConnector ref="myLDAP" attributeNames="mail" />
    </AttributeDefinition>

Configurazione per Office 365

Configurare Shibboleth IdP v4.x per Office 365

Configurazione per Google Suite

Configurare Shibboleth IdP v4.x per Google Suite