Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Access Manager 6 2005Q1 Developer's Guide 

Chapter 11
SAML Service

Sun Java™ System Access Manager 6 2005Q1 uses the Security Assertion Markup Language (SAML) for exchanging security information. SAML defines an eXtensible Markup Language (XML) framework to achieve inter-operability across different vendor platforms that provide SAML assertions. This chapter explains SAML and defines how it is used within Access Manager. It contains the following sections:

Overview

SAML is an open-standard protocol that uses an XML framework to exchange security information between an authority and a trusted partner site. The security information concerns itself with authentication status, access authorization decisions and subject attributes. The Organization for the Advancement of Structured Information Standards (OASIS) drives the development of the SAML specifications. The latest SAML information and specifications can be found at the Oasis Security Services Technical Committee home page.

SAML security information is expressed in the form of an assertion about a subject. A subject is an entity in a particular domain, either human or machine, with which the security information concerns itself. (A person identified by an email address is a subject as might be a printer.) An assertion is a package of verified security information that supplies one or more statements concerning a subject’s authentication status, access authorization decisions or attributes. Assertions are issued by a SAML authority. (An authority is a platform or application that has been integrated with the SAML SDK, allowing it to relay security information.) The assertions are received by partner sites defined within the authority as trusted. SAML authorities use different sources to configure the assertion information including external data stores or assertions that have already been received and verified. Figure 11-1 illustrates how the SAML Service interacts with the other Access Manager components.

Figure 11-1  SAML Interaction Within Access Manager

Graphical representation of SAML interaction with Access Manager.

The SAML Service allows Access Manager to work in the following ways:

Accessing The SAML Service

The SAML Service can be accessed using a web browser or the SAML SDK. An end user would authenticate to Access Manager using a web browser and, when authorized to do so, access URLs from trusted partner sites. Developers, on the other hand, would integrate the API into their applications to enable them to exchange security information with Access Manager. For example, a Java application can use the SAML API to accomplish single sign-on. After obtaining a SSOToken from Access Manager, the application can call the doWebArtifact() method of the SAMLClient class which will send a SOAP request for authorization information to Access Manager and, if applicable, redirect the application to the destination site.

SAML Component Details

The following sections explain specific details of the components of the SAML Service. They include:

Profile Types

A set of rules describing how to embed and extract SAML assertions is called a profile. The profile describes how the assertions can be combined with other objects by an authority, transported from the authority and, subsequently, processed at the trusted partner site. Access Manager supports two profiles that use HTTP: the Web Browser Artifact Profile and the Web Browser POST profile. Either of these profiles can be used in the case of single sign-on between two SAML-enabled entities, allowing an already authenticated user to access resources from a trusted partner site. Each profile has its benefits that include:

Web Browser Artifact Profile

