Part IV SAML Administration and Application Programming Interfaces

• Chapter 9, SAML Administration

• Chapter 10, Application Programming Interfaces

Chapter 9 SAML Administration

Sun Java™ System Access Manager uses the Security Assertion Markup Language (SAML) as the means for exchanging security information. SAML uses an eXtensible Markup Language (XML) framework to achieve interoperability between vendor platforms that provide SAML assertions. This chapter explains SAML and defines how it is used within Access Manager.

This chapter covers the following topics:

• SAML Overview

• Elements of SAML

• SAML Attributes

• SAML API

• SAML Samples

SAML Overview

SAML is an open-standard protocol that defines user authentication, entitlements, and attribute information in XML documents. The Organization for the Advancement of Structured Information Standards (OASIS) drives the development of SAML 1.0 and 1.1, the versions supported in Access Manager 7 2005Q4.

For information and specifications, see the OASIS Security Services (SAML) Technical Committee web site.

The SAML documents can be used to exchange security information between an authority and a trusted partner site. The security information that is exchanged deals with a subject’s authentication status, access authorization, and attribute information. A subject is an entity in a particular domain. A person identified by an email address is a subject, as might be a printer. A SAML authority, sometimes called the asserting party, is a platform or application that has been integrated with the SAML API, allowing it to relay security information. Trusted partner sites receive the security information and rely on its authenticity.

All domains need to form a trust relationship before they can share information about a subject’s identity. How this is accomplished is beyond the scope of this guide.

Comparison of SAML and Liberty Specifications

SAML was designed by vendors to address the issue of cross-domain single sign-on. The Liberty Alliance Project was formed to develop technical specifications that would solve business process problems. These issues include single sign-on, but also incorporate protocols for account linking and consent, among others. SAML, on the other hand, does not solve issues such as privacy, single logout, and federation termination.

The SAML 1.0 and 1.1 specifications and the Liberty Alliance Project specifications do not compete with one another. They are complementary. In fact, the Liberty Alliance Project specifications leverage profiles from the SAML specifications. The decision of whether to use SAML or the Liberty specifications depends on your goal. In general, SAML should suffice for single sign-on basics. The Liberty Alliance Project specifications can be used for more sophisticated functions and capabilities, such as global sign-out, attribute sharing, web services. The following table lists the benefits of the two.

SAML Version 2.0 has been integrated into the Liberty Alliance Project specifications. This version is planned for implementation in an upcoming release of Access Manager.

SAML Architecture in Access Manager

SAML security information is expressed in the form of an assertion about a subject. 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 identity attributes. Assertions are issued by the SAML authority, and received by partner sites defined by 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. The following figure illustrates how SAML interacts with the other components in Access Manager.

Although Federation (as described in Chapter 3, Federation) integrates aspects of the SAML specifications, its usage of SAML is independent of the SAML component as described in this chapter.

Figure 9–1 SAML Interaction in Access Manager

SAML allows Access Manager to work in the following ways:

• Users can authenticate using Access Manager and access trusted partner sites without having to reauthenticate.

  ---

  Note –

  This single sign-on process is independent of the proprietary Access Manager process discussed in the Sun Java System Access Manager 7 2005Q4 Administration Guide.

  ---

• Access Manager acts as a policy decision point, allowing external applications to access user authorization information for the purpose of granting or denying access to their resources. For example, employees of an organization can be allowed to order office supplies from suppliers if they are authorized to do so.

• Access Manager acts as both an attribute authority (allowing trusted partner sites to query a subject’s attributes) and an authentication authority (allowing trusted partner sites to query a subject’s authentication information).

• Two parties in different security domains can validate each other for the purpose of performing business transactions.

• The SAML API can be used to build Authentication, Authorization Decision, and Attribute Assertions.

• The SAML service permits an XML-based digital signature signing and verifying functionality to be plugged into it.

Using SAML

The SAML can be accessed using a web browser or the SAML API. An end user authenticates to Access Manager using a web browser and, once authorized to do so, accesses URLs from trusted partner sites. Developers integrate the API into their applications to exchange security information with Access Manager. For example, a Java application can use the SAML API to achieve 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. For more information, see SAML API.

Elements of SAML

The following sections describe the elements of the SAML component:

• Assertion Types

• Profile Types

• SAML SOAP Receiver

Assertion Types

SAML assertions are a declaration of facts about a principal. For example, an assertion can be made that a particular client was granted update privileges to a specific database resource at a certain time. Assertions are constructed in XML based on the SAML assertion schema. Assertions are built from the user’s session information and optional attribute information using the siteAttributeMapper class. For more information, see SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces.

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

The SAML specification provides for different types of assertions:

• An authentication assertion declares that the specified subject has been authenticated by a particular means at a particular time. This information is declared in an AuthenticationStatement element. In Access Manager, the Authentication Service is the authentication authority. The following code example illustrates a sample authentication assertion.

  <?xml version="1.0" encoding="UTF-8" ?> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" MajorVersion="1" MinorVersion="0" AssertionID="random-182726" Issuer="sunserver.example.com" IssueInstant="2001-11-05T17:23:00GMT-02:00"> <saml:AuthenticationStatement AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password" AuthenticationInstant="2001-11-05T17:22:00GMT-02:00"> <saml:Subject> <saml:NameIdentifier NameQualifier="example.com">John Doe </saml:NameIdentifier> </saml:Subject> </saml:AuthenticationStatement> </saml:Assertion>

• An attribute assertion declares that the specified subject is associated with the specified attribute. This information is declared in an AttributeStatement element. The identity data store that is networked with Access Manager is the attribute authority.

• An authorization decision assertion declares that the specified subject’s request for access to a specified resource has been granted or denied. This information is declared in an AuthorizationDecisionStatement element. In Access Manager, the Policy Service is the authorization authority.

