Enable persistent federation

For more information on persistent federation, refer to Choose persistent or transient federation.

Both integrated and standalone SAML 2.0 implementations allow you to link accounts persistently.

Before you configure persistent federation, ensure you:

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

Integrated mode

To enable persistent federation with integrated mode:

Create a journey that contains the SAML2 Authentication node.

Refer to SSO and SLO in Integrated Mode for an example.

In the NameID Format field of the SAML2 Authentication node, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

You can link accounts using different nameid formats. For example, you could use the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified value, and receive the IdP user’s e-mail address in the NameID value. The SP displays the login page to identify the local user account and persistently link the two accounts.

Save your work.
Initiate SSO by accessing a URL that calls an journey that includes the SAML2 Authentication node.

For example, https://<tenant-env-sp-fqdn>/am/XUI/#login/&realm=alpha&service=mySAML2Tree.

Standalone mode

To enable persistent federation with standalone mode:

Initiate SSO with spSSOInit.jsp or idpSSOInit.jsp JSP page, including NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent as a query parameter.

For example, to initiate SSO from the SP, access a URL similar to the following:

https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSSOInit.jsp
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&metaAlias=/sp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

To initiate SSO from PingOne Advanced Identity Cloud acting as the IdP, access a URL similar to the following:

https://<tenant-env-fqdn>/am/saml2/jsp/idpSSOInit.jsp
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&metaAlias=/idp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Test your work

Authenticate to the IdP as the user you want to persistently link.

On success, you are redirected to the SP.

If there was no login page displayed at the SP, you might have enabled auto-federation, or PingOne Advanced Identity Cloud was able to find a link between the two identities without requiring authentication at the SP.

To ensure there are no existing links, create a new identity in the IdP, and initiate SSO again, authenticating to the IdP as the new user.

Authenticate to the SP as the local user to link with.

The accounts are persistently linked, with persistent identifiers stored in the user’s profile on both the IdP and the SP.

Subsequent attempts to access the SP only requires the user authenticates to the IdP, as the identities are now permanently linked.

You can prevent the ability to persistently link accounts.

For an SP, set the Disable NameID Persistence property to true in the NameID Format section of the Assertion Content tab. For more information, refer to SP assertion content.

For an IdP, set the Disable NameID Persistence to true in the Account Mapper section of the Assertion processing tab. For more information, refer to IdP assertion processing.

Manage persistent federation

When using persistent federation, you can configure and manage the federation of the persistently linked accounts.

PingOne Advanced Identity Cloud implements the SAML 2.0 Name Identifier Management profile, which allows you to change a persistent identifier set to federate accounts, as well as terminate federation for an account.

Name identifier information from identities are stored in the sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey attributes of a user’s entry.

PingOne Advanced Identity Cloud provides a pair of JSP files for managing persistently linked accounts; idpMNIRequestInit.jsp for initiating changes from the IdP side, and spMNIRequestInit.jsp for initiating changes from the SP side.

When setting parameters in the JSPs, make sure the parameter values are correctly URL-encoded.

Table 1. idpMNIRequestInit.jsp parameters
Parameter	Description
`spEntityID`	(Required) Indicate the remote SP. Make sure you URL-encode the value. For example, specify `spEntityID=https://www.sp.com:8443/openam` as `spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam`.
`metaAlias`	(Required) Local alias for the provider, such as `metaAlias=/myRealm/idp`. This parameter takes the format `/realm-name/provider-name` as described in MetaAlias.
`requestType`	(Required) Type of manage name ID request, either `NewID` to change the ID, or `Terminate` to remove the information that links the accounts on the IdP and the SP.
`SPProvidedID`	(Required if `requestType=NewID`) Name identifier in use as described previously.
`affiliationID`	(Optional) Specify a SAML affiliation identifier.
`binding`	(Optional) Indicate which binding to use for the operation. The full, long name format is required for this parameter to work. The value must be one of the following: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` `urn:oasis:names:tc:SAML:2.0:bindings:SOAP`
`relayState`	(Optional) Specify where to redirect the user when the process is complete. Make sure you URL-encode the value. For example, `relayState=http%3A%2F%2Fforgerock.com` takes the user to `http://forgerock.com`.