The Web Browser Artifact Profile defines interaction between three parties: a user equipped with a web browser, an authority site, and a trusted partner site. When an authenticated user attempts to access a trusted partner site (generally by clicking a link), they are directed to a transfer service at the authority site. In Access Manager, the transfer service is the SAML Aware Servlet. The base of the transfer URL is http(s)://identity_server_host.domain_name:port/server_deploy_uri/SAMLAwareServlet; it is appended with the URL of the location to which the user is requesting access (?TARGET=URL_of_destination). The SAML Aware Servlet then provides the following functions as part of the Web Browser Artifact Profile:

  1. It compares the SAML Service’s configured list of Trusted Partner Sites against the user’s TARGET location.

    2. Only targets configured in the Trusted Partner Sites attribute of the SAML Service can access the SAML Service. Configured targets specify a domain and/or a port number. More information on this attribute can be found in the Sun Java System Access Manager Administration Guide.

  2. Assuming the TARGET location was found in the list of Trusted Partner Sites, the SAML Aware Servlet looks for and validates the session token from the inbound request.

    3. Without a valid session token, Access Manager will not create an assertion.

  3. The SAML Aware Servlet then creates an artifact and a corresponding assertion.

    4. An artifact is carried as part of the URL and points to an assertion and its source; it is not, and does not contain, the security information itself. The assertion contains the security information and is built from the user’s session information and optional attribute information from the siteAttributeMapper class. (More information on the siteAttributeMapper can be found in com.sun.identity.saml.plugins.) The assertion can be signed.

    Note

    The need to send an artifact rather than the assertion itself is dictated by the restrictions on URL size imposed by many web browsers.

  4. It redirects the user’s browser to the Artifact Receiver URL with a query string containing the artifact and the original TARGET location.

    5. The Artifact Receiver URL is based on mapping configurations defined in the SAML Service. More information on this can be found in the SAML Service Attributes chapter of the Sun Java System Access Manager Administration Guide.

    Note

    In Access Manager, the Artifact Receiver URL and the SAML Aware Servlet are one and the same. Other SAML implementations might not integrate the two servlets.

  5. At the Artifact Receiver URL, the artifact is extracted from the query string to find the SOAP Receiver URL.

    6. The SAML SDK extracts the source ID from the artifact and uses it to find the SOAP Receiver URL in the SAML Service configuration. SAML SOAP Receiver has more information on the use of SOAP, a communications specification integrating XML and HTTPS.

  6. A SAML request containing the artifact is then sent to the SOAP Receiver URL at the trusted partner site requesting the assertion to which the artifact points.

    7. The Artifact Receiver URL uses SOAP binding to request the assertion.

  7. The SOAP Receiver URL accepts the returned artifact query from the trusted partner site and responds by sending the correct assertion in a SOAP response.
  8. The assertion is processed, mapping the user account information from the trusted partner site to the target site’s user account.

    9. The user is either granted or denied access to the trusted partner site. If access is granted a SSOToken is generated, a cookie is set to the browser and the user is redirected to the TARGET location.

    Note

    A sample has been provided to test the Web Browser Artifact Profile function. SAML Samples has more information.

Web Browser POST Profile

The Web Browser POST Profile allows security information to be supplied to a trusted partner site using the HTTP POST method (and without the use of an artifact). It consists of two interactions: the first between a user with a web browser and the Access Manager, and the second between the same user and a trusted partner site.

When an authenticated user attempts to access a trusted partner site using a web browser (usually by clicking a link), they are redirected to a transfer service in the authority site. In Access Manager, the transfer service is the SAML Post Profile Servlet. The base of the transfer URL is http(s)://identity_server_host.domain_name:port/server_deploy_uri/SAMLPOSTProfileServlet; it is appended with the URL of the location to which the user is requesting access (?TARGET=URL_of_destination). The SAML POST Profile Servlet provides functions for the two POST Profile interactions. In the first interaction between the user and Access Manager:

  1. Access Manager obtains the TARGET location from the request and retrieves the trusted partner site URL from the SAML Service.

    2. Again, only targets configured in the Trusted Partner Sites attribute of the SAML Service can access the SAML Service. More information on this can be found in the SAML Service Attributes chapter of the Sun Java System Access Manager Administration Guide.

  2. It generates an assertion using the AssertionManager class of the SAML SDK.

    3. com.sun.identity.saml contains information on the AssertionManager class.

  3. It forms, signs and Base64 encodes a SAMLResponse containing the assertion.
  4. It generates an HTML form, containing both the SAMLResponse and the TARGET as parameters, and posts the form as an HTTP response back to the user’s browser.
  5. The user’s browser is then directed to the location based on this information.

In the second interaction between the user and the trusted partner site:

  1. The trusted partner site obtains the TARGET and SAMLResponse from the request.
  2. It Base64 decodes the SAMLResponse.
  3. It verifies the signature on the SAMLResponse and obtains and verifies the SAML response itself.

    4. It also verifies the assertion inside the SAMLResponse and enforces single-sign on policy.

  4. It obtains or creates an SSOToken and redirects the authenticated user to the TARGET location.

The POST profile function is provided by either of two means: an HTTP request using the SAMLPOSTProfileServlet, or an SAMLClient API call [doWebPost( )] to a Java application.

Note