Profile Types

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

• The Web Browser Artifact Profile requires less processing overhead because there is no assertion signing as there is in the Web Browser POST Profile.

• The Web Browser Artifact Profile works without browsers enabled with JavaScript technology. It is considered more secure than the Web Browser POST Profile.

• The Web Browser POST Profile does not require SOAP. This profile is more firewall-friendly and involves fewer steps and less server-side processing.

The profile methods can be initiated through a web browser or the SAML API. For more information about the API method, see SAML API.

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. The SOAP communication should be either Basic Authentication or Client Certificate Authentication over SSL. Note that XML signing is a stronger alternative.

1. When an authenticated user attempts to access a trusted partner (generally by clicking a link), the user is directed to a transfer service at the authority site.

   In Access Manager, the transfer service is SAMLAwareServlet. The base of the transfer service URL is http(s)://access-manager-host.domain:port/deploy-uri/SAMLAwareServlet. The URL is appended with the location to which the user is requesting access (?TARGET=URL-of-destination).

2. SAMLAwareServlet receives the information and compares the SAML module’s list of Trusted Partners against the user’s TARGET location.

   Only targets that are configured in the Trusted Partners attribute of the SAML module are accessible. For more information about this attribute, see Trusted Partners.

3. Assuming the TARGET location was found in the list of Trusted Partners, SAMLAwareServlet looks for and validates the session token from the inbound request.

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

4. Assuming a valid session token, SAMLAwareServlet creates an artifact and a corresponding assertion.

   An artifact is carried as part of the URL and points to an assertion and its source. An artifact is not (and does not contain) security information. The assertion contains the security information. For more information, see SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces.

   ---

   Note –

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

   ---

5. SAMLAwareServlet redirects the user’s browser to the Artifact Receiver URL with a query string that contains the artifact and the original TARGET location.

   ---

   Note –

   In Access Manager, the Artifact Receiver URL and SAMLAwareServlet are the same. Other SAML implementations might not integrate the two functions.

   ---

6. At the Artifact Receiver URL, the artifact is extracted from the query string to locate the SOAP Receiver URL at the trusted partner site.

   The SAML API extracts the source ID from the artifact and uses it to locate the SOAP Receiver URL at the trusted partner site. For more information about the use of SOAP, see SAML SOAP Receiver.

7. A SOAP query that contains the artifact is sent to the SOAP Receiver URL at the trusted partner site that is requesting the assertion to which the artifact points.

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

9. The assertion is processed, mapping the user account information from the trusted partner site to the target site’s user account.

   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.

Figure 9–2 Web Browser Artifact Profile Interactions

A sample has been provided to test the Web Browser Artifact Profile function. See SAML Samples for 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 (without the use of an artifact). This interaction consists of two parts. The first part is between a user with a web browser and Access Manager. The second part is between the same user and the trusted partner site. The content of the POST should be signed to ensure message integrity, and the method of transport should be SSL.

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

• The first interaction of the Web Browser POST Profile is as follows:

  1. An authenticated user attempts to access a trusted partner site using a web browser (usually by clicking a link), and the user is redirected to a transfer service at the authority site.

     In Access Manager, the transfer service is SAMLPostProfileServlet. The base of the transfer service URL is http(s)://access-manager-host.domain:port/deploy-uri/SAMLPOSTProfileServlet. This URL is appended with the location to which the user is requesting access (?TARGET=URL-of-destination).

     ---

     Note –

     SAMLPostProfileServlet provides functions for both Web Browser POST Profile interactions.

     ---

  2. Access Manager obtains the TARGET location from the request and matches it against the trusted partners configured in the Trusted Partners attribute of the SAML module.

     For more information, see Trusted Partners.

  3. Access Manager generates an assertion using the AssertionManager class of the SAML API.

     For information about the AssertionManager class, see com.sun.identity.saml Package.

  4. Access Manager forms, signs, and Base64 encodes a SAMLResponse that contains the assertion.

  5. Access Manager generates an HTML form that contains both the SAMLResponse and the TARGET as parameters and posts the form as an HTTP response back to the user’s browser.

  6. The user’s browser is then directed to the location based on this information.

• The second interaction of the Web Browser POST Profile is as follows:

  1. The trusted partner site obtains the TARGET and SAMLResponse from the redirected request.

  2. The trusted partner site decodes the SAMLResponse, verifies the signature on the SAMLResponse, and obtains and verifies the SAML response.

     The trusted partner site also verifies the assertion inside the SAMLResponse and enforces single sign-on policy.

  3. Assuming a positive authentication, the trusted partner site obtains or creates an SSOToken and redirects the authenticated user to the TARGET location.

Figure 9–3 Web Browser POST Profile Interactions

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

Single-Use Policy With POST Profile

According to the SAML specifications, the trusted partner site must ensure a single-use policy for SSO assertions that are communicated using the Web Browser POST Profile. SAMLPOSTProfileServlet maintains a store of SSO assertion identifiers and the time that they expire. When an assertion is received, the servlet first checks for an entry in the map. If an entry exists, the servlet returns an error. If an entry does not exist, the assertion identifier and expiration time are saved to the map. POSTCleanUpThread removes expired assertion identifiers periodically.

SAML SOAP Receiver

Assertions are exchanged between Access Manager and inquiring parties using the <Request> and <Response> XML constructs defined in the SAML specification. These SAML constructs are then integrated into SOAP messages for transport.

A SAML <Request> can contain queries for authentication status, authorization decisions, attribute information, and one or more assertion identifier references or artifacts.

