PingAM

Persistent or transient federation

You can choose to permanently link identities, known as persistent federation. AM lets you configure the SP to persistently link identities, based on an attribute value from the IdP. When you know the user accounts on both the IdP and the SP share a common attribute value, such as an email address or another unique user identifier, you can use this method to link accounts without user interaction. See Link identities automatically based on an attribute value.

Sometimes the IdP can choose to communicate a minimum of information about an authenticated user, with no user account maintained on the SP side. This is known as transient federation.

Transient federation can be useful when the SP either needs no user-specific account to provide a service, or when you don’t want to retain a user profile on the SP, but instead, you make authorization decisions based on attribute values from the IdP.

In a SAML 2.0 federation where accounts have been persistently linked, authentication is required only on the IdP side.

Authentication is required on the SP side, however, when the SP is unable to map the identity in the assertion from the IdP to a local user account.

This can happen the first time accounts are linked, for example. After which, the persistent identifier establishes the mapping.

Authenticating to the SP may also be required when transient federation is used when linking identities. The SP must authenticate the user for every SAML assertion received. This is because the identifier used to link the identities is transient; it doesn’t provide a repeatable, durable means to link the identities.

You can prevent the ability to persistently link accounts on the SP side by setting the spDoNotWriteFederationInfo property to true, and on the IdP side by setting the idpDisableNameIDPersistence to true.

Persistent federation

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

Before attempting to configure persistent federation, make sure that you have configured AM for SAML 2.0 SSO, created the IdP and SPs, and configured a circle of trust.

Find information about these tasks in Deployment considerations and Implement SSO and SLO.

Enable persistent federation

  1. If you are using integrated mode:

    • Create an authentication tree that contains the SAML2 Authentication node.

      If you haven’t created one yet, find an example in SSO in integrated mode.

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

      You can also link accounts together 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 would display the login page to identify the local user account and persistently link them.

    • Save your work.

    • Initiate single sign-on by accessing a URL that calls an authentication tree that includes the SAML2 node.

      For example, https://www.sp.com:8443/am/XUI/#login/&realm=alpha&service=mySAML2Tree.

  2. If you are using standalone mode SSO:

    • Initiate SSO with either the 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://www.sp.com:8443/am/spssoinit
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam
&metaAlias=/sp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

      To initiate SSO from AM acting as the IdP, access a URL similar to the following:

      https://www.idp.com:8443/am/idpssoinit
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&metaAlias=/idp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

  3. To test your work:

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

      On success, you will be redirected to the SP.

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

      To make sure 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 will 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 on the SP side by setting the spDoNotWriteFederationInfo property to true, and on the IdPside by setting the idpDisableNameIDPersistence to true.

Change persistent federation

The SAML 2.0 Name Identifier management profile lets you change a persistent identifier that federates accounts and lets you terminate federation for an account.

When user accounts are stored in an LDAP directory server, name identifier information is stored on the sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey attributes of a user’s entry.

To configure these attribute types, go to Configure > Global Services > SAMLv2 Service Configuration in the AM admin UI.

AM provides two endpoints for managing persistently linked accounts; IDPMniInit for initiating changes from the IdP side, and SPMniInit for initiating changes from the SP side.

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://www.sp.com:8443/am|
  https://www.idp.com:8443/am|
  ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD|
  https://www.idp.com:8443/am|
  urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|
  9B1OPy3m0ejv3fZYhlqxXmiGD24c|
  https://www.sp.com:8443/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://www.idp.com:8443/am/IDPMniInit
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&metaAlias=/idp
&requestType=NewID
&SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c
    IDPMniInit parameters
    spEntityID

    (Required) Use this parameter to 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) Use this parameter to specify the local alias for the provider; such as, metaAlias=/myRealm/idp. This parameter takes the format /realm-name/provider-name as described in MetaAlias.

    You don’t repeat the slash for the Top Level Realm, for example, metaAlias=/idp.

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

    SPProvidedID

    (Required if requestType=NewID) Name identifier in use as described above.

    affiliationID

    (Optional) Use this parameter to specify a SAML affiliation identifier.

    binding

    (Optional) Use this parameter to 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) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value. For example, relayState=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.

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://www.idp.com:8443/am|
  https://www.sp.com:8443/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://www.sp.com:8443/am/SPMniInit
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam
&metaAlias=/sp
&requestType=NewID
&IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2
    SPMniInit parameters
    idpEntityID

    (Required) Use this parameter to 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) Use this parameter to 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.

    You don’t repeat the slash for the Top Level Realm, for exmaple, metaAlias=/sp.

    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 identity provider and service provider.

    IDPProvidedID

    (Required if requestType=NewID) Name identifier in use as described above.

    affiliationID

    (Optional) Use this parameter to specify a SAML affiliation identifier.

    binding

    (Optional) Use this parameter to 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) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value. For example, relayState=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.

Terminate persistent federation

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

The examples below work in an environment where the IdP is www.idp.example and the SP is www.sp.example. Both providers have deployed AM on port 8443 under deployment URI /am.

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

    https://www.sp.com:8443/am/SPMniRedirect
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam
&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://www.idp.com:8443/am/IDPMniRedirect
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&metaAlias=/idp
&requestType=Terminate

Transient federation

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

Before you configure transient federation, you must do the following:

  • Configure AM for SAML 2.0

  • Create the IdP and SPs

  • Configure a circle of trust

  • Configure AM to support SSO

Find information about these tasks in Set up IdPs and SPs in a CoT and Implement SSO and SLO.

Enable transient federation

  1. If you are using integrated mode SSO:

    • Create an authentication tree that contains the SAML2 Authentication node.

      If you haven’t created one yet, find an example in SSO in integrated mode.

    • In the NameID Format field, specify the value urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

    • Save your work.

    • Initiate SSO by accessing a URL that calls an authentication tree that includes the SAML 2.0 node:

      For example, https://www.sp.com:8443/am/XUI/#login/&realm=alpha&service=mySAMLTree.

  2. If you are using standalone mode SSO:

    • Initiate SSO with either the /spssoinit or /idpssoinit URLs, including NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient as a query parameter.

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

      https://www.sp.com:8443/am/spssoinit
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam
&metaAlias=/sp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient

      To initiate SSO from the IdP, access a URL similar to the following:

      https://www.idp.com:8443/am/idpssoinit
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&metaAlias=/idp
&NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  3. To test your work:

    • Authenticate to the IdP as the user you want to temporarily link.

      On success, you will be redirected to the SP.

    • Authenticate to the SP as the local user.

      The accounts are only linked temporarily for the duration of the session. Once the user logs out, the accounts are no longer linked.

      Nothing is written in the user’s profile on either the IdP and the SP.

      Subsequent attempts to access the SP will require that the user authenticates to the IdP AND the SP (assuming no existing session exists), as the identities aren’t linked.