A sample has been provided to test the Web Browser POST Profile function. SAML Samples has more information.

Single Use Policy With POST Profile

According to the SAML specifications, the trusted partner site MUST ensure a single-use policy for SSO assertions communicated by the Web POST Profile. Thus, the SAMLPOSTProfileServlet maintains a store of SSO assertion IDs and the time they expire. When an assertion is received, the servlet first checks for an entry in the map. If one exists, the servlet returns an error. If not, the assertion ID and expiration time is saved to the map. The POSTCleanUpThread removes expired assertion IDs periodically.

Assertion Types

SAML assertions are represented as XML constructs based on a schema located at http://www.oasis-open.org/committees/security/docs/cs-sstc-schema-assertion-01.xsd. The SAML specification provides for several types of assertions that are also defined in the SAML Service:

One assertion may contain many different statements made by the authority.

SAML SOAP Receiver

Assertions are exchanged between Access Manager and inquiring parties using the request and response XML-based protocol defined in the SAML specification. These SAML assertions are then integrated into a standard communication protocol for transport purposes.

Note

Access Manager uses SOAP, a message communications specification integrating XML and HTTPS, to transport requests and responses in its Web Browser Artifact Profile.

SOAP binding defines how SAML request and response message exchanges are integrated into SOAP exchanges. The SAML SOAP Receiver is a servlet that processes the message. It receives a SOAP message, extracts the SAML request and responds with another SOAP message containing the requested assertion. It responds to queries for authentication, attributes or authorization decisions as well as those that include an assertion identifier reference or artifact by returning assertions.

Note

The access URL for the SAML SOAP Receiver is http(s)://identity_server_host.domain_name:port/server_deploy_uri/SAMLSOAPReceiver. The SAML SOAP Receiver only supports the POST method.

SOAP Messages

SOAP messages consist of three parts: an envelope, header data and a message body. (The SAML request/response elements are enclosed in the message body.) A client, acting as a SAML requestor, transmits a <Request> element within the body of a SOAP message to an entity acting as a SAML Receiver. In answer, the SAML Receiver MUST return either a <Response> element within the body of another SOAP message or a SOAP fault code (or error message).

Note

The SAML requestor and the SAML Receiver MUST NOT include more than one SAML request or response per SOAP message or any additional XML elements in the SOAP body.

A SAML Request may contain queries for any of the following: authentication status, authorization decisions, attribute information and one or more assertion identifier references or artifacts. A SAML Response is sent back to the requesting party for every Request received.

Note

The SAML SDK and the Java API for XML Messaging (JAXM) are used to construct SOAP messages and send them to the SOAP Receiver.

Protecting The SOAP Receiver

The Access Manager administrator has the option of protecting the SAML SOAP Receiver using authentication. The available methods are:

This option is configured in the Trusted Partner Sites attribute of the SAML Service in the form:

SourceID=source_id_of_site|SOAPUrl=url_of_site|AuthType=chosen_auth_option|User=user_id

Note

The value user=user_id is used only with the Basic Authentication and SSL With Basic Authentication options.

The default authentication type is NOAUTH. If SSL authentication is to be specified, it is configured in the SOAPUrl field with the https URL prefix. More information on the Trusted Partner Sites and other SAML Service attributes can be found in the SAML Attributes chapter of the Sun Java System Access Manager Administration Guide.

amSAML.xml

amSAML.xml is the XML service file that defines the attributes for the SAML Service. All of the attributes in the SAML Service can be managed through either the Access Manager console or the XML service file except two. These attributes can only be managed through amSAML.xml using the amadmin command line interface.

To change the values of these attributes, the amSAML.xml service file needs to be modified, the old amSAML.xml service file needs to be deleted, and the newly modified file reloaded using amadmin. Information on how to use amadmin can be found in The amadmin Command Line Tool chapter of the Sun Java System Access Manager Administration Guide. Information on the other SAML Service attributes can also be found in the Sun Java System Access Manager Administration Guide.

SAML SDK