Access Manager uses SOAP, a message communications specification that integrates XML and HTTPS, to transport the SAML constructs. The request is received by SAML SOAP Receiver, a servlet that receives a SOAP message, extracts the SAML request, and responds with another SOAP message that contains the requested assertion. SAML SOAP Receiver responds to queries for authentication, attributes, or authorization decisions (including those that have an artifact) by returning assertions. The access URL for SAML SOAP Receiver is http(s)://access-manager-host.domain:port/deploy-uri/SAMLSOAPReceiver.

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> and <Response> elements are enclosed in the message body. A client transmits a SAML <Request> element within the body of a SOAP message to an entity.

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

The following two samples illustrate a SOAP exchange for the Web Browser Artifact Profile. The first is a request for an authentication assertion.

Example 9–1 SOAP Request for Authentication Assertion Using Web Browser Artifact Profile

POST /authn HTTP/1.1
Host: idp.example.com
Content-type: text/xml
Content-length: nnnn
<soap-env:Envelope
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:Header/>
<soap-env:Body>
<samlp:Request xmlns="urn:oasis:names:tc:SAML:1.0:protocol"
	xmlns:lib="http://projectliberty.org/schemas/core/2002/12"
	xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
	xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	IssueInstant="2002-12-12T10:08:56Z"
	MajorVersion="1"
	MinorVersion="0"
	RequestID="e4d71c43-c89a-426b-853e-a2b0c14a5ed8"
	id="ericssonb6dc3636-f2ad-42d1-9427-220f2cf70ec1"
	xsi:type="lib:SignedSAMLRequestType">
	<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
		<ds:SignedInfo>
			<ds:CanonicalizationMethod
				Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
			</ds:CanonicalizationMethod>
			<ds:SignatureMethod
				Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1">
			</ds:SignatureMethod>
			<ds:Reference URI="#ericssonb6dc3636-f2ad-42d1-9427-220f2cf70ec1">
				<ds:Transforms>
					<ds:Transform
						Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature">
					</ds:Transform>
					<ds:Transform
						Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
					</ds:Transform>
				</ds:Transforms>
				<ds:DigestMethod
					Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
				</ds:DigestMethod>
				<ds:DigestValue>+k6TnolGkIPKZlpUQVyok8dwkuE=</ds:DigestValue>
			</ds:Reference>
		</ds:SignedInfo>
		<ds:SignatureValue>
			wXJMVoPO1V1jFnWJPyOWqP5Gqm8A1+/2b5gNzF4L4LMu4yEcRtttLdPPT3bvhwkwHXjL9
			NuOFumQ5YEyiVzlNcjAxX0LfgwutvEdJb748IU4L+8obXPXfqTZLiBK1RbHCRmRvjlPIu
			22oGCV6EwuiWRvOD6Ox9svtSgFJ+iXkZQ
		</ds:SignatureValue>
		<ds:KeyInfo>
			<ds:X509Data>
			<ds:X509Certificate>
			MIIDMTCCApqgAwIBAgIBHDANBgkqhkiG9w0BAQQFADCBlTELMAkGA1UEBhMCVVMxCzAJB
			gNVBAcTAlNGMRkwFwYDVQQKExBMaWJlcnR5IEFsbGlhbmNlMRQwEgYDVQQLEwtJT1AgVG
			VzdGVyczEiMCAGA1UEAxMZTGliZXJ0eSBUZXN0ZXJzIENlcnRpZmllcjEkMCIGCSqGSIb
			3DQEJARYVcnJvZHJpZ3VlekBuZW9zb2wubmV0MB4XDTAyMTIwNDE1NTg0NFoXDTEyMTIw
			MTE1NTg0NFowgasxCzAJBgNVBAYTAlVTMQswCQYDVQQHEwJTRjEkMCIGA1UEChMbTGliZ
			XJ0eSBBbGxpYW5jZSBlcmljc3Nvbi1hMSYwJAYDVQQLEx1JT1AgVGVzdGVycyBlcmljc3
			Nvbi1hIHNpZ25lcjEXMBUGA1UEAxMOZXJpY3Nzb24tYS5pb3AxKDAmBgkqhkiG9w0BCQE
			WGXJyb2RyaWd1ZXpAZXJpY3Nzb24tYS5pb3AwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJ
			AoGBAPUoGYvJxQc5jzDnJ14TV6TaTbB3fH95ju24Z0y6HQxm6gXdJSAoWh7/AIes4UcV0
			9DC2kKS6Vow2YoXt2LIyH9HWH2tEUt1jS/PUeBHEWcW3tFezM6jh5GG5rCuVPZaW9eoGU
			bFPSzOPFKUAwdHUXSDWufY1KZ93IxhOBeZgg6VAgMBAAGjeTB3MEoGCWCGSAGG+EIBDQQ
			9FjtUaGlzIHNpZ25pbmcgY2VydCB3YXMgY3JlYXRlZCBmb3IgdGVzdGluZy4gRG8gbm90
			IHRydXN0 IGl0LjAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIEMDALBgNVHQ8EBAMC
			BsAwDQYJKoZIhvcNAQEEBQADgYEAR/HSgBpAprQwQVyWDE9pCaiduKv4/W/+hrdpXlVKS
			r6TIlg4ouDCQJNos7tNuG9ZAbfWtHvCss51N2cfAzfns/DKqxRqcsxzL5ZUBksPpmsDob
			oopUv6Xm8RFsi7yB9AGaVuqObeY/+m70nOu03O+FlMN3U1k2E3rOKXlU1noC0
			</ds:X509Certificate>
			</ds:X509Data>
		</ds:KeyInfo>
	</ds:Signature>
<samlp:AssertionArtifact>
	AAM1uXw6+f+jyA/4XuFHqPl7QDvc/LIQL9+t7YQtG1Gwk9bph0Adl+o+
</samlp:AssertionArtifact>
</samlp:Request>
</soap-env:Body>
</soap-env:Envelope>

In response to the request, SAML SOAP Receiver must return either a <Response> element within the body of another SOAP message or a SOAP fault code (error message) for every request received. The following sample is a response that contains an authentication assertion.

