Access Management 7.2.2

Persistent or transient federation

You can choose to permanently link identities, known as persistent federation. AM lets you configure the service provider to persistently link identities, based on an attribute value from the identity provider. When you know the user accounts on both the identity provider and the service provider 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.

In some cases, the identity provider can choose to communicate a minimum of information about an authenticated user, with no user account maintained on the service provider side. This is known as transient federation.

Transient federation can be useful when the service provider either needs no user-specific account to provide a service, or when you do not want to retain a user profile on the service provider, but instead, you make authorization decisions based on attribute values from the identity provider.

In a SAML v2.0 federation where accounts have been persistently linked, authentication is required only on the identity provider side.

Authentication is required on the service provider side, however, when the service provider is unable to map the identity in the assertion from the identity provider 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 service provider must authenticate the user for every SAML assertion received. This is because the identifier used to link the identities is transient; it does not 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.

Enable persistent federation

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

Before attempting to configure persistent federation, ensure that you have configured AM for SAML v2.0 single sign-on, created the identity and service providers, and configured a circle of trust. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

  1. If you are using integrated mode SSO with chains:

    • Go to Realms > Realm Name > Authentication > Modules, and select the module name of your SAML2 authentication module.

    • 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 chain that includes the SAML2 module.

      For example, https://www.sp.com:8443/openam/XUI/#login/&service=mySAMLChain.

  2. If you are using integrated mode with trees:

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

      If you have not created one yet, see SSO and SLO in Integrated Mode for an example.

    • 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/openam/XUI/#login/&realm=alpha&service=mySAML2Tree.

  3. If you are using standalone mode single sign-on:

    • Initiate single sign-on with either the 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 single sign-on from the service provider, access a URL similar to the following:

      https://www.sp.com:8443/openam/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 single sign-on from AM acting as the identity provider, access a URL similar to the following:

      https://www.idp.com:8443/openam/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

  4. 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 ensure there are no existing links, create a new identity in the IDP, and initiate single sign-on 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 IDP side by setting the idpDisableNameIDPersistence to true.

Enable transient federation

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

Before attempting to configure transient federation, ensure that you have configured AM for SAML v2.0, created the identity and service providers, and configured a circle of trust. You must also have configured AM to support single sign-on. For information on performing those tasks, see Deployment considerations and Implement SSO and SLO.

  1. If you are using integrated mode SSO with chains:

    • Go to Realms > Realm Name > Authentication > Modules, and then select the module name of your SAML2 authentication module.

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

    • Save your work.

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

      For example, https://www.sp.com:8443/openam/XUI/#login/&service=mySAMLChain.

  2. If you are using integrated mode SSO with chains:

    • Go to Realms > Realm Name > Authentication > Modules, and then select the module name of your SAML2 authentication module.

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

    • Save your work.

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

      For example, https://www.sp.com:8443/openam/XUI/#login/&service=mySAMLChain.

  3. If you are using integrated mode SSO with trees:

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

      If you have not created one yet, see SSO and SLO in integrated mode for an example.

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

    • Save your work.

    • Initiate single sign-on by accessing a URL that calls an authentication tree that includes the SAML v2.0 node:

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

  4. If you are using standalone mode SSO:

    • Initiate single sign-on with either the spSSOInit.jsp or idpSSOInit.jsp JSP page, including NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient as a query parameter.

      For example, to initiate single sign-on from the service provider, access a URL similar to the following:

      https://www.sp.com:8443/openam/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:transient

      To initiate single sign-on from the identity provider, access a URL similar to the following:

      https://www.idp.com:8443/openam/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:transient

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

      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 are not linked.

Federation for persistently linked accounts

The SAML v2.0 Name Identifier management profile lets you change a persistent identifier that has been set to federate accounts, and 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, in the AM admin UI, go to Configure > Global Services > SAMLv2 Service Configuration.)

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

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

idpMNIRequestInit.jsp parameters
spEntityID

(Required) Use this parameter to indicate the remote service provider. 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) 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 do not 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 identity provider and service provider.

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=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

spMNIRequestInit.jsp Parameters
idpEntityID

(Required) Use this parameter to indicate the remote identity provider. 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) 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 do not repeat the slash for the Top Level Realm, 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=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

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://www.idp.com:8443/openam|
  https://www.sp.com:8443/openam|
  XyfFEsr6Vixbnt0BSqIglLFMGjR2

    2. Then, the name identifier on the IDP side is XyfFEsr6Vixbnt0BSqIglLFMGjR2.

      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 the following:

      sun-fm-saml2-nameid-info: https://www.sp.com:8443/openam|
  https://www.idp.com:8443/openam|
  ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD|
  https://www.idp.com:8443/openam|
  urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|
  9B1OPy3m0ejv3fZYhlqxXmiGD24c|
  https://www.sp.com:8443/openam|
  SPRole|
  false

Then, the name identifier on the SP side is 9B1OPy3m0ejv3fZYhlqxXmiGD24c.

  1. 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://www.sp.com:8443/openam/saml2/jsp/spMNIRequestInit.jsp
?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&metaAlias=/sp
&requestType=NewID
&IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2

      You can substitute openam/SPMniInit for openam/saml2/jsp/spMNIRequestInit.jsp.

    2. To initiate a change request from the identity provider, use a URL similar to the following example:

      https://www.idp.com:8443/openam/saml2/jsp/idpMNIRequestInit.jsp
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&metaAlias=/idp
&requestType=NewID
&SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c

      You can substitute openam/IDPMniInit for openam/saml2/jsp/idpMNIRequestInit.jsp

Terminate federation of persistently linked accounts

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

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

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

    https://www.sp.com:8443/openam/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 identity provider, access the following URL with at least the query parameters shown:

    https://www.idp.com:8443/openam/saml2/jsp/idpMNIRequestInit.jsp
?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&metaAlias=/idp
&requestType=Terminate