Access Manager contains a SAML SDK made up of several Java packages. Administrators can use these packages to integrate the SAML functionality and XML messages into their applications and services. The SDK supports all types of assertions and operates with the Access Manager authorities to process external SAML requests and generate SAML responses. The packages include:

com.sun.identity.saml

This package contains the AssertionManager and SAMLClient classes. The AssertionManager provides interfaces and methods to create and get assertions, authentication assertions and assertion artifacts; it is the connection between the SAML specification and the Access Manager. Some of the methods included are:

The SAMLClient provides methods to execute either the Artifact or POST profile from within an application as opposed to a web browser. Its methods include:

com.sun.identity.saml.assertion

This package contains the classes needed to create, manage, and integrate, an XML assertion into an application. For example, Code Example 11-2 illustrates how to use the Attribute class and getAttributeValue method to get the value of an attribute. From an Assertion, call the getStatement() method to retrieve a set of statements. If a statement is an AttributeStatement, call the getAttribute() method to get a list of attributes. From there, call getAttributeValue() to retrieve the AttributeValue.

Code Example 11-2  Sample Code To Get An Attribute Value 

// get statement in the assertion

Set set = assertion.getStatement();

//assume there is one AttributeStatement

//should check null& instanceof

AttributeStatement statement = (AttributeStatement) set.iterator().next();

List attributes = statement.getAttribute();

// assume there is at least one Attribute

Attribute attribute = (Attribute) attributes.get(0);

List values = attribute.getAttributeValue();

com.sun.identity.saml.common

This package defines classes common to all SAML elements including site_ID, issuer name and server host. It also contains all SAML-related exceptions.

Caution

The date format, yyyy-MM-dd'T'HH:mm:ss'+/-'HH:mm , which was used in JDK 1.3.1 with IS 6.0 is no longer supported in IS 6.1. The correct format in JDK 1.4.1 for use in Access Manager 6.1 is:

yyyy-MM-dd'T'HH:mm:ss'+/-'HHmm

or

yyyy-MM-dd'T'HH:mm:ss'GMT''+/-'HH:mm

For example, the following are correct:

2003-04-22T01:20:02 -0001 (with a space before the zone sign)

2003-04-22T01:20:02GMT-00:01

2003-04-22T01:20:02-0001

com.sun.identity.saml.plugins

Access Manager provides four SPIs, three of them with default implementations. The implementations of these SPIs can be altered, or brand new ones written, based on the specifications of a particular customized service. These can then be used to integrate the SAML Service into the custom service. Currently, the APIs include the AccountMapper, ActionMapper, AttributeMapper and SiteAttributeMapper.

com.sun.identity.saml.protocol

This package contains classes that parse the request and response XML messages used to exchange assertions and their authentication, attribute or authorization information.

AuthenticationQuery

The AuthenticationQuery class represents an authentication query. An application sends a SAML request with an AuthenticationQuery inside. The Subject of the AuthenticationQuery must contain a SubjectConfirmation element. In this element, ConfirmationMethod needs to be set to urn:com:sun:identity, and SubjectConfirmationData needs to be set to the SSOToken id of the Subject. If the Subject contains a NameIdentifier, then the info in the NameIdentifier should be the same as the one in the SSOToken.

AttributeQuery

The AttributeQuery class represents a query concerning an identity’s attributes. An application sends a SAML request with an AttributeQuery inside. The application develops an AttributeMapper to obtain either a SSOToken ID or an Assertion containing an AuthenticationStatement from the query and the mapper is then used to retrieve the attributes for the Subject. If no AttributeMapper for the querying site is found, then the DefaultAttributeMapper will be used. To use the DefaultAttributeMapper, the application should put either the SSOToken ID or an assertion containing an AuthenticationStatement in the SubjectConfirmationData element of the Subject in the query. If an SSOToken ID is used, then the ConfirmationMethod must be set to urn:com:sun:identity:. If an assertion is used, then this assertion should be issued by the Access Manager instance processing the query or a server that is trusted by the Access Manager instance processing the query.

Note

In DefaultAttributeMapper, it is possible to query a subject's attributes using another subject's SSOToken as long as the SSOToken has the privilege of retrieving those attributes.

