Replace Targeted ID by SAML NameID format persistent

For not boring you with too many details, we start with the checklist as first chapter.
All the explanations you find in the subsequent chapters, starting with Why a Persistent Identifier?.

Table of contents

1. No entry yet.

All SP administrators whose SP currently lists the Targeted ID (eduPersonTargetedID) attribute in the Resource Registry in section "Requested Attributes and Claims" as required or desired, should carefully process this checklist in order to prevent future interoperability issues.

Within this chapter, persistent-id refers to the persistent identifier transferred from IdP to SP either as eduPersonTargetedID attribute or as SAML NameID format persistent value.
At the SP side, persistent-id is usually configured as environment variable name to pass the persistent identifier value from the SAML SP to the web applications the SP protects.

First, find the answer to this question:

Does the persistent-id value really get used or which other identifier(s) get used?

Therefore, check your SP's configuration, the web server configuration as well as the configuration (or source code) of the web applications the SP protects.

Only check the configuration, do not yet change anything in it!

1. For a Shibboleth SP:
   1. Identify the persistent identifier's environment variable name:
      In the file /etc/shibboleth/attribute-map.xml, the id value defines an attribute's environment variable name.
      Since Shibboleth SPv2.5, persistent-id is the environment variable name defined for both alternatives, according to this default configuration from the SWITCH SP Configuration Guide:

      <!-- The eduPerson attribute version (eduPersonTargetedID, note the OID-style name): -->
      <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="persistent-id">
          <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
      </Attribute>
      
      <!-- SAML 2.0 NameID Format: -->
      <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
          <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
      </Attribute>
      

      ⇒ If your configuration uses another name than persistent-id, for the rest of this page you need to substitute it for the default name.
   2. Does the REMOTE_USER environment variable contain the persistent-id environment variable name?
      In the file /etc/shibboleth/shibboleth2.xml in the <ApplicationDefaults> and possibly in optional <ApplicationOverride> elements, check the sequence of the identifiers in the REMOTE_USER attribute. It defines the priority for the identifiers listed.
      The SP uses only the first identifier with a value to populate the REMOTE_USER environment variable.
      Since Shibboleth SPv3.0, this is the default configuration from the SWITCH SP Configuration Guide:

          REMOTE_USER="persistent-id uniqueID"
      

      If REMOTE_USER contains persistent-id, you need to check in the next step not just for persistent-id but also for occurrences of REMOTE_USER.
2. For a SimpleSAMLphp SP:
   Refer to either the official SimpleSAMLphp SP documentation or use the SimpleSAMLphp as SP documentation kindly provided by the Austrian ACOnet Identity Federation to find out which identifiers are configured in the SP.
3. For SPs using another SAML implementation:
   Refer to documentation of your SAML SP implementation to identify which identifiers are actually configured in the SP.

Now that you identified the environment variable names of the identifiers configured in your SP, check the web server configuration as well as the configuration (or source code) of the web applications protected by your SP.

1. Which environment variable names, if any, are configured in your web server to authorize access?
2. If any of your web applications store user profiles and needs to recognize returning users, check which identifiers are stored in the user profile database to identify them.
   Get persistent-id triplet values stored or do you store only values of another identifier like uniqueID or even mail?
3. BTW: Based on the attribute requirements declared in the Resource Registry, you might have detected attributes that your SP gets but no longer needs, neither your web applications. These attributes you should drop from the attribute requirements declaration in the Resource Registry since data minimisation is good practice.

If you verified, that neither REMOTE_USER nor persistent-id is in use, no longer request Targeted ID from the IdPs.

First validate your analysis by only changing the SP configuration during a maintenance window, especially if you do not have a test setup readily available to test the changes first.

1. Drop persistent-id from REMOTE_USER in the file /etc/shibboleth/shibboleth2.xml
2. In the file /etc/shibboleth/attribute-map.xml comment out the attribute mappings for eduPersonTargetedID SAML 2.0 NameID Format like this:

   <!-- The eduPerson attribute version (eduPersonTargetedID, note the OID-style name): -->
   <!--
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="persistent-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   -->
   
   <!-- SAML 2.0 NameID Format: -->
   <!--
   <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   -->
   

3. Test the syntactical correctness of the changed SP configuration with

   $ shibd -t
   

   • If successful, restart the shibd process:

     $ systemctl restart shibd
     

   • If your SP and the protected web applications do not use REMOTE_USER nor persistent-id, this modification did not change the behaviour of your SP protected web applications.
   • In case the behaviour changed, e.g. the user has no longer access to the former user profile, you must have missed one of the identifiers during the analysis phase.
     ⇒ Revert the modifications applied and start over with identifying the identifier your web applications really use.
4. Go to the Resource Registry to edit your resource entry.
   • Click on "Requested Attributes and Claims" and drop the attribute Targeted ID.
     

     
     

   • Click on "Save and continue" and submit the change for approval.
