SAML-Subject-ID-Attribute

Indice

1 Identificatori utente nella Federazione IDEM
2 Definizione
3 Configurazione per supportare i nuovi standard in Shibboleth IdP e SP
- 3.1 Identity Provider (>=4.0.0)
- 3.2 Service Provider (>=3.0.0)
  - 3.2.1 Attribute Policy
  - 3.2.2 Attribute Map
4 Configurazione per per supportare i nuovi standard in simpleSAMLphp IdP e Sp

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:

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)
<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:

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.
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.
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.

!! Attenzione !! Nel caso sia specificato any allora l'Identity Provider potrebbe rilasciare pairwise-id.

Tale dichiarazione è soggetta all'approvazione del servizio IDEM e 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

La modifica non sarà visibile fino a quando il servizio IDEM non avrà approvato la richiesta di aggiornamento amministrativo via Registry.

[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:

Modificare attribute-resolver.xml
Modificare, se necessario, attribute-filter.xml (la versione di default già contiene le regole di rilascio opportune)
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:

Modificare, se necessario, attribute-policy.xml
Modificare attribute-map.xml
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:

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:

Controllare che SimpleSAMLphp li riconosca entrambi nel file attributemap/urn2name.php (default dalla v2.0.0)
Abilitare la loro generazione ed il loro rilascio attraverso il file metadata/saml20-idp-hosted.php (default nell'HOWTO di IDEM)
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:

Abilitare la richiesta su IDEM Entity Registry come Entity Attribute.
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

SAML-Subject-ID-Attribute

Indice

Identificatori utente nella Federazione IDEM

Definizione

Attributo SAML2 Subject ID

Sintassi

Esempio

Attributo SAML2 Pairwise ID

Sintassi

Esempio

Strategie per la scelta dell'attributo sorgente

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

Come segnalare la richiesta di tali identificatori per un SP

Configurazione per supportare i nuovi standard in Shibboleth IdP e SP

Identity Provider (>=4.0.0)

Attribute Resolver

Attribute Filter

Services

Service Provider (>=3.0.0)

Attribute Policy

Attribute Map

Configurazione per per supportare i nuovi standard in simpleSAMLphp IdP e Sp

Identity Provider (>=2.0.0)

metadata/saml20-idp-hosted.php

conf/idem-attribute-filter.php

Service Provider (>= 2.0.0)

Riferimenti

Menu di navigazione

Strumenti personali

Namespace

Varianti

Visite

Altro

Ricerca

Navigazione

IDEM Wiki

IDEM Organi

GARR CS

Min Salute

Strumenti