Example 9–2 SOAP Response to SOAP Request for Web Browser Artifact Profile

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: nnnn
<soap-env:Envelope
	xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
	<soap-env:Header/>
	<soap-env:Body>
		<samlp:Response
			xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
			InResponseTo="RPCUk2ll+GVz+t1lLURp51oFvJXk"
			IssueInstant="2002-10-31T21:42:13Z" 
			MajorVersion="1" MinorVersion="0"
			Recipient="http://localhost:8080/sp"
			ResponseID="LANWfL2xLybnc+BCwgY+p1/vIVAj">
			<samlp:Status>
				<samlp:StatusCode
					xmlns:qns="urn:oasis:names:tc:SAML:1.0:protocol"
					Value="qns:Success">
				</samlp:StatusCode>
			</samlp:Status>
			<saml:Assertion
				xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
				xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
				xmlns:lib="http://projectliberty.org/schemas/core/2002/12"
				xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				AssertionID="SqMC8Hs2vJ7Z+t4UiLSmhKOSUO0U"
				InResponseTo="RPCUk2ll+GVz+t1lLURp51oFvJXk"
				IssueInstant="2002-10-31T21:42:13Z" 
				Issuer="http://host:8080/idp"
				MajorVersion="1" MinorVersion="0"
				xsi:type="lib:AssertionType">
				<saml:Conditions
					NotBefore="2002-10-31T21:42:12Z"
					NotOnOrAfter="2002-10-31T21:42:43Z">
					<saml:AudienceRestrictionCondition>
						<saml:Audience>http://localhost:8080/sp</saml:Audience>
					</saml:AudienceRestrictionCondition>
				</saml:Conditions>
				<saml:AuthenticationStatement
					AuthenticationInstant="2002-10-31T21:42:13Z"
					AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
					xsi:type="lib:AuthenticationStatementType">
					<saml:Subject xsi:type="lib:SubjectType">
						<saml:NameIdentifier>
							C9FfGouQdBJ7bpkismYgd8ygeVb3PlWK
						</saml:NameIdentifier>
						<saml:SubjectConfirmation>
							<saml:ConfirmationMethod>
								urn:oasis:names:tc:SAML:1.0:cm:artifact-01
							</saml:ConfirmationMethod>
						</saml:SubjectConfirmation>
						<lib:IDPProvidedNameIdentifier>
							C9FfGouQdBJ7bpkismYgd8ygeVb3PlWK
						</lib:IDPProvidedNameIdentifier>
					</saml:Subject>
				</saml:AuthenticationStatement>
				<ds:Signature>
					<ds:SignedInfo>
						<ds:CanonicalizationMethod
							Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
						</ds:CanonicalizationMethod>
					<ds:SignatureMethod 
						Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1">
					</ds:SignatureMethod>
					<ds:Reference URI="">
					<ds:Transforms>
					<ds:Transform 
					Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature">
					</ds:Transform>
					<ds:Transform 
					Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
					</ds:Transform>
					</ds:Transforms>
					<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
					</ds:DigestMethod>
					<ds:DigestValue>ZbscbqHTX9H8bBftRIWlG4Epv1A=</ds:DigestValue>
					</ds:Reference>
				</ds:SignedInfo>
				<ds:SignatureValue>
					H+q3nC3jUalj1uKUVkcC4iTFClxeZQIFF0nvHqPS5oZhtkBaDb9qI
					TA7gIkotaB584wXqTXwsfsuIrwT5uL3r85Rj7IF6NeCeiy3K0+z3u
					ewxyeZPz8wna449VNm0qNHYkgNak9ViNCp0/ks5MAttoPo2iLOfaK
					u3wWG6d1G+DM=
				</ds:SignatureValue>
			</ds:Signature>
		</saml:Assertion>
	</samlp:Response>
</soap-env:Body>
</soap-env:Envelope>

The entities requesting and responding with SAML must not include more than one SAML request or response per SOAP message. They must also not include any additional XML elements in the SOAP body.

Protecting SAML SOAP Receiver

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

• NOAUTH

• BASICAUTH

• SSL

• SSLWITHBASICAUTH

This value is configured as a subattribute of the Trusted Partners attribute in the SAML module. The default authentication type is NOAUTH. If SSL authentication is to be specified, it is configured in the SOAPUrl field with the https protocol. For more information, see Trusted Partners.

To Configure Access Manager for Basic Authentication

Basic authentication allows a provider originating a request to authenticate itself by transmitting a username and password. The credentials are presented in response to a challenge from the provider to which the request is being sent. You need to configure Access Manager to support basic authentication using the following procedure.

1. In the Access Manager Console, click the Federation tab.

2. Under Federation, click the SAML tab.

3. Select New under the Trusted Partners attribute.

4. Select the Web Browser Artifact Profile (Artifact) under Source and click Next.

5. Type a value for the Source ID attribute.

   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 Site Identifiers.

6. Enter the SOAP Receiver URL for the site you are configuring as a value for the SOAP URL attribute.

   General information on SOAP endpoints is in SAML SOAP Receiver.

7. Select BASICAUTH or SSLWITHBASICAUTH (if the endpoint is configured with Secure Sockets Layer) as the authentication type.

8. Enter a user identifier for the user on the partner side being used to protect their SOAP Receiver.

9. Enter and reenter the password associated with the user on the partner side being used to protect their SOAP Receiver.

10. Click Finish to complete the configuration.

11. Click Save to save the configuration.

SAML Attributes

The SAML module is configured by applying values to its attributes. amSAML.xml is the XML service file that defines the attributes. All SAML attributes are global in that the values applied to them are carried across the Access Manager configuration and inherited by every organization defined in the instance of Access Manager.

For more information on service files, see Sun Java System Access Manager 7 2005Q4 Administration Guide.