5. You are done! Your SP will no longer get persistent-id values.

If you verified, that REMOTE_USER is used, but does not include persistent-id nor the persistent-id environment variable is in use, no longer request Targeted ID from the IdPs.

First validate your analysis by only changing the SP configuration during a maintenance window, especially if you do not have a test setup readily available to test the changes first.

1. In the file /etc/shibboleth/attribute-map.xml comment out the attribute mappings for eduPersonTargetedID SAML 2.0 NameID Format like this:

   <!-- The eduPerson attribute version (eduPersonTargetedID, note the OID-style name): -->
   <!--
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="persistent-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   -->
   
   <!-- SAML 2.0 NameID Format: -->
   <!--
   <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   -->
   

2. Test the syntactical correctness of the changed SP configuration with

   $ shibd -t
   

   • If successful, restart the shibd process:

     $ systemctl restart shibd
     

   • If your SP and the protected web applications do not use persistent-id, this modification did not change the behaviour of your SP protected web applications.
   • In case the behaviour changed, e.g. the user has no longer access to the former user profile, you must have missed one of the identifiers during the analysis phase.
     ⇒ Revert the modifications applied and start over with identifying the identifier your web applications really use.
3. Go to the Resource Registry to edit your resource entry.
   • Click on "Requested Attributes and Claims" and drop the attribute Targeted ID.
     

     
     

   • Click on "Save and continue" and submit the change for approval.
4. You are done! Your SP will no longer get persistent-id values.

Note: If your SP is a busy one with many users logging in all around the clock, you should properly plan a maintenance window to apply this change, especially if you do not have a test setup readily available to test and validate the changes first.

1. In the file /etc/shibboleth/attribute-map.xml, modify the id value for the eduPersonTargetedID attribute to targeted-id and leave the id value for the SAML 2.0 NameID Format unchanged:

   <!-- The eduPerson attribute version (eduPersonTargetedID, note the OID-style name): -->
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="targeted-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   
   <!-- SAML 2.0 NameID Format: -->
   <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
       <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
   </Attribute>
   

2. In the file /etc/shibboleth/shibboleth2.xml in the <ApplicationDefaults> and possibly in optional <ApplicationOverride> elements, temporarily modify the REMOTE_USER attribute by adding targeted-id after persistent-id:

       REMOTE_USER="persistent-id targeted-id uniqueID"
   

3. Test the syntactical correctness of the changed SP configuration with

   $ shibd -t
   

   If successful, restart the shibd process:

   $ systemctl restart shibd
   

   This change did not change the behaviour of your SP protected web applications. However, it ensures, that REMOTE_USER will never carry duplicated values. Now, your SP is ready for the next steps.
4. Go to the Resource Registry to edit your resource entry.
   • Click on "Requested Attributes and Claims" and scroll down to the NameID Configuration section.
   • Click on "Show Options" and pick SAML2 persistent from the Common NameID Format pop-up list.
     

     
     

   • Click on "Save and continue" and submit the change for approval.
5. After you receive the approval notification message from the Resource Registry, wait two hours for the change to surely propagate to the IdPs.
6. Go again to the Resource Registry to edit your resource entry.
   • Click on "Requested Attributes and Claims" and drop the attribute Targeted ID.
     

     
     

   • Click on "Save and continue" and finally submit the change for approval.
7. After you receive the approval notification message from the Resource Registry, again wait two hours for the change to surely propagate to the IdPs.
   However, if your SP is interfederation enabled, you should now wait at least two days, better a week, before continuing to ensure that the IdPs loaded the updated metadata.
8. In the file /etc/shibboleth/shibboleth2.xml in the <ApplicationDefaults> and possibly in optional <ApplicationOverride> elements, revert the temporary change to the REMOTE_USER attribute by removing targeted-id:

       REMOTE_USER="persistent-id uniqueID"
   

9. Test the syntactical correctness of the changed SP configuration with

   $ shibd -t
   

   If successful, restart the shibd process:

   $ systemctl restart shibd
   

10. You are done! Your SP will now get the persistent identifier values in SAML NameID format persistent.

If you verified, that only persistent-id is in use, you need to schedule a maintenance window for your service. If not, your SP might pass duplicated persistent-id values to your web application.
This could happen since SWITCHaai IdPs reload about every hour updated metadata files as well as the attribute filter file. However, IdPs do not load them at the same time. It can take up to one hour to surely have reloaded both files.
The following changes will affect the SP entry in the metadata file but also your SP's attribute filter rule.
If your SP is interfederation enabled, IdPs from other federations do only load metadata, but not an attribute filter file. Therefore, the information these IdPs use will always be consistent.

