test

Sun OpenSSO Enterprise 8.0 Administration Guide

Chapter 10 SAML 1.x Administration

Security Assertion Markup Language (SAML) is an open-standard protocol that uses a L framework to exchange security information between an authority and a trusted partner site. The security information concerns itself with a subject's authentication status, access authorization and attribute information. (A person identified by an email address is a subject as might be a printer.) A SAML authority (also referred to as the asserting party) is a platform or application that has been integrated with SAML API, allowing it to relay security information. For example, asserting that a subject has been authenticated into its system by passing the required attributes. Trusted partner sites receive the security information and rely on its authenticity.

SAML Attributes

All attributes associated with SAML1.x can be configured and defined in the OpenSSO Enterprise console. This section describes how to create and configure the SAML1.x service.

Note –

By default character escaping is enabled so that you can use the following special characters in SAML 1.x attributes in the OpenSSO Enterprise console:

To disable character escaping:

  1. In the OpenSSO Enterprise Console, go to Configuration>Servers and Sites>Default Server Setting>Advanced.

  2. Enter the com.sun.identity.saml.escapeattributevalue as the key, and false as the value.

  3. Restart the server.

If you wish to enable character escaping, change the value to true and restart the server.

The following SAML attributes can be configured for your implementation by clicking the Local Site Properties button:

Target Specifier

This attribute assigns a name to the destination site URL used in SAML redirects. The default is TARGET. Only sites configured in the Trusted Partners attribute can be specified as a TARGET.

Site Identifiers

For information about site identifiers and to see the procedure for configuring a site identifier, see the following section.

ProcedureTo Configure a Site Identifier

The Site Identifier defines any site hosted by the server on which OpenSSO Enterprise is installed. A default value and an automatically generated Site ID are defined for the host during installation. Multiple entries are possible. For example, load balancing or multiple instances of OpenSSO Enterprise sharing the same data store would all need to be defined. The starting point is the Site Identifiers attribute on the SAML screen under the Federation interface. Site IDs are defined in the Servers and Sites configuration screen. For more information, see Servers and Sites in Sun OpenSSO Enterprise 8.0 Administration Reference.

  1. Click New to add a new site identifier or click on the name of a configured site identifier to modify its profile.

    The Site Identifier attributes are displayed.

  2. Provide values for the Site Identifier attributes based on the following information:

    Instance ID

    The value of this property is protocol ://host: port.

    If configuring SAML for SSL (in both the source and destination site), ensure that the protocol defined here is https//.

    Site ID

    The site ID is an identifier generated for each site (although the value will be the same for multiple servers behind a load balancer). There is a class in the com.sun.identity.saml.common package that can be used to generate this identifier manually, if needed. Type the following at the command line:


    % java -classpath FM-classpath com.sun.identity.saml.common.SAMLSiteID 
protocol://host:port
    Issuer Name

    The default value of this property is host :port, but it could be any URI.

  3. Click OK to complete the Site Identifier configuration.

  4. Click Save on the Local Site Properties page to complete the SAML configuration.

Trusted Partners

For information on trusted partners and to see the procedure for configuring a new Trusted Partner, see the following section.

ProcedureTrusted Partners: Selecting Partner Type and Profile

This attribute defines any trusted partner (remote to the server on which OpenSSO Enterprise is installed) that will be communicating with OpenSSO Enterprise.

Note –

The trusted partner site must have a prearranged trust relationship with one or more of the sites configured in the Site Identifiers attribute.

The first step in configuring a trusted partner is to determine the partner's role in the trust relationship. A trusted partner can be a source site (one that generates a single sign-on assertion) or a destination site (one that consumes a single sign-on assertion). For example, if the partner is the source site, this attribute is configured based on how it will send assertions. If the partner is the destination site, this attribute is configured based on the profile in which it will be receiving assertions. Following is the first part of the procedure for configuring a trusted partner. The starting point is the SAML screen under Federation.

Note –

