PersistentNameIDGenerationConfiguration
Overview
SAML 2.0 (but not 1.x) defines a kind of NameID called a "persistent" identifier, with a Format of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
The term "persistent" refers to the fact that it's not a per-session identifier, but a stable value; in addition, SAML persistent identifiers have very particular properties, notably they're intended to be opaque and "pairwise". The latter means that for the most part every SP receives a different value for the same user. The term "pairwise" is the more typical way of describing this whole concept today, so the Format constant is unfortunate and confusing.
You should consider carefully whether this kind of identifier meets your needs. They can be difficult to deal with, they work very poorly with a wide variety of applications, and they are often more trouble than they're worth. Be cautious, and don't commit to supporting something you don't want to have to support.
There were some internal code changes in V4 but the configuration is designed to be backward-compatible. The most significant change is that a public PairwiseIdStore interface now exists to support third party extension of the way these values are produced and managed if it becomes necessary.
The IdP has a couple of built-in implementations of this interface (called "strategies" in the configuration) to produce this kind of identifier. The strategy used is controlled with the idp.persistentId.generator property in saml-nameid.properties.
It's come to light that at least some (perhaps many, or even most) applications do not support case-sensitive handling of identifiers. This SAML format is explicitly defined to be case-sensitive, but it is much, much wiser not to rely on that. Older versions of the software generate identifiers with the Base64 encoding and this is much less safe, so if you're not already supporting identifiers produced by them, you would be wise to generate the values using a Base32 encoding, which is designed to support case-insensitive applications. New installs include a property explicitly set to produce Base32 values, but upgrades of older configurations will continue to use Base64 for compatibility reasons.
Enabling the Generator
To enable either approach, you will need to uncomment the generator bean in saml-nameid.xml for SAML 2 once you set the appropriate properties highlighted below.
SAML 2.0 Persistent NameID Generator
<util:list id="shibboleth.SAML2NameIDGenerators">
<ref bean="shibboleth.SAML2TransientGenerator" />
<ref bean="shibboleth.SAML2PersistentGenerator" />
</util:list>
There is no equivalent SAML 1 bean, as this is a SAML 2-only feature.
Supported Strategies
Reference