Table 2. spMNIRequestInit.jsp parameters
Parameter	Description
`idpEntityID`	(Required) Indicate the remote IdP. Make sure you URL-encode the value. For example, specify `idpEntityID=https://www.idp.com:8443/openam` as `idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam`.
`metaAlias`	(Required) Specify the local alias for the provider, such as `metaAlias=/myRealm/sp`. This parameter takes the format `/realm-name/provider-name` as described in MetaAlias.
`requestType`	(Required) Type of manage name ID request, either `NewID` to change the ID, or `Terminate` to remove the information that links the accounts on the IdP and the SP.
`IDPProvidedID`	(Required if `requestType=NewID`) Name identifier in use as described above.
`affiliationID`	(Optional) Specify a SAML affiliation identifier.
`binding`	(Optional) Indicate which binding to use for the operation. The full, long name format is required for this parameter to work. The value must be one of the following: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` `urn:oasis:names:tc:SAML:2.0:bindings:SOAP`
`relayState`	(Optional) Specify where to redirect the user when the process is complete. Make sure you URL-encode the value. For example, `relayState=http%3A%2F%2Fforgerock.com` takes the user to `http://forgerock.com`.

Change federation

To change federation of persistently linked accounts:

Retrieve the name identifier value, used to manage the federation in the second step.
1. You can retrieve the name identifier value on the IdP side by checking the value of the sun-fm-saml2-nameid-infokey property.
  
  For example, if the user’s entry in the directory shows:
  sun-fm-saml2-nameid-infokey: https://<tenant-env-fqdn>/am| https://<tenant-env-sp-fqdn>/am| XyfFEsr6Vixbnt0BSqIglLFMGjR2
  Then, the name identifier on the IdP side is XyfFEsr6Vixbnt0BSqIglLFMGjR2.
2. You can retrieve the name identifier value on the SP side by checking the value of sun-fm-saml2-nameid-info.
  
  For example, if the user’s entry in the directory shows:
  sun-fm-saml2-nameid-info: https://<tenant-env-sp-fqdn>/am| https://<tenant-env-fqdn>/am| ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD| https://<tenant-env-fqdn>/am| urn:oasis:names:tc:SAML:2.0:nameid-format:persistent| 9B1OPy3m0ejv3fZYhlqxXmiGD24c| https://<tenant-env-sp-fqdn>/am| SPRole|false
  Then, the name identifier on the SP side is 9B1OPy3m0ejv3fZYhlqxXmiGD24c.
Use the identifier to initiate a change request, as in the following examples:
1. To initiate a change request from the service provider, use a URL similar to the following example:
  https://<tenant-env-sp-fqdn>/am/saml2/jsp/spMNIRequestInit.jsp ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam &metaAlias=/sp &requestType=NewID &IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2
  You can substitute am/SPMniInit for am/saml2/jsp/spMNIRequestInit.jsp.
2. To initiate a change request from the identity provider, use a URL similar to the following example:
  https://<tenant-env-fqdn>/am/saml2/jsp/idpMNIRequestInit.jsp ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam &metaAlias=/idp &requestType=NewID &SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c
  You can substitute am/IDPMniInit for am/saml2/jsp/idpMNIRequestInit.jsp

Terminate federation

PingOne Advanced Identity Cloud lets you terminate account federation, where the accounts have been linked with a persistent identifier, as described in Enable persistent federation.

The following examples work in an environment where the IdP is www.idp.example and the SP is www.sp.example.

To initiate the process of terminating account federation from the SP, access the following URL with at least the query parameters shown:

https://<tenant-env-sp-fqdn>/am/saml2/jsp/spMNIRequestInit.jsp
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&metaAlias=/sp
&requestType=Terminate

To initiate the process of terminating account federation from the IdP, access the following URL with at least the query parameters shown:

https://<tenant-env-fqdn>/am/saml2/jsp/idpMNIRequestInit.jsp
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&metaAlias=/idp
&requestType=Terminate