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. It covers the following topics:
SAML is an XML-based standard for communicating authentication, authorization and attribute information amongst online partners. It allows businesses to securely send assertions between partnered organizations regarding the identity and entitlements of a principal. The Organization for the Advancement of Structured Information Standards (OASIS) Security Services Technical Committee is in charge of defining, enhancing, and maintaining the SAML specifications. SAML standardizes queries for, and responses that contain, user authentication, entitlements, and attribute information in an XML format. This format can then be used by a relying party to request security information about a principal from a SAML authority. A SAML authority, sometimes called the asserting party, is a platform or application that can relay security information. The relying party (or assertion consumer or requesting party) is a partner site that receives the security information. The exchanged information 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.
All parties in a SAML interaction 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.
SAML was designed 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 compares the benefits of the two.
Table 10–1 Comparison of the SAML and Liberty Alliance Project Specifications
SAML Uses |
Liberty Alliance Project Uses |
---|---|
Cross-domain single sign-on |
Single sign-on only after user federation |
No user federation |
User federation |
No privacy control, best for use within one company |
Built on top of SAML |
User identifier is sent in plain text |
User identifier is sent as a unique handle |
The Organization for the Advancement of Structured Information Standards (OASIS) drives the development of SAML. For information and specifications, see the OASIS Security Services (SAML) Technical Committee home page.
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.
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.
This single sign-on process is independent of the proprietary Access Manager process discussed in the Sun Java System Access Manager 7.1 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.
The SAML Service 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, attempts to access URLs on trusted partner sites. Developers, who have integrated the SAML API into their applications, are then able 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.
SAML defines message formats in XML for queries and responses. SAML queries are sent to a SAML authority and responses, in the form of SAML assertions, are returned via SOAP over HTTP, the request-response protocol used to carry SAML messages. The following sections describe these and other elements of SAML.
An entity can interact with a SAML authority using requests containing queries and responses containing assertions. AuthenticationQuery, AttributeQuery, and AuthorizationDecisionQuery XML tags containing requests for security information are wrapped within a <samlp:Request> XML tag and sent to a SAML authority. AuthenticationStatement, AttributeStatement, and AuthorizationDecisionStatement XML tags containing assertions of security information are wrapped within a <samlp:Response> XML tag and returned to the assertion consumer. See the following sections for more information.
A requesting party uses AuthenticationQuery, AttributeQuery, and AuthorizationDecisionQuery tags within a <samlp:Request> to ask for assertions about a particular entity from a SAML authority. Following is an example request containing an attribute query.
<samlp:Request xmlns:samlp="urn:oasis:names:tc:SAML:1.1:protocol" RequestID="s9c4a43c0265e904ca86f43c3e30034dd56582a79" MajorVersion="1" MinorVersion="1" IssueInstant="2006-01-09T11:33:48Z"> <samlp:AttributeQuery> <saml:Subject xmlns:saml="urn:oasis:names:tc:SAML:1.1:assertion"> <saml:NameIdentifier NameQualifier="dc=example,dc=com">uid=amadmin,dc=example,dc=com</saml:NameIdentifier> <saml:SubjectConfirmation> <saml:ConfirmationMethod>urn:com:sun:identity</saml:ConfirmationMethod> <saml:SubjectConfirmationData> </saml:SubjectConfirmationData> </saml:SubjectConfirmation> </saml:Subject> </samlp:AttributeQuery> </samlp:Request> |
A SAML authority uses AuthenticationStatement, AttributeStatement, and AuthorizationDecisionStatement tags within a <samlp:Response> to return information about an entity to the requesting party. Following is an example response containing an assertion. See Assertions for more information.
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:1.1:protoco" ResponseID="s757013615ab8ab95ffe272f9e377aa6ed823d030" InResponseTo="s9c4a43c0265e904ca86f43c3e30034dd56582a79" MajorVersion="1" MinorVersion="1" IssueInstant="2006-01-09T11:33:48Z" Recipient="10.17.246.43"> <samlp:Status> <samlp:StatusCode Value="samlp:Success"> </samlp:StatusCode> </samlp:Status> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.1:assertion" MajorVersion="1" MinorVersion="1" AssertionID="s1f3764242b274a835475d5433b8c62020a0e39a80" Issuer="dde280-3.france.sun.com:80" IssueInstant="2006-01-09T09:44:48Z" > <saml:Conditions NotBefore="2006-01-09T09:41:48Z" NotOnOrAfter="2006-01-09T09:51:48Z"> </saml:Conditions> <!-- statements go here --> </saml:Assertion> </samlp:Response> |
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 PartnerSiteAttributeMapper Interface.
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 within an AuthenticationStatement XML tag. In Access Manager, the Authentication Service is the authentication authority. The following code example illustrates a SAML assertion with an AuthenticationStatement.
<?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 within an AttributeStatement XML tag. The identity data store that is networked with Access Manager is the attribute authority. The following code example illustrates a SAML assertion with an AttributeStatement.
<?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:AttributeStatement> <saml:Subject> <saml:NameIdentifier NameQualifier="dc=example,dc=com"> uid=amadmin,dc=example,dc=com</saml:NameIdentifier> </saml:Subject> <saml:Attribute AttributeName="sn" AttributeNamespace="urn:sun:fm:samples:saml:query"> <saml:AttributeValue xmlns:saml="urn:oasis:names:tc:SAML:1.1:assertion">amadmin</saml:AttributeValue> </saml:Attribute> <saml:Attribute AttributeName="cn" AttributeNamespace="urn:sun:fm:samples:saml:query"> <saml:AttributeValue xmlns:saml="urn:oasis:names:tc:SAML:1.1:assertion">amadmin</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> |
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 within an AuthorizationDecisionStatement XML tag. In Access Manager, the Policy Service is the authorization authority.
The OASIS Security Services (SAML) Technical Committee has recently frozen this query in favor of using the eXtensible Access Control Markup Language (XACML). Future versions of Access Manager will reflect this.
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 the Web Browser Artifact Profile and the Web Browser POST Profile. Both profiles use HTTP. The profile methods can be initiated through a web browser or the SAML API. (For more information about the API method, see SAML API.) Either profile 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.
More information can be found in the following sections:
The Web Browser Artifact Profile is used when there is a back channel available to process an artifact. (An artifact is carried as part of the URL and points to an assertion which contains the security information regarding the requestor.) 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 artifact is sent via a browser and processed using SOAP. The SOAP communication should be either Basic Authentication or Client Certificate Authentication over SSL although XML signing is a stronger alternative. The Web Browser Artifact Profile is considered more secure than the Web Browser POST Profile (as discussed in Web Browser POST Profile).
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).
SAMLAwareServlet
receives
the information and compares the SAML Service’s list of Trusted
Partners against the user’s TARGET location.
Only targets that are configured in the Trusted Partners attribute of the SAML Service are accessible. For more information about this attribute, see Trusted Partners.
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.
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 PartnerSiteAttributeMapper Interface.
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.
SAMLAwareServlet
redirects
the user’s browser to the Artifact
Receiver URL
with a query string that contains the artifact
and the original TARGET location.
In Access Manager, the Artifact Receiver
URL
and SAMLAwareServlet
are
the same. Other SAML implementations might not integrate the two functions.
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.
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.
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.
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.
A sample has been provided to test the Web Browser Artifact Profile function. See SAML Samples for more information.
The Web Browser POST Profile is a front-channel profile that sends responses via the browser. It 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 Web Browser POST Profile is simpler than the Web Browser Artifact Profile (as discussed in Web Browser Artifact Profile).
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:
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).
SAMLPostProfileServlet
provides
functions for both Web Browser POST Profile interactions.
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.
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.
Access Manager forms, signs, and Base64 encodes a SAMLResponse that contains the assertion.
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.
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:
The trusted partner site obtains the TARGET and SAMLResponse from the redirected request.
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.
Assuming a positive authentication, the trusted partner site obtains or creates an SSOToken and redirects the authenticated user to the TARGET location.
A sample has been provided to test the Web Browser POST Profile function. See SAML Samples.
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.
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 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.
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.
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.
SAML
SOAP Receiver
The Access Manager administrator has the option of protecting the SAML SOAP Receiver
. The available methods
are:
NOAUTH
Specify NOAUTH if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is not protected by HTTP basic authentication.
BASICAUTH
Specify BASICAUTH if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is protected by HTTP basic authentication.
SSL
Specify SSL if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by HTTP basic authentication.
SSLWITHBASICAUTH
Specify SSLWITHBASICAUTH if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is protected by HTTP basic authentication.
If you are protecting the SAML SOAP receiver URL with HTTP basic authentication, you do so in the web container configuration and not in the Access Manager configuration. You do, however, supply the HTTP basic authentication user ID and password in the Access Manager configuration.
This value is configured as a sub-attribute 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.
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.
In the Access Manager Console, click the Federation tab.
Under Federation, click the SAML tab.
Select New under the Trusted Partners attribute.
Select the Web Browser Artifact Profile (Artifact) under Source and click Next.
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.
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.
Select BASICAUTH or SSLWITHBASICAUTH (if the endpoint is configured with Secure Sockets Layer) as the authentication type.
Enter a user identifier for the user on the partner side being used to protect their SOAP Receiver.
Enter and reenter the password associated with the user on the partner side being used to protect their SOAP Receiver.
Click Finish to complete the configuration.
Click Save to save the configuration.
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.1 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.
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.
Duplicate the amSAML.xml service file and make any changes to the attributes.
Remove the old amSAML.xml service file.
Use amadmin to reload the newly modified amSAML.xml file.
For more information on amadmin, see the Sun Java System Access Manager 7.1 Administration Guide.
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:
The attributes in the Properties group are as follows:
This attribute assigns a name to the destination site URL value that is used in the redirects discussed in Profiles. The default is TARGET. Only sites configured in the Trusted Partners attribute can be specified as a TARGET. For information, see Trusted Partners.
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//.
You may also edit or duplicate entries already listed.
In the Access Manager Console, click the Federation tab.
Under Federation, click the SAML tab.
Select New under the Site Identifiers attribute.
Enter values for the following attributes:
The value of this property is protocol://host:port.
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.
The value of this property is host:port.
Click OK.
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.
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.
In the Access Manager Console, click the Federation tab.
Under Federation, click the SAML tab.
Select New under the Trusted Partners attribute.
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.
Type values for the Common Settings subattributes based on the selected roles.
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.
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.
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.
The class is used to return a list of attribute values defined as AttributeStatements elements in an Authentication Assertion. A site attribute mapper needs to be implemented from the com.sun.identity.saml.plugins.PartnerSiteAttributeMapper interface.
If no class is defined, no attributes will be included in the assertion. For more information, see PartnerSiteAttributeMapper Interface.
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
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 PartnerAccountMapper Interface.
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.
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.
The creator of a generated assertion. The default syntax is hostname:port.
Type values for the Destination subattributes.
The URL that points to the servlet that implements the Web Browser Artifact Profile. See Web Browser Artifact Profile.
The URL that points to the servlet that implements the Web Browser POST Profile. See Web Browser POST Profile.
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.
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.
Type values for the Source subattributes.
The URL to the SAML SOAP Receiver. See SAML SOAP Receiver.
Authentication types that can be used with SAML:
NOAUTH
Specify NOAUTH if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is not protected by HTTP basic authentication.
BASICAUTH
Specify BASICAUTH if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is protected by HTTP basic authentication.
SSL
Specify SSL if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by HTTP basic authentication.
SSLWITHBASICAUTH
Specify SSLWITHBASICAUTH if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is protected by HTTP basic authentication.
If you are protecting the SAML SOAP receiver URL with HTTP basic authentication, you do so in the web container configuration and not in the Access Manager configuration. You do, however, supply the HTTP basic authentication user ID and password in the Access Manager configuration.
This attribute is optional. If not specified, the default is NOAUTH. If BASICAUTH or SSLWITHBASICAUTH is specified, the Trusted Partners attribute is required and should be HTTPS. For more information, see Trusted Partners.
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.
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.
Reenter the password defined previously.
Click Finish to complete the configuration.
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:
Choose either http or https.
The name of the server on which the TARGET URL resides, such as www.sun.com.
The port number, such as 58080.
The URI, such as /amserver/console.
The attributes in the Assertion group are as follows:
This attribute specifies the number of seconds before a timeout occurs on an assertion. The default is 420.
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.
The attributes in the Artifact group are as follows:
For more information about artifacts, see Web Browser Artifact Profile.
This attribute specifies the period of time an assertion that is created for an artifact will be valid. The default is 400.
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.
The attributes in the Signing group are as follows:
This attribute specifies whether all SAML assertions will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.
This attribute specifies whether all SAML requests will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.
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.
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:
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.
This package contains the AssertionManager and SAMLClient classes.
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).
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.
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.
// 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(); |
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.
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:
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.
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.
NameIdentifierMapper is an interface that can be implemented by a site to map a user account to a name identifier in the subject of a SAML assertion. The implementation class is specified when configuring the site's Trusted Partners.
The AccountMapper interface has been deprecated. Use the PartnerAccountMapper interface.
The PartnerAccountMapper interface needs 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 sub-attribute 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. The PartnerAccountMapper takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. 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.1 Developer’s Guide.
The SiteAttributeMapper interface has been deprecated. Use the PartnerSiteAttributeMapper interface.
The PartnerSiteAttributeMapper interface needs 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 this mapper which would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion.
Implement a customized class based on the PartnerSiteAttributeMapper interface.
This class will include user attributes in the SAML authentication assertion.
Log in to the Access Manager console to configure the class in the Site Attribute Mapper attribute of the Trusted Partner configuration.
See Trusted Partners for more information.
This package contains classes that parse the request and response XML messages used to exchange assertions and their authentication, attribute, or authorization information.
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.
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.
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.
// 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); } |
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.1 Developer’s Guide. For details on how to use the signature functionality, see SAML Samples.
This section contains procedures illustrating how to use the Access Manager SAML Service. They are:
The following procedures explain how to configure and access instances of Access Manager for single sign-on using SAML 1.x assertions. Machine A (exampleA.com) is the source site which authenticates the user and creates the SAML authentication assertion. Machine B (exampleB.com) is the destination site which consumes the assertion and generates a SSOToken for the user.
If both machines are in the same domain, the cookie names must be different. You can change the cookie name by modifying the com.iplanet.am.cookie.name property in AMConfig.properties, located in /etc/opt/SUNWam/config/.
This section contains the following procedures:
This procedure assumes the following values:
Deployment URI |
amserver |
Port |
58080 |
Protocol |
http |
Write down or copy the value of the Site ID attribute from the destination site (machine B).
Login to the Access Manager console running at exampleB.com as the default administrator, amadmin.
Click the Federation tab.
Click the SAML tab.
Click the sole entry listed under Site Identifiers.
This takes you to the Edit site identifier page.
Write down or copy the value of the Site ID attribute.
Click Cancel.
Log out of this instance of Access Manager.
Configure the source site (machine A) to trust the destination site (machine B) AND write down or copy the value of the Site ID attribute from the source site.
Login to the Access Manager console running at exampleA.com as the default administrator, amadmin.
Click the Federation tab.
Click the SAML tab.
Click New under Trusted Partners.
This takes you to the Select trusted partner type and profile page.
Check Artifact and Post under Destination and click Next.
This takes you to the Add New Trusted Partner page.
Set the values of the following attributes to configure machine B as a trusted partner of machine A:
Source ID |
Type the Site ID copied from the destination site, machine B, in the previous step. |
Target |
The value of this attribute contains the host's domain or domain with port. Do not include the accompanying protocol. For example, exampleB.com and exampleB.com:58080 are valid but, http://exampleB.com:58080. |
SAML URL |
http://exampleB.com:58080/amserver/SAMLAwareServlet |
HOST LIST |
exampleB.com |
POST URL |
http://exampleB.com:58080/amserver/SAMLPOSTProfileServlet |
Click Finish.
Click Save.
Click the sole entry listed under Site Identifiers.
This takes you to the Edit site identifier page.
Write down or copy the value of the Site ID attribute.
Click Cancel to go to previous page.
Log out of Access Manager.
Configure the destination site (machine B) to trust the source site (machine A).
Login to the Access Manager console running at exampleB.com as the default administrator, amadmin.
Click the top-level realm under Access Control.
Click the Authentication tab.
Click New under Module Instances.
Type a value in the Name field.
Select the SAML radio button and click OK.
Click Save.
Click Access Control in the upper left corner.
Click the Federation tab.
Click the SAML tab.
Click New under Trusted Partners.
This takes you to the Select trusted partner type and profile page.
Check Artifact and Post under Source and click Next.
This takes you to the Add New Trusted Partner page.
Set the values of the following attributes to configure machine A as a trusted partner of machine B:
Source ID |
Type the Site ID you copied from the source site, machine A, in the previous step. |
SOAP URL |
http://exampleA.com:58080/amserver/SAMLSOAPReceiver |
Issuer |
exampleA.com:58080 |
If machine B uses https, check SSL under Authentication Type. Be sure to modify the protocol in the other attributes as necessary.
Click Finish.
Click Save.
Log out of Access Manager.
Login to the Access Manager console running at exampleA.com as the default administrator, amadmin.
To initialize single sign-on from machine A, do one of the following:
Access the following URL to use the SAML Artifact profile:
http://exampleA.com:58080/amserver/SAMLAwareServlet?TARGET=exampleB.com_Target_URL
Access the following URL to use the SAML POST profile:
http://exampleA.com:58080/amserver/SAMPOSTProfileServlet?TARGET=exampleB.com_Target_URL
XML signing must be enabled before running the SAML POST profile. See Signing Liberty ID-FF Requests and Responses for details.
exampleB.com_Target_URL is any URL on the exampleB.com site to which the user will be redirected after a successful single sign-on. For testing purpose, this could be the login page as in TARGET=http://exampleB.com:58080/amserver/UI/Login. If the administrator successfully accesses the Access Manager console on the destination site without manual authentication, we know that an SSOtoken has been created for the principal on the destination site and single sign-on has been properly established.
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.