For a query using the DefaultAttributeMapper, any matching attributes found in the Identity Management module will be returned. If no AttributeDesignator is specified in the AttributeQuery, all attributes from the services defined under the userServiceNameList in amSAML.properties will be returned. userServiceNameList’s value is user service names separated by a comma.

AuthorizationDecisionQuery

The AuthorizationDecisionQuery class represents a query concerning an identity’s authority to access protected resources. An application sends a SAML request with an AuthorizationDecisionQuery inside. The application develops an ActionMapper to obtain an SSOToken ID. The mapper is then used to retrieve the authentication decisions for the actions defined in the query.

If no ActionMapper for the querying site is found in the configuration, a DefaultActionMapper will be used. To use the DefaultActionMapper, the application should put the SSOToken ID in the SubjectConfirmationData element of the Subject in the query. If SSOToken ID is used, then the ConfirmationMethod must be set to urn:com:sun:identity:. If a NameIdentifier is present, then the info in the SSOToken must be the same as the one in the NameIdentifier.

Note

The DefaultActionMapper handles actions in action namespace urn:oasis:names:tc:SAML:1.0:ghpp only. The iPlanetAMWebAgentService is used to serve the policy decisions for this action namespace.

The application may also pass in the authentication information through the Evidence element in the query. The Evidence could be an AssertionIDReference or an assertion containing an AuthenticationStatement issued by the Access Manager instance processing the query, or an assertion issued by a server that is trusted by the Access Manager instance processing the query. The Subject in the AuthenticationStatement as the evidence should be the same as the one in the query.

Note

Policy conditions can be passed in through AttributeStatements of Assertion(s) inside the Evidence of the query. If the value of an attribute contains TEXT node only, then the condition is set as attributeName=attributeValueString; otherwise, the condition is set as attributename=attributeValueElement.

AuthorizationDecisionQuery Sample

There are many ways to form an authorization decision query and have the decision assertion returned. Code Example 11-3 illustrates one way to do it.

Code Example 11-3  AuthorizationDecisionQuery Code Sample 

// testing getAssertion(authZQuery): no SC, with ni, with

// evidence(AssertionIDRef, authN, for this ni):

String nameQualifier = "dc=iplanet,dc=com";

String pName = "uid=amadmin,ou=people,dc=iplanet,dc=com";

NameIdentifier ni = new NameIdentifier(pName, nameQualifier);

Subject subject = new Subject(ni);

String actionNamespace = "urn:test";

// policy should be added to this resource with these

// actions for the subject

Action action1 = new Action(actionNamespace, "GET");

Action action2 = new Action(actionNamespace, "POST");

List actions = new ArrayList();

actions.add(action1);

actions.add(action2);

String resource = "http://www.sun.com:80";

eviSet = new HashSet();

// this assertion should contain authentication assertion for

// this subject and should be created by a trusted server

eviSet.add(eviAssertionIDRef3);

evidence = new Evidence(eviSet);

authzQuery = new AuthorizationDecisionQuery(eviSubject1, actions,

evidence, resource);

try {

assertion = am.getAssertion(authzQuery, destID);

} catch (SAMLException e) {

out.println("--failed. Exception:" + e);

}

com.sun.identity.saml.xmlsig

All SAML assertions, requests and responses may be signed using this signature API. This is an SPI in which the interfaces can be implemented and proprietary XML/signature implementations can be plugged in. This package contains the classes needed to sign and verify. By default, the keystore provided with the JDK is used and the key type is DSA. The configuration properties for this functionality are in AMConfig.properties. Information on these properties can be found in SAML of Appendix A, "AMConfig.properties File." See SAML Samples for information on the signature functionality.

SAML Samples

There are several samples that can be accessed from the Access Manager installation. They are located in IdentityServer_base/SUNWam/samples/saml. These samples illustrate how the SAML service can be used in different ways. They include:

A README file is included with each sample with information and instructions on how to use it.



Previous      Contents      Index      Next     

Part No: 817-7649.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.