SAML-Subject-ID-Attribute

Identificatori utente nella Federazione IDEM

Dal 2019, con la pubblicazione del documento "SAML V2.0 Subject Identifier Attributes Profile Version 1.0" [SAML-SubjectID-v1.0], sono stati introdotti due nuovi attributi standard per SAML 2.0 al fine di identificare gli utenti e risolvere molti dei problemi legati agli identificatori SAML 2.0 già in uso.

Il documento SAML-SubjectID-v1.0 definisce due attributi con NameFormat URI da utilizzare come identificatori utenti:

• urn:oasis:names:tc:SAML:attribute:subject-id: un identificatore generale e globalmente univoco (vedi la sezione Definizione per maggiori dettagli).

• urn:oasis:names:tc:SAML:attribute:pairwise-id: un identificatore specifico per il servizio a cui è rilasciato (vedi la sezione Definizione per maggiori dettagli).

I nuovi identificatori si vanno ad aggiungere agli identificatori già supportati e permessi nella Federazione IDEM, ovvero:

1. Attributi SAML (provenienti dallo schema eduPerson):
   • eduPersonPrincipalName
   • eduPersonUniqueID
   • eduPersonTargetedID ('deprecato, ma ancora utilizzato da alcuni servizi; assume normalmente lo stesso valore del NameID di tipo persistent': urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
2. <saml2:NameID> Name Identifiers nel <saml2:Subject> dell'asserzione SAML nei formati:
   • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (SAML Persistent NameID)
   • urn:oasis:names:tc:SAML:2.0:nameid-format:transient (SAML Transient NameID)

[TOP]

Definizione

Attributo SAML2 Subject ID

Identificatore di individuo unico e globale per tutti i relying party/SP.

Le sue caratteristiche sono:

• Indipendente dal relying party/SP a cui viene rilasciato
• Di lunga durata nel tempo
• Non riassegnabile ad altri individui
• Opaco (non può contenere informazioni sull'individuo)

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

Sintassi

Il valore è costituito da due sottostringhe (unique ID e scope) separate dal simbolo @ (ASCII 64).

Lo unique ID è un valore alfanumerico di massimo 127 caratteri che può contenere il simbolo di uguale (= ASCII 61) o il simbolo del trattino (- ASCII 45). DEVE iniziare con un carattere alfanumerico.

Lo scope è un valore alfanumerico di massimo 127 caratteri che può contenere il simbolo del punto (. ASCII 46) o il simbolo del trattino (- ASCII 45). DEVE iniziare con un carattere alfanumerico.

La grammatica ABNF [RFC2234] è:

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

Esempio

Valore dell'attributo:

idm123-456789=@example.com

Codifica SAML 2.0:

<saml:Attribute Name="urn:oasis:names:tc:SAML:attribute:subject-id"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml:AttributeValue>idm123-456789=@example.com</saml:AttributeValue>
</saml:Attribute>

[TOP]

Attributo SAML2 Pairwise ID

Identificatore di individuo specifico per ciascun relying party/SP.

Le sue caratteristiche sono:

• Dipendente dal relying party/SP a cui viene rilasciato
• Di lunga durata nel tempo
• Non riassegnabile ad altri individui
• Opaco (non può contenere informazioni sull'individuo)

L'attributo è destinato a sostituire identificatori targeted come eduPersonTargetedID ed il <saml2:NameID> di tipo persistent.

Sintassi

Il valore è costituito da due sottostringhe (unique ID e scope) separate dal simbolo @ (ASCII 64).

Lo unique ID è un valore alfanumerico di massimo 127 caratteri che può contenere il simbolo di uguale (= ASCII 61) o il simbolo del trattino (- ASCII 45). DEVE iniziare con un carattere alfanumerico.

Lo scope è un valore alfanumerico di massimo 127 caratteri che può contenere il simbolo del punto (. ASCII 46) o il simbolo del trattino (- ASCII 45). DEVE iniziare con un carattere alfanumerico.

La grammatica ABNF [RFC2234] è:

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

Esempio

Valore dell'attributo:

HA2TKNZZGE2TOZDCGMZWKOLDHBQWIMBSGM4TGZBYGUYGINRQHAYTINBZGYZDOZBZMZRGKNZTME3TMNBXGYYTIOBYGMYWKNLFMYYDAYY=@osu.edu

Codifica SAML 2.0:

<saml:Attribute Name="urn:oasis:names:tc:SAML:attribute:pairwise-id"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml:AttributeValue>
HA2TKNZZGE2TOZDCGMZWKOLDHBQWIMBSGM4TGZBYGUYGINRQHAYTINBZGYZDOZBZMZRGKNZTME3TMNBXGYYTIOBYGMYWKNLFMYYDAYY=@osu.edu
    </saml:AttributeValue>
</saml:Attribute>

[TOP]

Strategie per la scelta dell'attributo sorgente

Si rende assolutamente necessario riflettere sulla scelta della parte univoca, <uniqueID>, inserita nei nuovi identificatori.

Ecco alcune raccomandazioni:

• non usare identificatori dipendenti dal database o dalla directory utenti come entryCSN (in OpenLDAP), ObjectGUID (Active Directory) e ObjectSid.
• utilizzare solo identificatori indipendenti dai dati dell'utente
• un ottimo esempio di identificatore che rispetta gli standard è Universally unique identifier (UUID) nella versione 4 (non utilizzare la versione 3 e 5). Riferimento: https://datatracker.ietf.org/doc/html/rfc4122
• non utilizzare attributi come il Codice Fiscale senza applicare una funzione che ne offuschi il valore. (Vedere l'esempio riportato per la definizione dell'attributo subjectHash più avanti).
• prestare attenzione all'uso di uid, sAMAccountName, userPrincipalName. Se il loro valore rivela l'identità dell'utente è necessario offuscarlo. (Vedere l'esempio riportato per la definizione dell'attributo subjectHash più avanti).
• non utilizzare attributi che possono essere riassegnati come eduPersonPrincipalName o altri.
• attributi già opachi che non necessitano di offuscare valori che rivelano l'identità dell'utente sono ottimi com attributi sorgente per la generazione dei nuovi identificatori.

[TOP]

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

Dal passato abbiamo imparato che:

1. utilizzare un identificatore come eduPersonPrincipalName, non opaco e riassegnabile, è pericoloso: Un individuo potrebbe non essere identificato correttamente se il valore dell'identificatore venisse riassegnato e, inoltre, potrebbero essere esposte informazioni personali.
2. utilizzare un identificatore come il SAML Persistent NameID o eduPersonTargetedID, che integra nel suo valore l'entityID di IdP ed SP, è problematico: Un individuo perde l'accesso alle risorse che lo utilizzano e che ne memorizzano il valore localmente nel momento in cui l'SP o l'IdP decide di modificare il proprio entityID. Questo comportamento costringe alla rigenerazione dell'identificatore da parte dell'IdP e la modifica dei valori salvati da parte dell'SP con un notevole dispendio di tempo. Oltre a questo, se non viene trattato come un valore "case-sensitive" dalle risorse, l'identificazione sicura dell'utente non può essere garantita.
3. nel momento in cui scriviamo non è possibile per un relying party/SP richiedere il rilascio di un identificatore qualsiasi (any) tra i molteplici che supporta, ma è costretto a sceglierne uno come obbligatorio (isRequired="True") e dichiarare l'altro come desiderato (isRequired="False") portando spesso gli Identity Provider al mancato rilascio dell'identificatore necessario all'accesso delle risorse.

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 l'ambito di unicità di un identificatore e di applicare politiche che definiscano quali entità possono emettere tali identificatori è fondamentale per i sistemi federati. La mancanza di queste politiche ha portato ad incidenti ben noti.

[TOP]

Come segnalare la richiesta di tali identificatori per un SP

I Service Provider segnalano la richiesta di voler 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 e 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 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

[TOP]

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 conf/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 conf/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 conf/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>

[TOP]

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>

[TOP]

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");
    }
  }
}

[TOP]

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['urn:oasis:names:tc:SAML:attribute:subject-id'] o $attributes['urn:oasis:names:tc:SAML:attribute:pairwise-id'] nella propria applicazione PHP.

[TOP]

Riferimenti

• [SAML-SubjectID-v1.0]: https://wiki.oasis-open.org/security/SAMLSubjectIDAttr
• [RFC2234]: https://www.rfc-editor.org/rfc/rfc2234