Most attributes in the SAML module can be configured either through the Access Manager Console or the XML service file. amSAML.xml Attributes lists the attributes that can only be configured by modifying the amSAML.xml file. Console Attributes lists the attributes that can be configured using the console or the XML service file.

amSAML.xml Attributes

The following attributes can only be configured through the amSAML.xml file using the amadmin command-line interface.

• iplanet-am-saml-cleanup-interval is used to specify how often the internal thread is run to clean up expired assertions from the internal data store. The default is 180 seconds.

• iplanet-am-saml-assertion-max-number is used to specify the maximum number of assertions that the server can hold at one time. No new assertion is created if the maximum number is reached. The default value is 0, which means no limit.

To Modify Attributes in the amSAML.xml File

1. Duplicate the amSAML.xml service file and make any changes to the attributes.

2. Delete the old amSAML.xml service file.

3. Use amadmin to reload the newly modified amSAML.xml file.

   For more information on amadmin, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.

Console Attributes

The following SAML attributes can be configured by using the Access Manager Console or by modifying amSAML.xml as described in amSAML.xml Attributes. When viewed using the Console, the SAML attributes are separated into the following groups:

• Properties Group

• Assertion

• Artifact

• Signing

Properties Group

The attributes in the Properties group are as follows:

• Target Specifier

• Site Identifiers

• Trusted Partners

• Target URLs

Target Specifier

This attribute assigns a name to the destination site URL value that is used in the redirects discussed in Profile Types. The default is TARGET. Only sites configured in the Trusted Partners attribute can be specified as a TARGET. For information, see Trusted Partners.

Site Identifiers

This attribute defines any site that is hosted by the server on which Access Manager is installed. A default value is defined for the host during installation (with values retrieved from AMConfig.properties), and a Site ID is automatically generated. Multiple entries are possible (for example, load balancing or multiple instances of Access Manager sharing the same Directory Server) although the default site identifier should always remain an entry.

If configuring SAML for SSL (in both the source and destination site), ensure that the protocol defined in the Instance ID attribute is HTTPS//.

To Configure a Site Identifier

You may also edit or duplicate entries already listed.

1. In the Access Manager Console, click the Federation tab.

2. Under Federation, click the SAML tab.

3. Select New under the Site Identifiers attribute.

4. Enter values for the following attributes:

   Instance ID

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

   Site ID

   This identifier is generated for each site, although the value will be the same for multiple servers behind a load balancer. To obtain this identifier manually, type the following at the command line:

   % #java -classpath AM-classpath \ com.sun.identity.saml.common.SAMLSiteID \protocol://host:port

   For more information, see com.sun.identity.saml.common Package.

   Issuer Name

   The value of this property is host:port.

5. Click OK.

Trusted Partners

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

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

Before configuring a trusted partner, you must 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 receives a single sign-on assertion). Following is the procedure for configuring a trusted partner.

To Configure a Trusted Partner

The Trusted Partners attribute can contain one or more entries. Each entry is configured based on the site's defined role. 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 which profile it uses to receive assertions.

1. In the Access Manager Console, click the Federation tab.

2. Under Federation, click the SAML tab.

3. Select New under the Trusted Partners attribute.

4. Select the role (Destination or Source) of the partner site that you are configuring by checking the appropriate profiles used to communicate with it and click Next.

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

5. Type values for the Common Settings subattributes based on the selected roles.

   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 Site Identifiers.

   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 Trusted Partners.

   ---

   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.

   ---

   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 one of the included interfaces:

   • com.sun.identity.saml.plugins.SiteAttributeMapper

   • com.sun.identity.saml.plugins.PartnerSiteAttributeMapper

   If no class is defined, no attributes will be included in the assertion. For more information, see SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces.

   Version

   The SAML version used (1.0 or 1.1) to send SAML requests. If this parameter is not defined, the following default values (defined in AMConfig.properties) are used:

   • com.example.identity.saml.assertion.version=1.1

   • com.example.identity.saml.protocol.version=1.1

   Account Mapper

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

   • com.sun.identity.saml.plugins.AccountMapper

   • com.sun.identity.saml.plugins.PartnerAccountMapper

   If no class is defined, no attributes will be included in the assertion. For more information, see AccountMapper and PartnerAccountMapper Interfaces.

   Certificate

   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.

   Host List

   A list of the IP addresses, the DNS host name, or the Certificate name 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.

   Issuer

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

6. Type values for the Destination subattributes.

   Artifact: SAML URL

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

   Post: Post URL

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

   SOAP Query: Attribute Mapper

   The class that is used to obtain single sign-on information from a query. You need to implement an attribute mapper from the included interface. If no class is specified, the DefaultAttributeMapper will be used. For more information, see com.sun.identity.saml.plugins Package.

   SOAP Query: Action Mapper

   The class that is used to get single sign-on information and map partner actions to Access Manager authorization decisions. You need to implement an action mapper from the included interface. If no class is specified, the DefaultActionMapper will be used. For more information, see com.sun.identity.saml.plugins Package.

7. Type values for the Source subattributes.

   Artifact: SOAP URL

   The URL to the SAML SOAP Receiver. See SAML SOAP Receiver.

   Authentication Type

   Authentication types that can be used with SAML:

   • NOAUTH

   • BASICAUTH

   • SSL

   • SSLWITHBASICAUTH

   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. For more information, see Trusted Partners.

   User

   When Basic Authentication 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 Basic Authentication 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.

8. Click Finish to complete the configuration.

Target URLs

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

Do not use test URLs or any other additional URLs in a POST.

To configure this attribute, type values for the following subattributes:

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

The port number, such as 58080.

Path

The URI, such as /amserver/console.

Assertion

The attributes in the Assertion group are as follows:

• Assertion Timeout

