Managing SAML v1.x Single Sign-On

This chapter describes OpenAM’s support for the SAML v1.x framework for exchanging security data.

SAML v1.x is an XML- and SOAP-based framework that allows online trusted partners to exchange security information. In particular, SAML v1.x defines mechanisms for browser based web single sign-on (SSO) across independent organizations that work together to permit SSO for access to resources.

Although not strictly compatible with SAML v1.x, SAML v2.0 extends SAML v1.x to several additional use cases and also clarifies how partners share metadata with each other. Unless you are integrating with an existing SAML v1.x deployment consider using SAML v2.0, or an alternative, such as OAuth 2.0 or OpenID Connect 1.0, instead.

OpenAM’s support for SAML 1.x requires stateful sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to use SAML 1.x functionality in OpenAM.

About SAML v1.x

SAML v1.x was defined in response to several technical problems:

  • Web SSO solutions often use SSO session cookies. Browsers do not return cookies across domains. For instance, browsers do not return cookies set by servers in the example.com domain to servers in the example.net domain. SAML v1.x works around this limitation of HTTP cookies.

  • Before SAML v1.x was defined, there were already proprietary SSO solutions, but the solutions did not interoperate well across domains.

    SAML v1.x specifies a standard, cross-domain, interoperable SSO mechanism that works together with proprietary SSO services in a particular domain.

  • Before SAML v1.x was defined, there was not an easy way to communicate security attributes across organization boundaries.

    SAML v1.x simplifies the communication of security attributes between different organizations.

In SAML v1.x, business partners can play two roles. The asserting party, also known as the SAML authority and whose domain is the Source site, authenticates users and asserts information about them. The relying party, whose domain is known as the Destination site, consumes assertions and uses information from the assertion to decide whether to allows access to resources.

In the Web Browser SSO Profiles for SAML v1.x, the user generally starts by authenticating with the asserting party and then selecting a relying party link to browse. Alternatively, the "Destination-Site-First" scenario can start with the user browsing to the relying party’s site and being redirected to the asserting party’s site to authenticate.

The SAML v1.x Inter-site Transfer Service is a service that redirects the authenticated user from the asserting party’s site to the appropriate service on the relying party’s site. The Inter-site Transfer Service also handles artifact and redirect generation. How this service transfers the user to the relying party’s site depends on how the asserting party and the relying party exchange messages.

The asserting party and relying party can exchange messages either by reference, where the asserting party sends an artifact (a base64-encoded reference to the assertion) as a query string parameter value, or by value, where the asserting party directs the user’s browser to HTTP POST the assertion to the relying party.

When the asserting party and relying party use artifacts, the Inter-site Transfer Service redirects the user’s browser to the relying party’s Artifact Receiver Service with the artifact as the value of a query string parameter. The relying party retrieves the artifact from the query string, and then sends a SAML Request to the Responder Service at the asserting party. The asserting party replies with a SAML Response containing one or more assertions.

saml 1 browser artifact profile

See section 4.1.1 of the SAML v1.1 technical overview for more detail.

When the assertion is sent using the Browser/POST Profile, the Inter-site Transfer Service responds to the user’s browser with an auto-submitting form containing the SAML response. The browser then submits the SAML response as form data by HTTP POST to the relying party’s Assertion Consumer Service. The relying party’s Assertion Consumer Service then processes the assertion.

saml 1 browser post profile

See section 4.2.1 of the SAML v1.1 technical overview for more detail.

The Assertion Consumer Service at the relying party validates the digital signature on the SAML response, and redirects the browser to the target URL of the resource that the user is attempting to access. The server providing that resource uses the relying party’s authorization decision capabilities to establish whether the user can access the resource. If so, the resource is returned to the user’s browser. If the relying party is using OpenAM, for example, then the relying party sets an OpenAM SSO token based on the SAML response, and this token is used to track the user’s session for authorization.

Organizations working together to achieve SAML v1.x web SSO are called trusted partners in this context. Trusted partners agree on which services they provide, which web SSO profiles they implement, and how information is exchanged in the assertions, including profile attribute values. Once the trusted partners have reached agreement on how they interact, you can collect information about your partners' configurations and configure OpenAM to match your organization’s part of the agreement.

Gathering Configuration Information

Before you can configure OpenAM to allow web SSO with trusted partners, you must first gather information about the agreement itself, as well as information for your site and for your partners sites.