To edit or duplicate the attributes of a trusted partner profile, click the appropriate button in the Actions column next to the configured trusted partner name.

  1. Select the role (Destination or Source) of the partner site you are configuring by checking the appropriate profile that will be used to communicate with it.

    You may choose Web Browser Artifact Profile or Web Browser Post Profile for either Destination, Source or both, or SOAP Query for Destination only. The choices made dictate which of the attributes in the following steps need to be configured.

    Note –

    Click Edit to change the role of the partner site if you are modifying an existing trusted partner.

  2. Click Next.

ProcedureTrusted Partners: Configuring Trusted Partner Attributes

Following is the second part of the procedure for configuring a trusted partner. Based on the roles selected in the first part, any of the sub-attributes listed in the following sections may need to be defined.

Note –

If you reached this page by clicking Edit or Duplicate on the SAML configuration screen under Federation, modify the trusted partner profile based on the steps below and click Save to change the values. Click Save on the SAML Profile page to complete the modification.

  1. Type in values for the Common Settings sub-attributes.

    Name

    Can be any string, such as an organization name.

    Source ID

    This is a 20 byte sequence (encoded using the Base64 format) that comes from the partner site. It is generally the same value as that used for the Site ID attribute when configuring the Site Identifiers attribute.

    Target

    This is the domain of the partner site (with or without a port number). If you want to contact a web page that is hosted in this domain, the redirect URL is picked up from the values defined in the Trusted Partner attribute.

    Note –

    If there are two defined entries for the same domain (one containing a port number and one without a port number), the entry with the port number takes precedence. For example, assume the following two trusted partner definitions: target=sun.com and target=sun.com:8080. If the principal is seeking http://machine.sun.com:8080/index.html, the second definition will be chosen.

    SAML URL

    The URL that points to the servlet that implements the Web Browser Artifact Profile.

    Site Attribute Mapper

    The class is used to return a list of attribute values defined as AttributeStatements elements in an Authentication Assertion. A site attribute mapper needs to be implemented from the PartnerSiteAttributeMapper interface.

    If no class is defined, no attributes will be included in the assertion.

    Name Identifier Mapper

    The class that defines how the subject of an assertion is related to an identity at the destination site. An account mapper needs to be implemented from the com.sun.identity.saml.plugins.PartnerAccountMapper interface. The default is com.sun.identity.saml.plugins.DefaultAccountMapper.

    If no class is defined, no attributes will be included in the assertion.

    Version

    The SAML version used (1.0 or 1.1) to send SAML requests. To change the version or protocol, click on the Local Site Properties button and change the Protocol and Assertion attributes as necessary.

    Signing Certificate Alias

    A certificate alias that is used to verify the signature in an assertion when it is signed by the partner and the certificate cannot be found in the KeyInfo portion of the signed assertion.

  2. Type in values for the Destination sub-attributes.

    Artifact: SAML URL

    The URL that points to the servlet that implements the Web Browser Artifact Profile.

    Post: Post URL

    The URL that points to the servlet that implements the Web Browser POST Profile.

    Host List

    A list of the IP addresses, the DNS host name, or the alias of the client authentication certificate used by the partner. This is configured for all hosts within the partner site that can send requests to this authority. This list helps to ensure that the requestor is indeed the intended receiver of the artifact. If the requester is defined in this list, the interaction will continue. If the requester’s information does not match any hosts defined in the host list, the request will be rejected.

  3. Type in values for the Source sub-attributes.

    Artifact: SOAP URL

    The URL to the SAML SOAP Receiver.

    Authentication Type

    Authentication types that can be used with SAML:

    • Specify None if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is not protected by HTTP basic authentication and/or SSL.

    • Specify Basic if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is protected by HTTP basic authentication.

    • Specify SSL if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by HTTP SSL.

    • Specify SSL with Basic if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by BASIC AUTH WITH SSL.

    Note –

    If you are protecting the SAML SOAP receiver URL with HTTP basic authentication, you do so in the web container configuration and not in the OpenSSO Enterprise configuration. You do, however, supply the HTTP basic authentication user ID and password in the OpenSSO Enterprise configuration.

    This attribute is optional. If not specified, the default is NOAUTH. If BASICAUTH or SSLWITHBASICAUTH is specified, the Trusted Partners attribute is required and should be HTTPS.

    User

    When BASICAUTH is chosen as the Authentication Type, the value of this attribute defines the user identifier of the partner being used to protect the partner’s SOAP receiver.

    User's Password

    When BASICAUTH is chosen as the Authentication Type, the value of this attribute defines the password for the user identifier of the partner being used to protect the partner’s SOAP receiver.

    User's Password (reenter)

    Reenter the password defined previously.

  4. Type a value for the Post sub attribute.

    Issuer

    The creator of a generated assertion. The default syntax is hostname: port.

  5. Click Finish.

  6. Click Save on the SAML Profile page to complete the configuration.

