SAML-Subject-ID-Attribute

Da WIKI IDEM GARR.
Jump to navigation Jump to search

Subject Identifiers 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 per identificare i soggetti di sicurezza e risolvere molti dei problemi legati ai precedenti Subject Identifier.

I nuovi identificatori sono:

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

La Federazione IDEM, ad oggi, utilizza due tipi di identificatori utente:

  1. Attributi SAML (provenienti dallo schema eduPerson):
    • eduPersonTargetedID (deprecato e assume normalmente lo stesso valore del NameID di tipo 'persistent': urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
    • eduPersonPrincipalName
    • eduPersonUniqueID
  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)

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

[TOP]

Definizione di SAML 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 legacy 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

idm123-456789=@example.com


[TOP]

Definizione di SAML 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 legacy 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

HA2TKNZZGE2TOZDCGMZWKOLDHBQWIMBSGM4TGZBYGUYGINRQHAYTINBZGYZDOZBZMZRGKNZTME3TMNBXGYYTIOBYGMYWKNLFMYYDAYY=@osu.edu


[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.
  • 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).
  • 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>

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

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

Estratto da "https://wiki.idem.garr.it/w/index.php?title=SAML-Subject-ID-Attribute&oldid=13116"