This section lists the data that you must collect:

  • SAML protocol version to use (1.1 or 1.0; default: 1.1)

  • Assertion version to use (1.1 or 1.0; default: 1.1)

  • Which trusted partners play which roles (asserting party, relying party)

  • Domain names of partner sites (for example, example.com, example.net)

  • Whether assertions are exchanged by SAML artifact or by HTTP POST

    If assertions are exchanged by artifact, also gather this information:

    • SAML artifact parameter name (default: SAMLart)

    • Artifact timeout

    • URL to the relying party endpoint that receives the artifact (for example, https://rp.example.com/openam/SAMLAwareServlet)

    • Relying party hosts that consume artifacts (by IP addresses, DNS names, or certificate aliases)

    • URL to the asserting party endpoint that responds to SAML requests (for example, https://ap.example.net/openam/SAMLSOAPReceiver)

    • Authentication credentials to connect to the asserting party endpoint, if any (for example, the username and password for HTTP Basic authentication)

    • Asserting party signing certificate alias

    If assertions are exchanged by HTTP POST, also gather this information:

    • URL to the relying party endpoint that consumes the form data in the POST assertion (for example, https://rp.example.com/openam/SAMLPOSTProfileServlet)

    • Asserting party host:port issuing assertions

    • Asserting party signing certificate alias

  • Whether the relying party sends SOAP query requests to the asserting party, for example, to get authorization decisions

    If the relying party queries the asserting party, also gather this information:

    • Relying party hosts that consume artifacts (by IP addresses, DNS names, or certificate aliases)

    • How to get SSO information, and to map partner actions to authorization decisions

    • Asserting party host:port issuing assertions

    • Asserting party signing certificate alias

  • Target specifier parameter name (default: TARGET)

  • Assertion timeout

  • Whether to digitally sign assertions, requests, responses

  • Partners' public key certificates used for HTTPS

  • Partners' public key certificates used for message signing (unless included on the KeyInfo element of signed messages)

  • Partners' Site IDs (base64-encoded ID, for example, XARFfsIAXeLX8BEWNIJg9Q8r0PE=)

  • What NameID formats are used to exchange names (for example, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

  • How attributes map from an assertion to an OpenAM profile (for example, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress|EmailAddress=mail)

For more information about your own public key certificates, see "Preparing To Secure SAML v1.x Communications".

For your own Site ID, see the following procedure.

To Generate a Site Identifier For an OpenAM Site

Trusted partners should ask you for a Site ID. OpenAM generates a SAML v1.x Site ID value at configuration time. This Site ID value corresponds to the server. To find this in OpenAM 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 OpenAM 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 OpenAM server, shown with lines folded to fit on the printed page:

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

Preparing To Secure SAML v1.x Communications

SAML communications are secured using Public Key Infrastructure (PKI). Communications should be protected over the network by HTTPS, and relying parties requesting assertions should use SSL or TLS mutual authentication to identify each other, meaning they should be able to trust each others' certificates. Furthermore, when an asserting party works through the user’s browser to post an assertion to the relying party, then the asserting party must digitally sign the SAML response.

A certificate can be trusted when the signer’s certificate is trusted, or when the certificate itself is trusted. Trusted partners must either use public key certificates signed by a well-known Certificate Authority (CA), or share their self-signed or private CA signing certificates.

To Configure Keys For Protecting SAML v1.x Communications
  1. See the chapter "Managing Certificates and Keystores" for instructions on handling your own key pairs.

    For specific instructions on changing signing keys, see the procedure "To Change OpenAM Default test Signing Key ".

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

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

Configuring SAML v1.x For Your Site

After you have gathered configuration information and prepared to secure SAML v1.x communications you can configure SAML v1.x for your site.

When you enter SAML v1.x configuration data, OpenAM console escapes these special characters by default: & < > " ' /. If you have already escaped these characters in the data that you plan to enter in the OpenAM console, set the value of the com.sun.identity.saml.escapeattributevalue property to false under Configure > Server Defaults > Advanced, and then restart OpenAM or the container in which it runs to prevent OpenAM console from escaping the characters for you.

To Configure Asserting Party Local Site Properties

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

  1. Log in to OpenAM console as administrator, amadmin, browse to Federation > 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 OpenAM Site, click New in the Site Identifiers table, and then add the information for the OpenAM 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 OpenAM 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 OpenAM user profile attributes.

    This allows OpenAM 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 OpenAM user profile attributes.

  12. Save your work.

To Configure Relying Party Local Site Properties

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

  1. Log in to OpenAM console as administrator, amadmin, browse to Federation > 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 OpenAM Site, click New in the Site Identifiers table, and then add the information for the OpenAM 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 OpenAM 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 OpenAM user profile attributes.

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

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

  12. Save your work.

Configuring SAML v1.x Trusted Partners

After you have gathered configuration information and if necessary imported public key certificates from trusted partners you can configure SAML v1.x information for the partners:

To Configure a Trusted Relying Party

OpenAM console refers to the relying party as the Destination, because the relying party’s site is the destination site:

  1. Log in to OpenAM console as administrator, amadmin, browse to Federation > 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. OpenAM 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 OpenAM must find the signing certificate elsewhere. If the relying party provides the signing certificate separately, import the signing certificate into OpenAM’s default keystore file, and set the alias for the signing certificate here in the configuration. For more information about OpenAM’s default keystore, see "Managing Certificates and Keystores".

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

  5. Save your work.

To Configure a Trusted Asserting Party

OpenAM console refers to the asserting party as the Source, because the asserting party’s site is the source site:

  1. Log in to OpenAM console as administrator, amadmin, browse to Federation > 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 OpenAM 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 OpenAM’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 OpenAM. Therefore if the asserting party runs OpenAM 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.

Testing SAML v1.x Web SSO

You can try SAML v1.x Web SSO using OpenAM by following the procedures in this section:

To Prepare the OpenAM Servers
  1. Install two separate OpenAM 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 OpenAM 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 OpenAM 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 OpenAM servers acting as asserting and relying parties.

  2. On the asserting party server, login to OpenAM console as administrator, browse to Federation > 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 OpenAM console as administrator, browse to Federation > 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.

To Prepare to Test the Asserting Party

Follow these steps to configure the asserting party OpenAM server:

  1. Log in to OpenAM console as administrator, browse to Federation > 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:

  7. Click Finish to save your work.

To Prepare to Test the Relying Party

Follow these steps to configure the relying party OpenAM server:

  1. Log in to OpenAM console as administrator, browse to Federation > 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.

To Try SAML v1.x Web SSO

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

  1. Log out of OpenAM console on both servers.

  2. Try Web SSO using the SAML Artifact profile.

    1. Simulate the OpenAM administrator browsing the asserting party’s site, and selecting a link to the OpenAM 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.

      OpenAM requires that you authenticate.

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

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

    4. Log out of OpenAM console on both servers.

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

    1. Simulate the OpenAM administrator browsing the asserting party’s site, and selecting a link to the OpenAM 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.

      OpenAM requires that you authenticate.

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

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