Coordinate the maintenance window with your Home Organisation's Resource Registration Administrators, so one of them can approve your submitted change for approval quickly.
After approval, you should wait two hours before you restart your SP again.

1. Consider to drop persistent-id from the not used REMOTE_USER in the file /etc/shibboleth/shibboleth2.xml, so that the SP configuration better reflects the actual usage.
   If you changed it, test the syntactical correctness of the changed SP configuration with

   $ shibd -t
   

   This change did not change the behaviour of your SP protected web applications.
2. At the beginning of the maintenance window, stop your SP shibd process to prevent user logins:

   $ systemctl stop shibd
   

3. Go to the Resource Registry to edit your resource entry.
   • Click on "Requested Attributes and Claims" and drop the attribute Targeted ID.
     

     
     

   • Scroll down to the NameID Configuration section.
   • Click on "Show Options" and pick SAML2 persistent from the Common NameID Format pop-up list.
     

     
     

   • Click on "Save and continue" and submit the changes for approval.
4. After you receive the approval notification message from the Resource Registry, you wait two hours before you start your SP shibd process again:

   $ systemctl start shibd
   

5. You are done! Your SP will now get the persistent identifier values in SAML NameID format persistent.

The persistent identifier is a privacy preserving user identifier shared between the Identity Provider (IdP) and the Service Provider (SP). It is generated by the IdP the first time a user accesses a specific SP. It is named persistent because its value remains the same for all further sessions of the same user with the same SP.
At the IdP, the persistent identifier value is stored in a relational database, provided the Shibboleth IdP was configured according to the SWITCHaai IdP guide.
If no database is configured, the persistent identifier value is computed every time anew using a predefined salt.

The persistent identifier is a triplet with these components

<name for the identifier's source>
<name for the identifier's intended audience>
<opaque identifier for the user>

As names, the globally unique SAML EntityID values get used: For the source the IdP's EntityID, for the intended audience the SP's EntityID.

The Shibboleth SP exposes a persistent identifier value in an environment variable as a string to the web application. The SP concatenates the three components in the above listed sequence, separated by !. See this example:

https://aai-logon.switch.ch/idp/shibboleth!https://attribute-viewer.aai.switch.ch/shibboleth!RxnUFPKVdJ0Awojg1C42k53NfPk=

It is privacy preserving since for a given user, the IdP generates per SP a different persistent identifier value. Therefore, a persistent identifier value cannot be used to correlate user data, even if several SPs would aggregate their data.

Targeted ID: To complement the SAML1 standard, the Shibboleth open source SAML implementation introduced the concept of a targeted identifier. To transfer this identifier from the IdP to the SP, the eduPersonTargetedID attribute was specified as part of the eduPerson schema.
Unlike all other attributes, the eduPersonTargetedID attribute gets not transferred as simple string. It uses an XML structure with the three components introduced above.
Only few SAML SP implementations are able to decode such a structure, namely the open source Shibboleth and SimpleSAMLphp implementations.

<saml2:Attribute
    FriendlyName="eduPersonTargetedID"
    Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>
        <saml2:NameID
            Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
            NameQualifier="https://aai-logon.switch.ch/idp/shibboleth"
            SPNameQualifier="https://attribute-viewer.aai.switch.ch/shibboleth">
            RxnUFPKVdJ0Awojg1C42k53NfPk=
        </saml2:NameID>
    </saml2:AttributeValue>
</saml2:Attribute>

SAML NameID format persistent: In 2005, the SAML2 standard introduced the "Persistent Identifier" with the corresponding Name Identifier Format Identifier urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (in short SAML NameID). It exactly matches the XML structure used by the eduPersonTargetedID attribute.
The SAML NameID gets transferred as part of the SAML <Subject> element that is included in the usually encrypted SAML assertion. I.e., the SAML NameID is not part of the attribute statement.
Not all SAML SP implementations can handle the SAML NameID format persistent, but definitely more than can cope with the eduPersonTargetedID attribute.

<saml2:NameID
    Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    NameQualifier="https://aai-logon.switch.ch/idp/shibboleth"
    SPNameQualifier="https://attribute-viewer.aai.switch.ch/shibboleth"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    RxnUFPKVdJ0Awojg1C42k53NfPk=
 </saml2:NameID>

It is overdue to deprecate the use of the mainly Shibboleth specific eduPersonTargetedID attribute by the SAML2 standard method SAML NameID format persistent.
Since more SAML implementations support SAML NameID format persistent than Targeted ID, it makes sense to finally migrate to the SAML2 standard way using SAML NameID format persistent.
In addition, a future release of the Shibboleth IdP will drop support for the XML structure in the attribute resolver required for the eduPersonTargetedID attribute. It is already marked as deprecated.

All the IdPs deployed in the higher education federations today, configured to provide the eduPersonTargetedID attribute are capable to provide SAML NameID format persistent.