--- title: Enable persistent federation description: Both integrated and standalone SAML 2.0 implementations allow you to link accounts persistently. component: pingoneaic page_id: pingoneaic:am-saml2:enable-persistent-federation canonical_url: https://docs.pingidentity.com/pingoneaic/am-saml2/enable-persistent-federation.html page_aliases: ["saml2-guide:persistent-federation.adoc", "saml2-guide:enable-persistent-federation.adoc"] section_ids: integrated_mode: Integrated mode standalone_mode: Standalone mode test_your_work: Test your work manage-persistent-federation: Manage persistent federation change-federation: Change federation initiate_change_from_the_sp: Initiate change from the SP initiate_change_from_the_idp: Initiate change from the IdP terminate_federation: Terminate federation initiate_termination_from_the_sp: Initiate termination from the SP initiate_termination_from_the_idp: Initiate termination from the IdP --- # Enable persistent federation | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | For more information on persistent federation, refer to [Choose persistent or transient federation](choose-persistent-or-transient-federation.html). | Both [integrated and standalone](saml2-sso-slo.html) 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](saml2-providers-and-cots.html#create-hosted-providers). * If Advanced Identity Cloud is the IdP, use the Advanced Identity Cloud admin console with [application management](../app-management/register-a-custom-application.html#custom-saml-app-setup-sso). * Create [SPs](saml2-providers-and-cots.html#create-hosted-providers). * Configure a [circle of trust (CoT)](saml2-providers-and-cots.html#create-cot). * Configure Advanced Identity Cloud to support [SSO](saml2-sso-slo.html). ## Integrated mode To enable persistent federation with [integrated mode](saml2-sso-slo.html): 1. Create a journey that contains the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/latest/saml2.html). Find an example in [SSO in integrated mode](saml2-integrated-mode.html). 2. In the NameID Format field of the [SAML2 Authentication node](https://docs.pingidentity.com/auth-node-ref/latest/saml2.html), 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](https://docs.pingidentity.com/auth-node-ref/latest/saml2.html). For example, `https:///am/XUI/#login/&realm=alpha&service=mySAML2Tree`. ## Standalone mode To enable persistent federation with [standalone mode](saml2-sso-slo.html): 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:///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:///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](saml2-reference.html#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](saml2-reference.html#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 > **Collapse: 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](saml2-reference.html#idp-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 > **Collapse: 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](saml2-reference.html#sp-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:///am| https:///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:///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:///am| https:///am| ATo9TSA9Y2Ln7DDrAdO3HFfH5jKD| https:///am| urn:oasis:names:tc:SAML:2.0:nameid-format:persistent| 9B1OPy3m0ejv3fZYhlqxXmiGD24c| https:///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:///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](enable-persistent-federation.html). #### Initiate termination from the SP Access the following URL with at least the query parameters shown. ``` https:///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:///am/IDPMniInit ?spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam &metaAlias=/idp &requestType=Terminate ```