Implementing a SAML v2.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 v2.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 participate in federation.

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 v2.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 chapter to secure communications with the sample SAE applications on both the identity provider and service provider sides.

Installing 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 Configuring IDPs, SPs, and CoTs. 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 v2.0 communications between the providers.

For access to the SAE samples, contact info@forgerock.com. The SAE samples are found 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.

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

Securing 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 then 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 then 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 then save your work.

    • Also under Advanced > SAE Configuration > Application Security Configuration, add the URL value for the kind of encryption you are using, and then 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 then 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 then 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 then save your work.

Securing 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 then 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 then save your work.

    • Also under Assertion Processing > Attribute Mapper > Auto Federation, select Enabled, set the Attribute to mail, and then 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 then 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 then save your work.

    • Also under Advanced > SAE Configuration > Application Security Configuration, add the URL value for the kind of encryption you are using, and then 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.

Trying 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 at least the "SP App URL" and "SAE URL on IDP end" to fit your configuration. For example if you used the settings above then 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 then select Generate URL to open the Secure Attributes Exchange IDP APP SAMPLE page.

Select the ssourl link in the page 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: 

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
Read a different version of :