Guide to working with SAML v1.x. ForgeRock® Access Management provides authentication, authorization, entitlement and federation software.

Trusted partners should ask you for a Site ID. AM generates a SAML v1.x Site ID value at configuration time. This Site ID value corresponds to the server. To find this in the AM console, see Federation > SAML 1.x Configuration > Local Site Properties > Site Identifiers, and then click your server URL.

If you have multiple servers in an AM site set up behind a load balancer, you can generate a Site ID, and then use it for all the servers in your site.

• Generate a Site ID for your site, using the primary site URL.

  This example is for an asserting party where the site load balancer host is ap.example.net. The command is bundled with AM server, shown with lines folded to fit on the printed page:

  $ cd /path/to/tomcat/webapps/openam/WEB-INF/lib/
  $ java \
       -cp forgerock-util-22.0.0.jar:openam-shared-6.5.5.jar:\
       openam-federation-library-6.5.5.jar com.sun.identity.saml.common.SAMLSiteID \
       https://ap.example.net/openam
  9BAg4UmVS6IbjccsSj9gAFYGO9Y=

1. See "Configuring Secrets, Certificates, and Keys" in the Setup and Maintenance Guide for instructions on handling your own key pairs.

   For specific instructions on changing signing keys, see "Changing Default Key Aliases" in the Setup and Maintenance Guide.

2. If necessary, share signing certificates with trusted partners.

3. Import public key certificates shared by trusted partners into your AM keystore.

Using the configuration information you have gathered complete the following steps:

1. Log in to the AM console as administrator, amadmin, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click Local Site Properties.

2. If the target specifier query string parameter is something other than the standard default TARGET, set it in the Target Specifier field.

3. If instead of the default server Site Identifier, you use a Site Identifier for the AM Site, click New in the Site Identifiers table, and then add the information for the AM Site, including the Site ID that you generated.

4. Target URLs let you configure URLs for which HTTP POST is always used.

   When the TARGET specified matches a URL in the Target URLs list, then the asserting party sends the response to the relying party by HTTP POST of an auto-submitting form returned to the browser.

5. If necessary, set the Default Protocol Version.

6. In the Assertion section, change the values if necessary.

   Remove Assertion: Yes means that assertions are deleted from memory after they are used, rather than deleted only when they expire.

7. In the Artifact section, change the values if necessary.

8. In the Signing section, for an asserting party using the HTTP POST profile, check at least Sign SAML Assertion.

   By default AM signs messages using the certificate with alias test.

   Check other options as required by your trusted partners.

9. In the Attribute Query section, if relying parties issue attribute queries, then set the default list of profile attributes to return.

10. In the NameID Format section, map SAML NameID formats to local AM user profile attributes.

    This allows AM to map a remote user to a local user profile.

11. In the Attribute Map section, if the parties exchange attributes, then map the SAML attributes requested by relying parties to local AM user profile attributes.

12. Save your work.

Using the configuration information you have gathered complete the following steps.

1. Log in to the AM console as administrator, amadmin, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click Local Site Properties.

2. If the target specifier query string parameter is something other than the standard default TARGET, set it in the Target Specifier field.

3. If instead of the default server Site Identifier, you use a Site Identifier for the AM Site, click New in the Site Identifiers table, and then add the information for the AM Site, including the Site ID that you generated.

4. Ignore the Target URLs table for a relying party.

5. If necessary, set the Default Protocol Version.

6. In the Assertion section, change the values if necessary.

7. In the Artifact section, change the values if necessary.

8. Ignore the Signing section for relying parties, unless trusted partners require that your site signs SAML requests.

   By default AM signs messages using the certificate with alias test.

9. Ignore the Attribute Query section for relying parties.

10. In the NameID Format section, map SAML NameID formats to local AM user profile attributes.

    This allows AM to map a remote user to a local user profile when not all the partners are using AM user IDs.

11. In the Attribute Map section, if the parties exchange attributes, then map the SAML attributes requested by relying parties to local AM user profile attributes.

12. Save your work.

The AM console refers to the relying party as the Destination, because the relying party's site is the destination site:

1. Log in to the AM console as administrator, amadmin, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click New in the Trusted Partners table.

2. Under Destination, select the SAML profiles used with the relying party.

3. In the Common Settings section, set at least a name for the partner configuration, enter the partner's Site ID as the Source ID, and specify the fully qualified domain, optionally with the port number, of the relying party in the Target field. The value in the target field is matched to TARGET parameter values, so it should correspond to the real domain (and optionally port number) in the URLs of resources to access at the relying party's site.

   Optionally set a custom site attribute mapper, a custom name identifier mapper, and the SAML Version to use with the partner.

   You must also set one or more values in the host list for the partner to identify all hosts from the partner site that can send requests. AM rejects SAML requests from hosts not specified in this list.

4. In the Destination section, if the SAML Artifact profile is used with the relying party, set the SAML URL to the relying party's endpoint that receives the artifact and contacts your asserting party.

   If the SAML POST profile is used with the relying party, set the Post URL to the relying party's endpoint that consumes the assertion in the HTTP POST form data and redirects the user's browser to the target at the relying party's site.

   If the relying party makes SAML SOAP query requests, optionally set custom attribute or action mappers.

   If the relying party signs requests, then either requests include the certificate for the signing key in the KeyInfo element, or AM must find the signing certificate elsewhere. If the relying party provides the signing certificate separately, import the signing certificate into AM's default keystore file, and set the alias for the signing certificate here in the configuration. For more information about AM's default keystore, see "Configuring Secrets, Certificates, and Keys" in the Setup and Maintenance Guide.

   Set the issuer to a host:port combination corresponding to the relying party server issuing the requests.

5. Save your work.

The AM console refers to the asserting party as the Source, because the asserting party's site is the source site:

