Sun ONE logo     Previous     Contents     Index     Next     

Sun ONE Identity Server Programmer's Guide





Chapter 8   Using The SAML Service


Sun™ One Identity Server 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 this type of information. This chapter explains SAML and defines how it is used within the Identity Server. 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.

Note

The latest SAML information and specifications can be found at http://www.oasis-open.org/committees/security/.



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 computer, 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, attributes or access authorization decisions. 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 8-1 illustrates how the SAML Service interacts with the other Identity Server components. (The blocks filled with solid color are components of the SAML Service.)
Figure 8-1    SAML Architecture
Architecture of Identity Server SAML Service
The SAML Service allows the Identity Server to work with external applications in the following ways:

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.

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 to a trusted partner site and, subsequently, processed at the latter. Currently, Identity Server supports two profiles that use HTTP: the Web Artifact Profile and the Web POST profile. These profiles are used in the case of single sign-on when an authenticated user attempts to access resources from a trusted partner site. Both profiles can also be the receiver when accepting user single sign-on from a trusted partner site.

Note

The profile methods can be initiated through a web browser or the SAML API. More information on this API can be found in "com.sun.identity.saml".





Web Artifact Profile

The Web Artifact Profile defines interaction between three parties: a user equipped with a web browser, an authority site, and an trusted partner site. When an authenticated user attempts to access a trusted partner site (usually by clicking a link), they are redirected to a transfer service in the authority site. In Identity Server, the transfer service is the SAML Aware Servlet. The base of the transfer URL is http(s)://<server:port>/<server_deploy_uri>/SAMLAwareServlet; it is appended with the user's TARGET location (?TARGET=URL_of_destination). The SAML Aware Servlet then provides the following functions as part of the Web Artifact Profile:
  1. It compares its list of Trusted Partner Sites against the user's TARGET location.
    Only targets configured in the Trusted Partner Sites attribute of the SAML Service can access the SAML Service. More information on this attribute can be found in the Sun ONE Identity Server Administration Guide.
  2. It looks for and validates the SSO Token in the inbound request.
    Without a valid SSO Token, the Identity Server will not create an assertion.
  3. It creates an artifact and a corresponding assertion.
    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 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 opens a connection to the Artifact Receiver URL and redirects the user to the TARGET location (trusted partner site) with a query string containing the artifact.
    The Artifact Receiver URL is based on mapping configurations defined in the SAML Service. More information on this can be found in the Sun ONE Identity Server Administration Guide. Upon arriving at the TARGET location, the artifact is extracted and returned to the authority site in a query requesting the assertion to which the artifact points.
  5. It accepts an artifact query from the trusted partner site and responds by sending the correct assertion.
    The assertion is processed and the user is either granted or denied access to the trusted partner site. If access is granted an SSO token is generated, a cookie is set to the browser and the user is redirected to the TARGET location.


Web POST Profile

The Web POST Profile allows security information to be supplied to a trusted partner site without the use of an artifact. It consists of two interactions: the first between a user with a web browser and the Identity Server, 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 Identity Server, the transfer service is the SAML Post Profile Servlet. The base of the transfer URL is http(s)://<server:port>/ <server_deploy_uri>/SAMLPOSTProfileServlet; it is appended with the user's TARGET location (?TARGET=URL_of_destination). The SAML POST Profile Servlet is what provides functions for the two Web POST Profile interactions. In the first interaction between the user and Identity Server:
  1. It obtains the TARGET location from the request and retrieves the trusted partner site URL from the SAML Service.
    Again, only targets configured in the Trusted Partner Sites attribute of the SAML Service can access the SAML Service. More information on this attribute can be found in the Sun ONE Identity Server Administration Guide.
  2. It generates an assertion using the AssertionManager class of the SAML SDK.
  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.
In the second interaction between the user and the trusted partner site:
  1. It 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.
    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.
An advantage of the Web POST profile is that, because it does not use SOAP, it easily moves through a firewall and/or proxy server. The Web POST profile function is provided by either of two means: an HTTP request using the SAMLPOSTProfileServlet, or an SAMLClient API call to a Java application.

Note

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




SAML SOAP Receiver

Assertions are exchanged between Identity Server 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; Identity Server uses SOAP (Simple Object Access Protocol), a message communications specification integrating XML and HTTPS. 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 information. The SAML SOAP Receiver is the producer of SAML assertions. It responds to queries for authentication, attributes or authorization decisions as well as those that include an assertion identifier or artifact by returning assertions.

Note

The access URL for the SAML SOAP Receiver is http(s):// <server:port>/<server_deploy_uri>/SAMLSOAPReceiver.





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 identifiers 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 Identity Server administrator has the option of protecting the SAML SOAP Receiver using authentication. There are five types:
This option is configured in the Trusted Partner Sites attribute of the SAML Service in the form:
SourceID=sourceidofsite|SOAPUrl=urlofsite|AuthType=chosen_auth_option|User=userid
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 Identity Server Administration Guide.

Accessing The SAML Service

The SAML Service can be accessed using a web browser or the SAML SDK. An end user would authenticate to the Identity Server through a web browser and, when authorized, access URLs from trusted partner sites. Developers, on the other hand, would integrate the APIs into their applications to enable them to exchange security information with the Identity Server. For example, a Java application can use the SAML API to accomplish single sign-on. After obtaining an SSO token from the Identity Server, the application can call the doWebPOST() method of the SAMLClient class which contacts the Identity Server and can redirect the application to the destination site.


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 Identity Server 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 and then reloaded using amadmin. Information on how to use amadmin can be found in Chapter 6 "Service Management." Information on the additional SAML Service attributes can be found in the Sun ONE Identity Server Administration Guide.


SAML SDK

Identity Server contains a SAML SDK made up of APIs and lower level 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 Identity Server 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 Identity Server. Some of the methods included are:
The SAMLClient, on the other hand, provides methods to execute either the Web Artifact or Web POST profile from within an application as opposed to a web browser.

com.sun.identity.saml.assertion

This package contains the classes needed to stand for, transform, and integrate, an XML assertion into the application. For example, Code Example 8-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 8-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 class defines a number of XML attributes (and some utility methods) common to all SAML elements. It also contains all SAML-related exceptions.

com.sun.identity.saml.plugins

Identity Server 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 Identity Server instance processing the query or a server that is trusted by the Identity Server 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 Identity Server instance processing the query, or an assertion issued by a server that is trusted by the Identity Server 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.




com.sun.identity.saml.xmlsig

All SAML assertions, requests and responses may be signed using this signature API. This package contains the classes needed to sign and verify.


SAML Service Samples

There are several samples that can be accessed from the Identity Server installation. These samples illustrate how the SAML service can be used in different ways. They include:

Previous     Contents     Index     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.
Last Updated December 02, 2002