• Assertion Skew Factor For notBefore Time

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.

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

The attributes in the Artifact group are as follows:

• Artifact Timeout

• SAML Artifact Name

For more information about artifacts, see Web Browser Artifact Profile.

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.

Signing

The attributes in the Signing group are as follows:

• Sign SAML Assertion

• Sign SAML Request

• Sign SAML Response

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.

All SAML responses used by the Web Browser POST Profile are digitally signed whether or not this feature is enabled.

SAML API

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

• com.sun.identity.saml Package

• com.sun.identity.saml.assertion Package

• com.sun.identity.saml.common Package

• com.sun.identity.saml.plugins Package

• com.sun.identity.saml.protocol Package

• com.sun.identity.saml.xmlsig Package

For more detailed information, including methods and their syntax and parameters, see the Java API reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

com.sun.identity.saml Package

This package contains the AssertionManager and SAMLClient classes.

AssertionManager Class

The AssertionManager class provides interfaces and methods to create and get assertions, authentication assertions, and assertion artifacts. This class is the connection between the SAML specification and Access Manager. Some of the methods include the following:

• createAssertion creates an assertion with an authentication statement based on an Access Manager SSO Token ID.

• createAssertionArtifact creates an artifact that references an assertion based on an Access Manager SSO Token ID.

• getAssertion returns an assertion based on the given parameter (given artifact, assertion ID, or query).

SAMLClient Class

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

• getAssertionByArtifact returns an assertion for a corresponding artifact.

• doWebPOST executes the Web Browser POST Profile.

• doWebArtifact executes the Web Browser Artifact Profile.

com.sun.identity.saml.assertion Package

This package contains the classes needed to create, manage, and integrate an XML assertion into an application. The following code example illustrates how to use the Attribute class and getAttributeValue method to retrieve the value of an attribute. From an assertion, call the getStatement() method to retrieve a set of statements. If a statement is an attribute statement, call the getAttribute() method to get a list of attributes. From there, call getAttributeValue() to retrieve the attribute value.

Example 9–3 Sample Code to Obtain 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 Package

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

com.sun.identity.saml.plugins Package

Access Manager provides service provider interfaces (SPIs), three of which have default implementations. The default implementations of these SPIs can be altered, or brand new ones written, based on the specifications of a particular customized service. The implementations are then used to integrate SAML into the custom service. Currently, the package includes the following interfaces:

• AccountMapper and PartnerAccountMapper Interfaces

• SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces

• AttributeMapper Interface

• ActionMapper Interface

AccountMapper and PartnerAccountMapper Interfaces

AccountMapper and PartnerAccountMapper are interfaces that need to be implemented by each partner site. The implemented class maps the partner site's user accounts to user accounts configured in Access Manager for purposes of single sign-on. For example, if single sign-on is configured from site A to site B, a site-specific account mapper can be developed and defined in the Trusted Partners subattribute of site B's Trusted Partners profile. When site B processes the assertion received, it locates the corresponding account mapper by retrieving the source ID of the originating site. Either SPI can be implemented although PartnerAccountMapper has one benefit over AccountMapper: it takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. The AccountMapper interface uses only the subject of the assertion as a parameter. The default implementation is com.sun.identity.saml.plugin.DefaultAccountMapper. If a site-specific account mapper is not configured, this default mapper is used.

Turning on the Debug Service in the AMConfig.properties file logs additional information about the account mapper, for example, the user name and organization to which the mapper has been mapped. For more information about the AMConfig.properties file, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.

SiteAttributeMapper and PartnerSiteAttributeMapper Interfaces

SiteAttributeMapper and PartnerSiteAttributeMapper are interfaces that need to be implemented by each partner site. The implemented class defines a list of attributes to be returned as elements of the AttributeStatements in an authentication assertion. By default, when Access Manager creates an assertion and no mapper is specified, the authentication assertion only contains authentication statements. If a partner site wants to include attribute statements, it needs to implement one of these mappers. This class would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion. Either SPI can be implemented although PartnerSiteAttributeMapper has one benefit over SiteAttributeMapper: there is an additional targetURL parameter that enables the partner to include different sets of attributes to target different applications.

The default behavior is that no attribute statements are returned unless specified by the plug-in.

AttributeMapper Interface

AttributeMapper is an interface used in conjunction with an AttributeQuery class When a site receives an attribute query, this mapper obtains the SSOToken or an assertion (containing an authentication statement) from the query. The retrieved information is used to convert the attributes in the query to the corresponding Access Manager attributes. A default attribute mapper is provided if no other implementation is defined.

For more information, see AttributeQuery Class.

ActionMapper Interface

ActionMapper is an interface used to obtain single sign-on information and to map partner actions to Access Manager authorization decisions. A default action mapper is provided if no other implementation is defined.

com.sun.identity.saml.protocol Package

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

AuthenticationQuery Class

The AuthenticationQuery class represents a query for an authentication assertion. When an identity attempts to access a trusted partner web site, a SAML request with an AuthenticationQuery inside is directed to the authority site.

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, the value of the NameIdentifier should be the same as the one in the SSOToken.

AttributeQuery Class

The AttributeQuery class represents a query for an identity’s attributes. When an identity attempts to access a trusted partner web site, a SAML request with an AttributeQuery is directed to the authority site.

You can develop an attribute mapper to obtain an SSOToken, or an assertion that contains an AuthenticationStatement from the query. If no attribute mapper for the querying site is defined, the DefaultAttributeMapper will be used. To use the DefaultAttributeMapper, the query should have either the SSOToken or an assertion that contains an AuthenticationStatement in the SubjectConfirmationData element. If an SSOToken is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If an assertion is used, the 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.

In the DefaultAttributeMapper, a subject’s attributes can be queried using another subject’s SSOToken if the SSOToken has the privilege to retrieve the attributes.