1. Log in to the AM console as administrator, amadmin, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click New in the Trusted Partners table.

2. Under Source, select the SAML profiles used with the asserting party.

3. In the Common Settings section, set at least a name for the partner configuration and enter the partner's Site ID as the Source ID.

   Optionally set a custom account mapper. By default AM maps accounts based on the NameID format configuration for your site.

   If the asserting party signs assertions (or other messages) and you have imported the signing certificate into AM's keystore (also used as a trust store), then enter the signing certificate alias. If instead the asserting party includes the signing certificate in the KeyInfo element of signed messages, then you can leave the alias blank.

4. In the Source section, if the SAML Artifact profile is used with the asserting party, set the SOAP URL to the asserting party endpoint that responds to requests such as https://ap.example.net/openam/SAMLSOAPReceiver.

   If the asserting party requires authentication to the SOAP URL, then configure the settings appropriately.

   If the SOAP URL is accessed over HTTP, choose None or Basic. If the SOAP URL is accessed over HTTPS, choose SSL/TLS or SSL/TLS with Basic.

   Basic means HTTP Basic authentication (with username and password). For HTTP Basic authentication, the authentication at this level is performed by the application server container, not AM. Therefore if the asserting party runs AM and wants to enforce HTTP Basic authentication, the asserting party administrator must set up the container to handle HTTP Basic authentication for the SOAP URL.

   Set the SAML Version as necessary.

   If the SAML POST profile is used with the asserting party, set the Issuer to the issuer name, such as a host:port combination.

5. Save your work.

1. Install two separate servers, one to act as asserting party, the other to act as relying party.

   How you do this in practice is up to you.

   You can, for example, set up two separate AM servers on a single host by adding aliases for the hosts in your hosts file, and by using separate containers that listen on different ports.

   For example, if your host is a laptop, you can add the aliases to the loopback address as in the following example line from an /etc/hosts file.

   127.0.0.1    localhost ap.example.net rp.example.com

   Then, run one application server to listen on port 8080, and another to listen on port 9080.

   Deploy and configure AM server with the default configuration at http://ap.example.net:8080/ap for the asserting party and at http://rp.example.com:9080/rp for the relying party. This allows you to use the default configuration for both servers.

   See the Installation Guide for instructions.

   The procedures in this section use those example URLs to represent the AM servers acting as asserting and relying parties.

2. On the asserting party server, login to the AM console as administrator, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click Local Site Properties.

   Click the server's instance ID in the Site Identifiers table.

   Record the asserting party Site ID for later use.

3. On the relying party server, login to the AM console as administrator, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click Local Site Properties.

   Click the server's instance ID in the Site Identifiers table.

   Record the asserting party Site ID for later use.

Follow these steps to configure the asserting party AM server:

1. Log in to the AM console as administrator, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click Local Site Properties.

2. On the Local Site Properties page for the asserting party server, select Sign SAML Response.

   The asserting party thus signs SAML responses with the private key for the default test certificate.

3. Save your work, and then click Back to Federation.

4. Click New in the Trusted Partners table to add the relying party as a trusted partner.

5. In the Destination area of the Select trusted partner type and profile page, select Artifact and Post (not SOAP Query), and then click Next.

6. Apply the following settings, adjusted for the host names you use.

   If a field is not mentioned, accept the defaults.

   Under Common Settings, use these settings:

   Name: rp.example.com:9080

   Source ID: relying party Site ID that you recorded

   Target: rp.example.com:9080

   Under Destination > Artifact, use these settings:

   SOAP URL: http://rp.example.com:9080/rp/SAMLAwareServlet

   Host List: rp.example.com

   Under Source > Post, set Post URL: http://rp.example.com:9080/rp/SAMLPOSTProfileServlet

7. Click Finish to save your work.

Follow these steps to configure the relying party AM server:

1. Log in to the AM console as administrator, navigate to Realms > Realm Name > Applications > SAML > SAML 1.x Configuration, and then click New in the Trusted Partners table to add the asserting party as a trusted partner.

2. In the Source area of the Select trusted partner type and profile page, select Artifact and Post, and then click Next.

3. Apply the following settings, adjusted for the host names you use.

   If a field is not mentioned, accept the defaults.

   Under Common Settings, use these settings:

   Name: ap.example.net:8080

   Source ID: asserting party Site ID that you recorded

   Signing Certificate Alias: test

   Under Source > Artifact, set SOAP URL: http://ap.example.net:8080/ap/SAMLSOAPReceiver

   Under Source > Post, set Issuer: ap.example.net:8080

   Click Finish to save your work.

Once you have successfully configured both parties, try SAML v1.x Web SSO:

1. Log out of The AM console on both servers.

2. Try Web SSO using the SAML Artifact profile.

   1. Simulate the AM administrator browsing the asserting party's site, and selecting a link to the AM console on the relying party's site.

      The URL to simulate this action is something like http://ap.example.net:8080/ap/SAMLAwareServlet?TARGET=http://rp.example.com:9080/rp.

      AM requires that you authenticate.

   2. Login as AM demo user, demo with default password changeit, on the asserting party server.

   3. Notice that you are redirected to the AM console on the relying party server, and that you are successfully logged in as the demo user.

   4. Log out of The AM console on both servers.

3. Try Web SSO using the SAML HTTP POST profile:

   1. Simulate the AM administrator browsing the asserting party's site, and selecting a link to the AM console on the relying party's site.

      The URL to simulate this action is something like http://ap.example.net:8080/ap/SAMLPOSTProfileServlet?TARGET=http://rp.example.com:9080/rp.

      AM requires that you authenticate.

   2. Login as AM administrator, amadmin, on the asserting party server.

   3. Notice that you are redirected to the AM console on the relying party server, and that you are successfully logged in as amadmin.