--- title: Implement a SAML 2.0 gateway by using Secure Attribute Exchange description: Most deployments can rely on AM to handle authentication and provide identity assertions. AM supports a wide variety of authentication scenarios out of the box, but AM also makes it possible to add custom authentication modules. Furthermore, IG lets you integrate legacy systems into your access management deployment. component: pingam version: 7.3 page_id: pingam:saml2-guide:saml2-sae canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/saml2-sae.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Encryption"] section_ids: sae-install-prerequisites: Install the SAE samples sae-security-prerequisites: Prepare to secure SAE communications sae-secure-idp: Secure the identity provider side sae-secure-sp: Secure the service provider side sae-trying-it-out: Try it out --- # Implement a SAML 2.0 gateway by using Secure Attribute Exchange Most deployments can rely on AM to handle authentication and provide identity assertions. AM supports a wide variety of authentication scenarios out of the box, but AM also makes it possible to add custom authentication modules. Furthermore, IG lets you integrate legacy systems into your access management deployment. In a deployment where you need AM to act as a SAML 2.0 gateway to a legacy application that serves as an identity provider, you can use AM Secure Attribute Exchange (SAE). On the identity provider side, SAE lets AM retrieve the information needed to create assertions from an external authentication service, bypassing AM authentication and trusting the external service as the authoritative source of authentication. On the service provider side, SAE lets AM securely provide attributes to an application that makes its own policy decision based on the attributes rather than rely on AM for the policy decision. ![External applications use SAE to communicate with AM providers. The providers in turn use SAML 2.0 to communicate with other providers.](_images/sae.png) When you use SAE on the identity provider side, an external application acts as the authoritative source of authentication. After a user authenticates successfully, the application tells AM to create a session by sending a secure HTTP GET or POST to AM that asserts the identity of the user. AM processes the assertion to create a session for the user. If the user is already authenticated and comes back to access the application, the application sends a secure HTTP POST to AM to assert both the user's identity and also any necessary attributes related to the user. AM processes the assertion to create the session for the user and populate the attributes in the user's session. When the user logs out, the external authentication application can initiate single logout from the identity provider AM server by sending the `sun.cmd=logout` attribute to AM using SAE. On the service provider side, AM communicates using SAML 2.0 with AM on the identity provider side. AM can use SAE to transmit attributes to an application through a secure HTTP POST. SAE relies either on shared keys and symmetric encryption, or on public and private keys and asymmetric encryption to protect attributes communicated between AM and external applications. AM ships with sample JSPs that demonstrate secure attribute exchange. To try the sample, you must set up an AM circle of trust to include an identity provider and a service provider, install the SDK sample web application on each provider, and then configure the providers appropriately as described in this page to secure communications with the sample SAE applications on both the identity provider and service provider sides. ## Install the SAE samples Set up an AM server as an identity provider, and another as a service provider, connecting the two in a circle of trust called `samplesaml2cot`. Configure both the hosted providers and also the remote providers as described in [Configure IdPs, SPs, and CoTs](saml2-providers-and-cots.html). This chapter assumes you set up the hosted identity provider at `https://www.idp.com:8443/openam` and the hosted service provider at `https://www.sp.com:8443/openam`. Make sure federation is working before you add secure attribute exchange applications that rely on functioning SAML 2.0 communications between the providers. The SAE samples are not delivered with PingAM. Instead, you find them with the client SDK samples in `openam-examples/openam-example-clientsdk-war` folder of the `openam-public` repo. The SAE samples are under `/saml2/sae` where you install the samples. `saeIDPApp.jsp` is the identity provider side external application. `saeSPApp.jsp` is the service provider side external application. ## Prepare to secure SAE communications In order for SAE to be secure, you must both set up a trust relationship between the application on the identity provider side and the AM server acting as identity provider, and sets up a trust relationship between the application on the service provider side and the AM server acting as the service provider. These trust relationships can be based on a shared secret and symmetric encryption, or on public and private key pairs and asymmetric encryption. The trust relationships on either side are independent. For example, you can use a shared secret on the identity provider side and certificates on the service provider side if you chose. When using symmetric encryption, you must define a shared secret string used both for the application and the provider. The sample uses `secret12` as the shared secret. To simplify configuration, the sample uses the same shared secret, and thus symmetric encryption, for both trust relationships. When using symmetric encryption, you must also use the encoded version of your shared secret. To get the encoded version of a shared secret string, use the `encode.jsp` page on the provider, as in `https://www.idp.com:8443/openam/encode.jsp` and `https://www.sp.com:8443/openam/encode.jsp`. An encoded version of `secret12` looks something like `AQICEcFhDWmb6sVmMuCJuVh43306HVacDte9`. When using asymmetric encryption, you must obtain a public-private key pair for the application, and store the keys in a keystore on the application side. Also store the public key from AM which is acting as the provider in the application's keystore. Make note of the certificate aliases for your application's private key, and for AM's public key. Also note the path to the keystore for your application, the keystore password, and the private key password. ## Secure the identity provider side This configuration uses the default sample settings with a shared secret of `secret12`, without encryption of the attributes: 1. Log in as `amAdmin` to the AM server console where you set up the hosted identity provider (IdP). 2. The sample includes a `branch` attribute not found in user profiles by default. Therefore, under Realms > *Realm Name* > Authentication > Settings > User Profile, set User Profile to `Ignored`, and save your work. 3. Under Realms > *Realm Name* > Applications > Federation > Entity Providers, select the name of the hosted IdP to access the IDP configuration: * Under Assertion Processing > Attribute Mapper, add both `mail=mail` and `branch=branch` to the attribute map, and save your work. * Under Advanced > SAE Configuration, make sure the IDP URL reflects an endpoint on the IDP such as `https://www.idp.com:8443/openam/idpsaehandler/metaAlias/idp`, and save your work. * Also under Advanced > SAE Configuration > Application Security Configuration, add the URL value for the kind of encryption you are using, and save your work. When using the defaults, the value is something like `url=https://www.idp.com:8443/samples/saml2/sae/saeIDPApp.jsp|type=symmetric|secret=encoded-secret`, where the AM SDK sample web application is deployed on the IDP side with context root `/samples` and the *encoded-secret* is something like `AQICEcFhDWmb6sVmMuCJuVh43306HVacDte9`. If you use a different mechanism to secure the communications between the SAE application and the provider, read the online help in the console to see how to construct your URL value. 4. Under Realms > *Realm Name* > Applications > Federation > Entity Providers, select the name of the remote SP to access the SP configuration on the IDP side: * Under Assertion Processing > Attribute Mapper, add both `mail=mail` and `branch=branch` to the attribute map, and save your work. * Under Advanced > SAE Configuration, make sure the SP URL reflects an endpoint on the SP, such as `https://www.sp.com:8443/openam/spsaehandler/metaAlias/sp`, and save your work. * Also under Advanced > SAE Configuration, add the URL to the sample SAE application as the SP Logout URL, such as `https://www.sp.com:8443/samples/saml2/sae/saeSPApp.jsp`, and save your work. ## Secure the service provider side This configuration uses the default sample setting of symmetric encryption, with a shared secret of `secret12`. Login as `amAdmin` to the AM server console where you set up the hosted service provider (SP): 1. The sample includes a `branch` attribute not found in user profiles by default. Therefore, under Realms > *Realm Name* > Authentication > Settings > User Profile, set User Profile to `Ignored`, and save your work. 2. Under Realms > *Realm Name* > Applications > Federation > Entity Providers, select the name of the hosted SP to access the SP configuration: * Under Assertion Processing > Attribute Mapper, add both `mail=mail` and `branch=branch` to the attribute map, and save your work. * Also under Assertion Processing > Attribute Mapper > Auto Federation, select Enabled, set the Attribute to `mail`, and save your work. * Under Advanced > SAE Configuration, make sure the SP URL reflects an endpoint on the SP such as `https://www.sp.com:8443/openam/spsaehandler/metaAlias/sp`, and save your work. * Furthermore, under Advanced > SAE Configuration, add the URL to the sample SAE application as the SP Logout URL such as `https://www.sp.com:8443/samples/saml2/sae/saeSPApp.jsp`, and save your work. * Also under Advanced > SAE Configuration > Application Security Configuration, add the URL value for the kind of encryption you are using, and save your work. When using the defaults, the value is something like `url=https://www.sp.com:8443/samples/saml2/sae/saeSPApp.jsp|type=symmetric|secret=encoded-secret`, where the AM SDK sample web application is deployed on the IDP side with context root `/samples` and the *encoded-secret* is something like `AQICkX24RbZboAVgr2FG1kWoqRv1zM2a6KEH`. If you use a different mechanism to secure the communications between the SAE application and the provider, read the online help in the console to see how to construct your URL value. ## Try it out After completing the setup described above, go to the IDP-side SAE application; for example, at `https://www.idp.com:8443/samples/saml2/sae/saeIDPApp.jsp`. Make sure you set the `SP App URL` and `SAE URL on IDP end` to fit your configuration. For example, if you used the settings above, use the following values: * SP App URL `https://www.sp.com:8443/samples/saml2/sae/saeSPApp.jsp` * SAE URL on IDP end `https://www.idp.com:8443/openam/idpsaehandler/metaAlias/idp` Check the settings, and select Generate URL to open the Secure Attributes Exchange IDP APP SAMPLE page. Select the `ssourl` link to start the exchange. The resulting web page shows the attributes exchanged, including the mail and branch values used. The text of that page is something like the following: ```none SAE SP APP SAMPLE Secure Attrs : mail testuser@foo.com sun.idpentityid https://www.idp.com:8443/openam sun.spentityid https://www.sp.com:8443/openam branch mainbranch sun.authlevel 0 ```