--- title: Persistent or transient federation description: 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. component: pingam version: 8.1 page_id: pingam:am-saml2:persistent-or-transient-federation canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/persistent-or-transient-federation.html keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Accounts"] page_aliases: ["saml2-guide:persistent-or-transient-federation.adoc"] section_ids: persistent-federation: Persistent federation enable-persistent-federation: Enable persistent federation to-manage-persistent-federation: Change persistent federation initiate_change_from_the_idp: Initiate change from the IdP initiate_change_from_the_sp: Initiate change from the SP terminate_persistent_federation: Terminate persistent federation transient-federation: Transient federation enable-transient-federation: Enable transient federation --- # 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](auto-federation.html#auto-federate-based-on-attribute). 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](saml2-configuration.html) and [Implement SSO and SLO](saml2-sso-slo.html). ### Enable persistent federation 1. If you are using integrated mode: * Create an authentication tree that contains the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8.1/saml2.html). If you haven't created one yet, find an example in [SSO in integrated mode](saml2-integrated-mode.html). * 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: ```bash 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: ```bash https://www.idp.com:8443/am/IDPMniInit ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam &metaAlias=/idp &requestType=NewID &SPProvidedID=9B1OPy3m0ejv3fZYhlqxXmiGD24c ``` > **Collapse: 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](saml2-reference.html#idp-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: ```bash 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: ```bash https://www.sp.com:8443/am/SPMniInit ?idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam &metaAlias=/sp &requestType=NewID &IDPProvidedID=XyfFEsr6Vixbnt0BSqIglLFMGjR2 ``` > **Collapse: 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](saml2-reference.html#sp-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](#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](saml2-providers-and-cots.html) and [Implement SSO and SLO](saml2-sso-slo.html). ### Enable transient federation 1. If you are using integrated mode SSO: * Create an authentication tree that contains the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/8.1/saml2.html). If you haven't created one yet, find an example in [SSO in integrated mode](saml2-integrated-mode.html). * 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.