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:

Integrated mode

To enable persistent federation with integrated mode:

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

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

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

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

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.

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:

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

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

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.

  1. 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
  2. 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
Copyright © 2010-2024 ForgeRock, all rights reserved.