PingOne Advanced Identity Cloud

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 Advanced Identity Cloud for SAML 2.0.

  • Create the IdP.

    • If Advanced Identity Cloud is the IdP, use the Advanced Identity Cloud admin console with application management.

  • Create SPs.

  • Configure a circle of trust (CoT).

  • Configure Advanced Identity Cloud to support SSO.

Integrated mode

To enable persistent federation with integrated mode:

  1. Create a journey that contains the SAML2 Authentication node.

    Find an example in SSO in integrated mode.

  2. 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.

  3. Save your work.

  4. 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:

  1. Initiate SSO with spssoinit or idpssoinit URLs, 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/spssoinit
?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 Advanced Identity Cloud acting as the IdP, access a URL similar to the following:

    https://<tenant-env-fqdn>/am/idpssoinit
?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

  1. 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 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.

  2. 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 require that 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.

Advanced Identity Cloud implements the SAML 2.0 Name Identifier Management profile. This lets you change a persistent identifier set to federate accounts and terminate federation for an account.

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

Advanced Identity Cloud provides two endpoints for managing persistently linked accounts:

  • IDPMniInit for initiating changes from the IdP side

    IDPMniInit 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/am as spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam.

    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%2Fpingidentity.com takes the user to http://pingidentity.com.

  • SPMniInit for initiating changes from the SP side

    SPMniInit 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/am as idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam.

    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%2Fpingidentity.com takes the user to http://pingidentity.com.

Change federation

To change federation of persistently linked accounts, you must to get the name identifier value and initiate a change request using either the IDPMniInit or SPMniInit endpoint.

Initiate change from the SP

  1. Get 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

    The name identifier on the IdP side is XyfFEsr6Vixbnt0BSqIglLFMGjR2.

  2. Call the /SPMniInit endpoint to initiate a change request from the SP. Make sure you URL-encode the parameters. For example:

    https://<tenant-env-sp-fqdn>/am/SPMniInit
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&metaAlias=/sp
&requestType=NewID
&IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2

Initiate change from the IdP

  1. Get 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 the following:

      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

    The name identifier on the SP side is 9B1OPy3m0ejv3fZYhlqxXmiGD24c.

  2. Call the /IDPMniInit endpoint to initiate a change request from the SP. Make sure you URL-encode the parameters. For example:

    https://<tenant-env-fqdn>/am/am/IDPMniInit
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&metaAlias=/idp
&requestType=NewID
&SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c

Terminate federation

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

Initiate termination from the SP

Access the following URL with at least the query parameters shown.

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

Initiate termination from the IdP

Access the following URL with at least the query parameters shown:

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