SAML-Subject-ID-Attribute

Subject Identifiers nella Federazione IDEM

Dal 2019 con la pubblicazione del documento [SAML-SubjectID-v1.0] "SAML V2.0 Subject Identifier Attributes Profile Version 1.0" sono stati standardizzati due nuovi attributi SAML per l'identificazione dei soggetti di sicurezza, con lo scopo di risolvere molti dei problemi legati ai precedenti Subject Identifier.

I nuovi Subject Indentifier standard sono:

• urn:oasis:names:tc:SAML:attribute:subject-id
• urn:oasis:names:tc:SAML:attribute:pairwise-id

Quelli che finora sono stati utilizzati nella nostra Federazione provengono dallo schema eduPerson e sono:

• eduPersonTargetedID (attributo deprecato normalmente valorizzato con urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
• eduPersonPrincipalName
• eduPersonUniqueID

Oltre all'impiego di attributi è in uso nella nostra Federazione il rilascio dei Name Identifiers nel <saml2:Subject> dell'asserzione SAML:

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient

L'impiego dell' indirizzo e-Mail come identificatore è vietato nella nostra Federazione (https://spaces.at.internet2.edu/display/federation/why-is-email-not-an-appropriate-user-identifier).

Definizione di SAML Subject-ID

Si tratta di un identificatore adatto per identificare univocamente un individuo su qualsiasi SP con le seguenti caratteristiche:

• Omnidirezionale (indipendente dal relying party/SP a cui viene rilasciato)
• Di lunga durata nel tempo
• Non riassegnabile ad altri utenti
• Opaco (può contenere solo: lettere, numeri, . (punti), - (trattini) )

Il suo valore per un determinato soggetto NON è associato al relying party a cui viene rilasciato.

(https://wiki.oasis-open.org/security/SAMLSubjectIDAttr)

L'attributo è destinato a sostituire identificatori legacy come eduPersonUniqueID e eduPersonPrincipalName

Sintassi

Il valore è costituito da due sottostringhe (denominate unique ID e scope) separate da un simbolo @ (ASCII 64) come delimitatore in linea.

Lo unique ID è composto da 1 a 127 caratteri ASCII, ciascuno dei quali può essere un carattere ASCII alfanumerico, un segno di uguale (ASCII 61) o un trattino (ASCII 45). Il primo carattere DEVE essere alfanumerico.

Lo scope è composto da 1 a 127 caratteri ASCII, ciascuno dei quali può essere un carattere ASCII alfanumerico, un trattino (ASCII 45) o un punto (ASCII 46). Il primo carattere DEVE essere alfanumerico.

La grammatica ABNF [ RFC2234 ] è quindi:

<value> = <uniqueID> "@" <scope>
<uniqueID> = (ALPHA / DIGIT) 0*126(ALPHA / DIGIT / "=" / "-")
<scope> = (ALPHA / DIGIT) 0*126(ALPHA / DIGIT / "-" / ".")

Strategie per la scelta dell'attributo sorgente

E' assolutamente necessario riflettere sulla scelta dell'attributo sorgente per la generazione dei nuovi identificatori.

Ecco alcune raccomandazioni:

• non usare identificatori dipendenti dal database o dalla directory utenti come entryCSN (in OpenLDAP), ObjectGUID (Active Directory) e ObjectSid.
• non utilizzare attributi come il codice fiscale (in quanto non opachi)
• prestare attenzione all'uso di uid, sAMAccountName, userPrincipalName in particolare se questi rivelano l'identità dell'utente (in tal caso è necessario applicare una funzione per offuscare il dato, vedere esempio nel codice dell'attributo SubjectHash proposto più avanti).
• attributi che già presentano le caratteristiche di opacità sono ottimi attributi sorgente e non necessitano della manipolazione presente nel codice proposto più avanti (definizione di attributo subjectHash).

Definizione di SAML Pairwise-ID

Si tratta di un identificatore adatto per identificare univocamente un individuo su di uno specifico SP con le seguenti caratteristiche:

• Unidirezionale (dipendente dal relying party/SP a cui viene rilasciato)
• Di lunga durata nel tempo
• Non riassegnabile ad altri utenti
• Opaco (può contenere solo: lettere, numeri, . (punti), - (trattini) )

Il suo valore per un determinato soggetto è associato al relying party a cui viene rilasciato.

(https://wiki.oasis-open.org/security/SAMLSubjectIDAttr)

L'attributo è destinato a sostituire identificatori legacy come eduPersonTargetedID e SAML 2.0 persistent NameID.

Sintassi

Il valore è costituito da due sottostringhe (denominate unique ID e scope) separate da un simbolo @ (ASCII 64) come delimitatore in linea.

Lo unique ID è composto da 1 a 127 caratteri ASCII, ciascuno dei quali può essere un carattere ASCII alfanumerico, un segno di uguale (ASCII 61) o un trattino (ASCII 45). Il primo carattere DEVE essere alfanumerico.

Lo scope è composto da 1 a 127 caratteri ASCII, ciascuno dei quali può essere un carattere ASCII alfanumerico, un trattino (ASCII 45) o un punto (ASCII 46). Il primo carattere DEVE essere alfanumerico.

La grammatica ABNF [ RFC2234 ] è quindi:

<value> = <uniqueID> "@" <scope>
<uniqueID> = (ALPHA / DIGIT) 0*126(ALPHA / DIGIT / "=" / "-")
<scope> = (ALPHA / DIGIT) 0*126(ALPHA / DIGIT / "-" / ".")

Strategie per la scelta dell'attributo sorgente

E' assolutamente necessario riflettere sulla scelta dell'attributo sorgente per la generazione dei nuovi identificatori.

Ecco alcune raccomandazioni:

• non usare identificatori dipendenti dal database o dalla directory utenti come entryCSN (in OpenLDAP), ObjectGUID (Active Directory) e ObjectSid.
• non utilizzare attributi come il codice fiscale (in quanto non opachi)
• prestare attenzione all'uso di uid, sAMAccountName, userPrincipalName in particolare se questi rivelano l'identità dell'utente (in tal caso è necessario applicare una funzione per offuscare il dato, vedere esempio nel codice dell'attributo "SubjectHash" proposto più sotto).
• attributi che già presentano le caratteristiche di opacità sono ottimi attributi sorgente e non necessitano della manipolazione presente nel codice proposto più sotto (definizione di attributo "subjectHash").

Approfondimento: Perché è necessario adottare i nuovi Subject Identifiers?

Esiste un consenso generale da parte degli esperti del settore su alcuni requisiti comuni:

• Gli identificatori dovrebbero essere il più possibile stabili e dovrebbero avere un rischio minimo o nullo di riassegnazione a soggetti diversi.
• Gli identificatori opachi (cioè, superficialmente casuali) sono intrinsecamente più stabili degli identificatori basati sul nome o degli indirizzi e-mail in molte organizzazioni.
• Gli identificatori dovrebbero essere compatti e semplici da maneggiare e manipolare.
• La capacità di esprimere chiaramente la portata dell'unicità di un identificatore e di applicare una politica che stabilisca quali parti assertive siano autorizzate a rilasciare un identificatore è cruciale per i sistemi federati e la mancanza di tale politica ha portato a violazioni ampiamente pubblicizzate.

Molti sono i problemi legati agli identificatori finora in uso:

• eduPersonPrincipalName è stato utilizzato nei casi di identificazione cross-platform, ma è riassegnabile e non è opaco (permette di risalire all'identità dell'utente). Al suo posto può essere usato urn:oasis:names:tc:SAML:attribute:subject-id

• SAML Persistent NameID viene composto come terna che include il valore di entityID dell'IdP e questo ha portato a notevoli workload nella migrazione di tali identificatori nei casi in cui l'IdP aggiorna l'entityID e vuole mantenere gli identificatori esistenti. Al suo posto può essere usato urn:oasis:names:tc:SAML:attribute:pariwise-id

Gli identificatori esistenti hanno bisogno di essere trattati come case-sensitive ma è emerso che molte, se non la maggior parte, delle applicazioni hanno una predisposizione a gestire gli identificatori senza distinzione tra maiuscole e minuscole. Ad esempio la definizione SAML Persistent NameID richiede esplicitamente una gestione con distinzione tra maiuscole e minuscole, rendendone impossibile l'utilizzo sicuro con tali applicazioni senza ricorrere a ulteriori livelli di profilazione.

In ultimo, prima di questa nuova specifica, non era possibile per un Service Provider segnalare la richiesta di almeno uno degli indentificatori presenti nei <md:RequestedAttribute> dei metadata (ad esempio eduPersonPrincipalName OR eduPersonTargetedID). Era solo possibile indicare se l'attributo era richiesto obbligatoriamente isRequested=true o era desiderato isRequested=false. Al contrario la richiesta dei nuovi identificatori non viene più espressa con <md:RequestedAttribute> , ma attraverso la dichiarazione una specifica <md:EntityAttribute> che prevede tra l'altro anche la possibilità di indicare l'opzione any (uno qualsiasi).

Come segnalare la richiesta di tali attributi da parte di un SP

I Service Provider segnalano la richiesta di ricevere Subject Id o Pairwise Id attraverso la dichiarazione nei metadata di uno specifico <md:EntityAttribute>.

I valori possibili per l'Entity Attribute sono subject-id, pairwise-id, any und none. Nel caso sia specificato any allora l'Identity Provider dovrebbe rilasciare pairwise-id.

Tale dichiarazione avviene esclusivamente modificando i metadata del SP via IDEM Entity Registry (https://registry.idem.garr.it/rr3) tramite il percorso Edit Provider -> Entity Attributes e selezionando quello opportuno tra gli Entity Attribute:

• SAML Profiles subject-id:req - subject-id
• SAML Profiles subject-id:req - pairwise-id
• SAML Profiles subject-id:req - any
• SAML Profiles subject-id:req - none

Configurazione per supportare i nuovi standard in Shibboleth IdP e SP

Identity Provider (>=4.0.0)

Per abilitare il supporto ed il rilascio di subject-id e pairwise-id è necessario:

1. Modificare attribute-resolver.xml
2. Modificare, se necessario, attribute-filter.xml (la versione di default già contiene le regole di rilascio opportune)
3. Modificare, se necessario, services.xml

Attribute Resolver

Nel file attribute-resolver.xml si deve aggiungere la definizione dei 2 nuovi attributi con:

<!-- Schema: SAML Subject ID attributes -->
 
<AttributeDefinition id="samlPairwiseID" xsi:type="Scoped" scope="%{idp.scope}">
    <InputDataConnector ref="computed" attributeNames="computedId" />
</AttributeDefinition>

<DataConnector id="computed" xsi:type="ComputedId"
    generatedAttributeID="computedId"
    salt="%{idp.persistentId.salt}"
    algorithm="%{idp.persistentId.algorithm:SHA}"
    encoding="%{idp.persistentId.encoding:BASE32}">

        <InputDataConnector ref="myLDAP" attributeNames="%{idp.persistentId.sourceAttribute}" />

</DataConnector>


<!-- subjectHash è di tipo "scripted" e prende in ingresso "idp.persistentId.sourceAttribute" -->
<!-- "idp.persistentId.sourceAttribute" subisce la funzione "salted hash" -->
<!-- subjectHash così generato viene usato in seguito come parte sinistra di "samlSubjectID" -->

<AttributeDefinition id="subjectHash" xsi:type="ScriptedAttribute" dependencyOnly="true">
    <InputDataConnector ref="myLDAP" attributeNames="%{idp.persistentId.sourceAttribute}" />
    <Script><![CDATA[
      var digestUtils = Java.type("org.apache.commons.codec.digest.DigestUtils");
      var saltedHash  = digestUtils.sha256Hex(%{idp.persistentId.sourceAttribute}.getValues().get(0) + "%{idp.persistentId.salt}");
      subjectHash.addValue(saltedHash);
    ]]></Script>
</AttributeDefinition>
 
<AttributeDefinition id="samlSubjectID" xsi:type="Scoped" scope="%{idp.scope}">
    <InputAttributeDefinition ref="subjectHash" />
</AttributeDefinition>

Attribute Filter

Nel file attribute-filter.xml, all'interno dell'elemento <AttributeFilterPolicyGroup> deve essere presente la seguente regola:

    <!--
    Example rule for honoring Subject ID requirement tag in metadata.
    The example supplies pairwise-id if subject-id isn't explicitly required.
    -->
    <AttributeFilterPolicy id="subject-identifiers">
        <PolicyRequirementRule xsi:type="ANY" />

        <AttributeRule attributeID="samlPairwiseID">
            <PermitValueRule xsi:type="OR">
                <Rule xsi:type="EntityAttributeExactMatch"
                    attributeName="urn:oasis:names:tc:SAML:profiles:subject-id:req"
                    attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                    attributeValue="pairwise-id" />
                <Rule xsi:type="EntityAttributeExactMatch"
                    attributeName="urn:oasis:names:tc:SAML:profiles:subject-id:req"
                    attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                    attributeValue="any" />
            </PermitValueRule>
        </AttributeRule>

        <AttributeRule attributeID="samlSubjectID">
            <PermitValueRule xsi:type="EntityAttributeExactMatch"
                attributeName="urn:oasis:names:tc:SAML:profiles:subject-id:req"
                attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                attributeValue="subject-id" />
        </AttributeRule>
    </AttributeFilterPolicy>

Services

Nel file services.xml va abilitato l'attribute-filter.xml contenente le regole per il rilascio di subject-id e pairwise-id

<util:list id ="shibboleth.AttributeFilterResources">
   <value>%{idp.home}/conf/attribute-filter.xml</value>
   <ref bean="IdemAttributeFilterFull"/>
</util:list>

Service Provider (>=3.0.0)

Per abilitare il supporto ed l'utilizzo di subject-id e pairwise-id è necessario:

1. Modificare, se necessario, attribute-policy.xml
2. Modificare attribute-map.xml
3. Abilitare la richiesta su IDEM Entity Registry come Entity Attribute

Attribute Policy

Per richiedere il subject-id e pairwise-id per il proprio SP nel formato corretto:

<AttributeRule attributeID="subject-id">
   <PermitValueRuleReference ref="ScopingRules"/>
</AttributeRule>

<AttributeRule attributeID="pairwise-id">
   <PermitValueRuleReference ref="ScopingRules"/>
</AttributeRule>

Attribute Map

<!-- New standard identifier attributes for SAML. -->

<Attribute name="urn:oasis:names:tc:SAML:attribute:subject-id" id="subject-id">
   <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>
  
<Attribute name="urn:oasis:names:tc:SAML:attribute:pairwise-id" id="pairwise-id">
   <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>

Segnalare la richiesta di un Subject-ID via IDEM Entity Registry

Configurare il valore del Subject-ID richiesto dalla scheda EntityAttribute di IDEM Entity Registry tenendo in considerazione che selezionando "Any" si riceverà prevalentemente il valore di pairwise-id in quanto più sicuro di subject-id.

Configurazione per per supportare i nuovi standard in SimpleSAMLphp Idp e Sp

Il supporto ufficiale alla generazione e al rilascio di subject-id e pairwise-id in SimpleSAMLphp arriva ufficialmente dalla v2.0.0.

Nella nuova versione di SimpleSAMLphp sono stati sviluppati 2 nuovi moduli per il loro supporto:

• https://simplesamlphp.org/docs/2.0/saml/authproc_pairwiseid.html
• https://simplesamlphp.org/docs/2.0/saml/authproc_subjectid.html

Identity Provider (>=2.0.0)

Gli Identity Provider che sono stati configurati secondo l'HOWTO per SimpleSAMLphp IdP v2.x sono già in grado di rilasciare subject-id e pairwise-id.

Per abilitare il supporto ed il rilascio di subject-id e pairwise-id è necessario:

1. Controllare che SimpleSAMLphp li riconosca entrambi nel file attributemap/urn2name.php (default dalla v2.0.0)
2. Abilitare la loro generazione ed il loro rilascio attraverso il file metadata/saml20-idp-hosted.php (default nell'HOWTO di IDEM)
3. Aggiornare, se necessario, il file conf/idem-attribute-filter.php distribuito in RilascioAttributi#SimpleSAMLphp Identity Provider

attributemap/urn2name.php

'urn:oasis:names:tc:SAML:attribute:pairwise-id'               => 'pairwise-id',
'urn:oasis:names:tc:SAML:attribute:subject-id'                => 'subject-id',

metadata/saml20-idp-hosted.php

Nel file metadata/saml20-idp-hosted.php, all'interno dell'elemento 'authproc' devono essere presenti i seguenti Authentication Process Filter:

// Add subject-id
13 => [
      'class' => 'saml:SubjectID',
      'identifyingAttribute' => 'uid',
      'scopeAttribute' => 'schacHomeOrganization',
],

// Add pairwise-id
14 => [
      'class' => 'saml:PairwiseID',
      'identifyingAttribute' => 'uid',
      'scopeAttribute' => 'schacHomeOrganization',
],

// The Attribute Limit will be use to release all possibile values supported by IdP to SPs
// Remember to comment out the same part with "50" on config/config.php file 
// or no attributes will be released
50 => [
      'class' => 'core:AttributeLimit',
      'uid','givenName','sn','cn','mail','displayName','mobile',
      'title','preferredLanguage','telephoneNumber',
      'schacMotherTongue','schacPersonalTitle','schacHomeOrganization',
      'schacHomeOrganizationType','schacUserPresenceID','schacPersonalPosition',
      'schacPersonalUniqueCode','schacPersonalUniqueID',
      'eduPersonPrincipalName','eduPersonEntitlement',
      'urn:oasis:names:tc:SAML:attribute:subject-id',
      'urn:oasis:names:tc:SAML:attribute:pairwise-id',
      'eduPersonTargetedID',
      'eduPersonOrcid','eduPersonOrgDN','eduPersonOrgUnitDN',
      'eduPersonScopedAffiliation' => [
         'regex' => true,
         '/^student@.*/',
         '/^staff@.*/',
         '/^library-walk-in@.*/',
         '/^affiliate@.*/',
         '/^member@.*/',
         '/^alum@.*/',
         '/^employee@.*/',
         '/^faculty@.*/',
      ],'eduPersonAffiliation' => [
         'student',
         'staff',
         'member',
         'alum',
         'affiliate',
         'library-walk-in',
         'faculty', // NO IDEM
         'employee', // NO IDEM
      ],
],

// IDEM Attribute Filter:
// IDEM SPs + Entity Category SPs + Custom SPs
60 =>[
    'class' => 'core:PHP',
    'code'  =>
    '
    $config_dir = apache_getenv("SIMPLESAMLPHP_CONFIG_DIR");
    include($config_dir."/idem-attribute-filter.php");
    '
],

conf/idem-attribute-filter.php

$sp_subject_id_array = [];
$subject_id = "subject-id";
$pairwise_id = "pairwise-id";
$any_id = "any";

if (isset($state["SPMetadata"]["EntityAttributes"]["urn:oasis:names:tc:SAML:profiles:subject-id:req"]))
   $sp_subject_id_array = $state["SPMetadata"]["EntityAttributes"]["urn:oasis:names:tc:SAML:profiles:subject-id:req"];

// Subject-ID and/or Pairwise-ID attribute release
if ($sp_subject_id_array){
  foreach ($sp_subject_id_array as $sp_id){
    if (strcmp($sp_id, $subject_id) == 0){
       array_push($remaining_attributes, "urn:oasis:names:tc:SAML:attribute:subject-id");
    }

    if ((strcmp($sp_id, $pairwise_id) == 0) or (strcmp($sp_id, $any_id) == 0)){
       array_push($remaining_attributes, "urn:oasis:names:tc:SAML:attribute:pairwise-id");
    }
  }
}

Service Provider (>= 2.0.0

Per abilitare il supporto ed l'utilizzo di subject-id e pairwise-id è necessario:

1. Abilitare la richiesta su IDEM Entity Registry come Entity Attribute.
2. Utilizzare $attributes['[[1]]'] o $attributes['[[2]]'] nella propria applicazione PHP.

Segnalare la richiesta di un Subject-ID via IDEM Entity Registry

Configurare il valore del Subject-ID richiesto dalla scheda EntityAttribute di IDEM Entity Registry tenendo in considerazione che selezionando "Any" si riceverà prevalentemente il valore di pairwise-id in quanto più sicuro di subject-id.