For a query using the DefaultAttributeMapper, any matching attributes found 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. The value of the userServiceNameList property is user service names separated by a comma.

AuthorizationDecisionQuery Class

The AuthorizationDecisionQuery class represents a query about a principal’s authority to access protected resources. When an identity attempts to access a trusted partner web site, a SAML request with an AuthorizationDecisionQuery is directed to the authority site.

You can develop an ActionMapper to obtain the SSOToken ID and retrieve the authentication decisions for the actions defined in the query. If no ActionMapper for the querying site is defined, the DefaultActionMapper will be used. To use the DefaultActionMapper, the query should have the SSOToken ID in the SubjectConfirmationData element of the Subject. If the SSOToken ID is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If a NameIdentifier is present, the information in the SSOToken must be the same as the information in the NameIdentifier.

When using web agents, the DefaultActionMapper handles actions in the namespace urn:oasis:names:tc:SAML:1.0:ghpp only. Web agents serve the policy decisions for this action namespace.

The authentication information can also be passed through the Evidence element in the query. Evidence can contain an AssertionIDReference, 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 of the Evidence element should be the same as the one in the query.

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

The following example illustrates one of many ways to form an authorization decision query that will return a decision.

Example 9–4 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 Package

All SAML assertions, requests, and responses can be signed using this signature package. It contains SPI that are implemented to plug in proprietary XML signatures. This package contains classes needed to sign and verify using XML signatures. By default, the keystore provided with the Java Development Kit is used and the key type is DSA. The configuration properties for this functionality are in the AMConfig.properties file. For information about these properties, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide. For details on how to use the signature functionality, see SAML Samples.

SAML Samples

You can access several SAML-based samples from the Access Manager installation in /AccessManager-base/SUNWam/samples/saml. These samples illustrate how the SAML service can be used in different ways, including the following:

• A sample that serves as the basis for using the SAML client API. This sample is located in /AccessManager-base/SUNWam/samples/saml/client.

• A sample that illustrates how to form a Query, write an AttributeMapper, and send and process a SOAP message using the SAML SDK. This sample is located in /AccessManager-base/SUNWam/samples/saml/query.

• A sample application for achieving SSO using either the Web Browser Artifact Profile or the Web Browser POST Profile. This sample is located in /AccessManager-base/SUNWam/samples/saml/sso.

• A sample that illustrates how to use the XMLSIG API and explains how to configure for XML signing. This sample is located in /AccessManager-base/SUNWam/samples/saml/xmlsig.

Each sample includes a README file with information and instructions on how to use it.

Chapter 10 Application Programming Interfaces

Sun Java System Access Manager provides a framework for identity federation and creating, discovering, and consuming identity web services. This framework includes a graphical user interface for Liberty-based web services as well as application programming interfaces (APIs). This chapter provides information on the APIs that do not have a corresponding graphical user interface (GUI).

This chapter covers the following topics:

• Public Interfaces

• Common Service Interfaces

• Common Security API

• Interaction Service

• PAOS Binding

Public Interfaces

The following list describes all of the public APIs you can use to deploy Liberty-enabled components or extend the core services. Packages that are part of a web service that has a GUI are described in the corresponding chapters of this book. Packages that are used solely on the back end are described in this chapter. Links to those sections are also provided. For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

Common Service Interfaces

This section summarizes classes that can be used by all Liberty-based Access Manager service components, as well as interfaces common to all Liberty-based Access Manager services. The packages that contain the classes and interfaces are:

• com.sun.identity.liberty.ws.common Package

• com.sun.identity.liberty.ws.interfaces Package

com.sun.identity.liberty.ws.common Package

This package includes classes common to all Liberty-based Access Manager service components.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

com.sun.identity.liberty.ws.interfaces Package

This package includes interfaces that can be implemented to add their corresponding functionality to each Liberty-based Access Manager web service.

com.sun.identity.liberty.ws.interfaces.Authorizer Interface

This interface, once implemented, can be used by each Liberty-based web service component for access control.

The com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer class is the implementation of this interface for the Discovery Service. For more information, see Chapter 7, Discovery Service. The com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer class is the implementation for the Liberty Personal Profile Service. For more information, see Chapter 6, Data Services.

The Authorizer interface enables a web service to check whether a web service consumer (WSC) is allowed to access the requested resource. When a WSC contacts a web service provider (WSP), the WSC conveys a sender identity and an invocation identity. Note that the invocation identity is always the subject of the SAML assertion. These conveyances enable the WSP to make an authorization decision based on one or both identities. The Access Manager Policy Service performs the authorization based on defined policies.

See the Sun Java System Access Manager 7 2005Q4 Technical Overview for more information about policy management, single sign-on, and user sessions. See the Sun Java System Access Manager 7 2005Q4 Administration Guide for information about creating policy.

com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface

This interface is used to map a user DN to the resource identifier associated with it. Access Manager provides implementations of this interface.

• com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the Base64 encoded userIDs.

• com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the hex string of userID.

• com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper assumes the Resource ID format to be: providerID + "/" + the Base64 encoded userIDs.

A different implementation of the interface may be developed. The implementation class should be given to the provider that hosts the Discovery Service. The mapping between the providerID and the implementation class can be configured through the Classes For ResourceIDMapper Plugin attribute.

Common Security API

The Liberty-based security APIs are included in the com.sun.identity.liberty.ws.security package and the com.sun.identity.liberty.ws.common.wsse package.

com.sun.identity.liberty.ws.security Package

The com.sun.identity.liberty.ws.security package includes the SecurityTokenProvider interface for managing Web Service Security (WSS) type tokens. The following table describes the classes used to manage Liberty-based security mechanisms.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

com.sun.identity.liberty.ws.common.wsse Package