Target URLs

If the Target URL received using either profile is listed as a value of this attribute, the received assertions will be sent to the Target URL using an HTTP FORM POST.

Note –

To edit or duplicate the attributes of a trusted partner profile, click the Local Site Properties button and click New in the Target URL table.

ProcedureTo Configure a Target URL

The following sub attributes can be defined (or modified) for each Target URL that will receive assertions using POST.

  1. Click New to add a new target URL.

    The Add New Post to Target URL page is displayed. You can also reach this page by selecting the Edit or Duplicate button of a defined Target URL.

  2. Type values for the attributes.

    Protocol

    Choose either http or https.

    Server Name

    The name of the server on which the TARGET URL resides, such as www.sun.com.

    Port

    This attribute contains the port number such as 58080.

    Path

    This attribute contains the URI such as /opensso/console.

  3. Click OK to complete the Target URL configuration.

  4. Click Save on the SAML Profile page to complete the SAML configuration.

Default Protocol Version

This attribute specifies the default SAML protocol version this entity uses to communicate with remote partners. Default value is 1.1.

Default Assertion Version

This attribute specifies the default SAML assertion version this entity uses to communicate with remote partners.

Remove Assertion

If enabled (true), the SAML entity will remove assertions from memory once they are used. Otherwise, all assertions remain in memory until expiration. It is enabled by default.

Assertion Timeout

This attribute specifies the number of seconds before a timeout occurs on an assertion. The default is 420.

Assertion Skew Factor for notBefore Time

This attribute is used to calculate the notBefore time of an assertion. For example, if IssueInstant is 2002-09024T21:39:49Z, and Assertion Skew Factor For notBefore Time is set to 300 seconds (180 is the default value), the notBefore attribute of the conditions element for the assertion would be 2002-09-24T21:34:49Z.

Note –

The total valid duration of an assertion is defined by the values set in both the Assertion Timeout and Assertion Skew Factor For notBefore Time attributes.

Artifact Timeout

This attribute specifies the period of time an assertion that is created for an artifact will be valid. The default is 400.

SAML Artifact Name

This attribute assigns a variable name to a SAML artifact. The artifact is bounded-size data that identifies an assertion and a source site. It is carried as part of a URL query string and conveyed by redirection to the destination site. The default name is SAMLart . Using the default SAMLart, the redirect query string could be http://host:port /deploy-URI/ SamlAwareServlet?TARGET=target-URL /&SAMLart=artifact123.

Sign SAML Assertion

This attribute specifies whether all SAML assertions will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.

Sign SAML Request

This attribute specifies whether all SAML requests will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.

Sign SAML Response

This attribute specifies whether all SAML responses will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.

Note –

All SAML responses used by the Web Browser POST Profile will be digitally signed whether this option is enabled or not enabled.

Attribute Query

Defines the list of the Attribute Query Profile for X. 509 subjects only.

SAML Operations

This section contains procedures illustrating how to use the OpenSSO Enterprise SAML Service.

Setting Up SAML Single Sign-on

The following procedures explain how to configure and access instances of OpenSSO Enterprise for single sign-on using SAML 1.x assertions. Machine A (exampleA.com) is the source site which authenticates the user and creates the SAML authentication assertion. Machine B (exampleB.com) is the destination site which consumes the assertion and generates a SSOToken for the user.

Note –

