Link identities automatically with auto-federation

Before linking identities, you must first choose between persistent or transient federation.

Identity Cloud lets you configure the SP to link identities automatically, based on an attribute value in the assertion returned from the IDP. This process is called auto-federation.

When the identities on both the IDP and the SP share a common attribute value, such as an email address or other unique user identifier, you can configure Identity Cloud to map the attributes to each other and link identities. The user doesn’t authenticate to the SP.

Link identities automatically based on an attribute value

You can automatically link identities based on an attribute value that is the same in both the IDP and the SP.

Before you configure auto-federation, ensure that you:

Configure Identity Cloud for SAML 2.0.
Create the IDP. If Identity Cloud is the IDP, use the Identity Cloud admin UI with application management.
Create SPs.
Configure a circle of trust (CoT).
Configure Identity Cloud to support SSO.

For an overview of the tasks listed above, refer to Deployment considerations.

Perform the following steps on the hosted IDP(s), and again on the hosted SP(s):

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers, and click on the name of the hosted provider.

Identity Cloud only displays the configuration of a single role.

To switch between an IDP and SP configuration for a given provider, select the role to view:

On the hosted IDP:

Go to the Assertion Processing tab.

Review the Attribute Map configuration. If the attributes you want to use to link the accounts on the IDP and the SP are not in the map already, add them.

The IDP sends these attributes in the assertion, and the SP maps them using its own attribute map.

The default IDP mapping implementation lets you add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes ("), as in the following example:

Example of Static Attribute Mapping. Notice that the static value is enclosed in double quotes.

Save your work.

On the hosted SP:
- Go to the Assertion Processing tab.
- Review the Attribute Map configuration, and ensure that the attribute mappings you created on the IDP are represented in the map.
  Tips to configure the attribute map on the SP
  The value of Key is a SAML attribute sent in an assertion. The value of Value is a property in the user’s session or an attribute of the user’s profile.
  
  By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during auto-federation and the identity doesn’t exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.
  
  The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.
  
  Remove the special mapping and add key pairs to the map if:
  
  During auto-federation the attributes in the IDP and SP’s identity stores do not match.
  
  You need control over the names of the session properties.
  
  You need control over which attributes the SP should map, because the IDP adds too many to the assertion.
  
  For example, if the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.
- Enable auto-federation. In the Attribute property, enter the SAML attribute name that the SP will use to link accounts, as configured in the Attribute Map.
- Save your work.
To test your work, initiate SSO; for example, as described in IDP-Initiated SSO JSP.

Authenticate to the IDP as an existing user. Attempt to access the SP, and you will notice that the user has a session, and can access their profile page on the SP without having to authenticate again.