This package includes classes for creating security tokens used for authentication and authorization in accordance with the Liberty ID-WSF Security Mechanisms. Both WSS X.509 and SAML tokens are supported.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

Interaction Service

Providers of identity services often need to interact with the owner of a resource to get additional information, or to get their consent to expose data. The Liberty Alliance Project has defined the Liberty ID-WSF Interaction Service Specification to specify how these interactions can be carried out. Of the options defined in the specification, Access Manager has implemented the Interaction RequestRedirect Profile. In this profile, the WSP requests the connecting WSC to redirect the user agent (principal) to an interaction resource (URL) at the WSP. When the user agent sends an HTTP request to get the URL, the WSP has the opportunity to present one or more pages to the principal with questions for other information. After the WSP obtains the information it needs to serve the WSC, it redirects the user agent back to the WSC, which can now reissue its original request to the WSP.

Configuring the Interaction Service

While there is no XML service file for the Interaction Service, this service does have properties. The properties are configured upon installation in the AMConfig.properties file located in /AccessManager-base/SUNWam/lib and are described in the following table.

Interaction Service API

The Access Manager Interaction Service includes a Java package named com.sun.identity.liberty.ws.interaction. WSCs and WSPs use the classes in this package to interact with a resource owner. The following table describes the classes.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

PAOS Binding

Access Manager has implemented the optional Liberty Reverse HTTP Binding for SOAP Specification. This specification defines a message exchange protocol that permits an HTTP client to be a SOAP responder. HTTP clients are no longer necessarily equipped with HTTP servers. For example, mobile terminals and personal computers contain web browsers yet they do not operate HTTP servers. These clients, though, can use their browsers to interact with an identity service, possibly a personal profile service or a calendar service. These identity services could also be beneficial when the client devices interact with an HTTP server. The use of PAOS makes it possible to exchange information between user agent-hosted services and remote servers. This is why the reverse HTTP for SOAP binding is also known as PAOS; the spelling of SOAP is reversed.

Comparison of PAOS and SOAP

In a typical SOAP binding, an HTTP client interacts with an identity service through a client request and a server response. For example, a cell phone user (client) can contact the phone service provider (service) to retrieve stock quotes and weather information. The service verifies the user’s identity and responds with the requested information.

In a reverse HTTP for SOAP binding, the phone service provider plays the client role, and the cell phone client plays the server role. The initial SOAP request from the server is actually bound to an HTTP response. The subsequent response from the client is bound to a request.

PAOS Binding API

The Access Manager implementation of PAOS binding includes a Java package named com.sun.identity.liberty.ws.paos. This package provides classes to parse a PAOS header, make a PAOS request, and receive a PAOS response.

This API is used by PAOS clients on the HTTP server side. An API for PAOS servers on the HTTP client side would be developed by the manufacturers of the HTTP client side products, for example, cell phone manufacturers.

The following table describes the available classes in com.sun.identity.liberty.ws.paos. For more detailed API documentation, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

PAOS Binding Sample

A sample that demonstrates PAOS service interaction between an HTTP client and server is provided in the /AccessManager-base/SUNWam/samples/phase2/paos directory. The PAOS client is a servlet, and the PAOS server is a stand-alone Java program. Instructions on how to run the sample can be found in the Readme.html or Readme.txt file. Both files are included in the paos directory. The following code example is the PAOS client servlet.

Example 10–1 PAOS Client Servlet From PAOS Sample

import java.util.*;
import java.io.*;

import javax.servlet.*;
import javax.servlet.http.*;

import com.sun.identity.liberty.ws.paos.*;

import com.sun.identity.liberty.ws.idpp.jaxb.*;

public class PAOSClientServlet extends HttpServlet {

  public void doGet(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException {

      PAOSHeader paosHeader = null;
      try {
    paosHeader = new PAOSHeader(req);
      } catch (PAOSException pe1) {
    pe1.printStackTrace();

    String msg = "No PAOS header\\n";
    res.setContentType("text/plain");
    res.setContentLength(1+msg.length());
    PrintWriter out = new PrintWriter(res.getOutputStream());
    out.println(msg);
    out.close();

    throw new ServletException(pe1.getMessage());
      }

      HashMap servicesAndOptions = paosHeader.getServicesAndOptions();

      Set services = servicesAndOptions.keySet();

      String thisURL = req.getRequestURL().toString();
      String[] queryItems = { "/IDPP/Demographics/Birthday" };
      PAOSRequest paosReq = null;
      try {
    paosReq = new PAOSRequest(thisURL,
                  (String)(services.iterator().next()),
                  thisURL,
                  queryItems);
      } catch (PAOSException pe2) {
    pe2.printStackTrace();
    throw new ServletException(pe2.getMessage());
      }
      System.out.println("PAOS request to User Agent side --------------->");
      System.out.println(paosReq.toString());
      paosReq.send(res, true);
  }

  public void doPost(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException {

      PAOSResponse paosRes = null;
      try {
    paosRes = new PAOSResponse(req);
      } catch (PAOSException pe) {
    pe.printStackTrace();
    throw new ServletException(pe.getMessage());
      }

      System.out.println("PAOS response from User Agent side -------------->");
      System.out.println(paosRes.toString());

      System.out.println("Data output after parsing -------------->");

      String dataStr = null;
      try {
    dataStr = paosRes.getPPResponseStr();
      } catch (PAOSException paose) {
    paose.printStackTrace();
    throw new ServletException(paose.getMessage());
      }
      System.out.println(dataStr);

      String msg = "Got the data: \\n" + dataStr;

      res.setContentType("text/plain");
      res.setContentLength(1+msg.length());

      PrintWriter out = new PrintWriter(res.getOutputStream());

      out.println(msg);

      out.close();
  }
}

See Appendix A, Liberty-based and SAML Samples for information about all the sample code and files included with Access Manager.