If both machines are in the same domain, the cookie names must be different. You can change the cookie name by modifying the Coopkie Name property in Configuration>Servers and Sites>Security, located in the OpenSSO Enterprise console.

This section contains the following procedures:

ProcedureTo Set Up SAML Single Sign-on

This procedure assumes the following values:

Deployment URI 

opensso

Port 

58080 

Protocol 

http

  1. Write down or copy the value of the Site ID attribute from the destination site (machine B).

    1. Login to the console running at exampleB.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click the SAML button.

    4. Click the sole entry listed under Site Identifiers.

      This takes you to the Edit site identifier page.

    5. Write down or copy the value of the Site ID attribute.

    6. Click Cancel.

    7. Log out of this instance of OpenSSO Enterprise.

  2. Configure the source site (machine A) to trust the destination site (machine B) AND write down or copy the value of the Site ID attribute from the source site.

    1. Login to the console running at exampleA.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click New under Trusted Partners.

      This takes you to the Select trusted partner type and profile page.

    4. Check Artifact and Post under Destination and click Next.

      This takes you to the Add New Trusted Partner page.

    5. Set the values of the following attributes to configure machine B as a trusted partner of machine A:

      name 

      Type the name of the trusted partner. The name will be displayed in the trusted partner table. 

      Source ID 

      Type the Site ID copied from the destination site, machine B, in the previous step. 

      Target 

      The value of this attribute contains the host's domain or domain with port. Do not include the accompanying protocol. For example, exampleB.com and exampleB.com:58080 are valid but, http://exampleB.com:58080.

      SAML URL 

      http://exampleB.com:58080/opensso/SAMLAwareServlet

      HOST LIST 

      exampleB.com

      POST URL 

      http://exampleB.com:58080/opensso/SAMLPOSTProfileServlet

    6. Click Finish.

    7. Click Save.

    8. Click the sole entry listed under Site Identifiers.

      This takes you to the Edit site identifier page.

    9. Write down or copy the value of the Site ID attribute.

    10. Click Cancel to go to previous page.

    11. Log out of OpenSSO Enterprise.

  3. Configure the destination site (machine B) to trust the source site (machine A).

    1. Login to the OpenSSO Enterprise console running at exampleB.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click New under Trusted Partners.

      This takes you to the Select trusted partner type and profile page.

    4. Check Artifact and Post under Source and click Next.

      This takes you to the Add New Trusted Partner page.

    5. Set the values of the following attributes to configure machine A as a trusted partner of machine B:

      Name 

      Type the name of the trusted partner. This will appear in the Trusted Partners table. 

      Source ID 

      Type the Site ID you copied from the source site, machine A, in the previous step. 

      SOAP URL 

      http://exampleA.com:58080/opensso/SAMLSOAPReceiver

      Issuer 

      exampleA.com:58080

      Note –

      If machine B uses https, check SSL under Authentication Type. Be sure to modify the protocol in the other attributes as necessary.

    6. Click Finish.

    7. Click Save.

    8. Log out of OpenSSO Enterprise.

ProcedureTo Verify the SAML Single Sign-on Configurations

  1. Login to the OpenSSO Enterprise console running at exampleA.com as the default administrator, amadmin.

  2. To initialize single sign-on from machine A, do one of the following:

    • Access the following URL to use the SAML Artifact profile:

      http://exampleA.com:58080/opensso/SAMLAwareServlet?TARGET=exampleB.com_Target_URL

    • Access the following URL to use the SAML POST profile:

      http://exampleA.com:58080/opensso/SAMPOSTProfileServlet?TARGET=exampleB.com_Target_URL

      Note –

      XML signing must be enabled before running the SAML POST profile. .

    exampleB.com_Target_URL is any URL on the exampleB.com site to which the user will be redirected after a successful single sign-on. For testing purpose, this could be the login page as in TARGET=http://exampleB.com:58080/opensso/UI/Login. If the administrator successfully accesses the OpenSSO Enterprise console on the destination site without manual authentication, an SSOtoken has been created for the principal on the destination site and single sign-on has been properly established.