Securing Web Services with WS-Security: Demystifying WS-Security, WS-Policy, SAML, XML Signature, and XML Encryption

SAML is fundamentally three XML-based mechanisms:

• Assertions ” An XML schema and definition for security assertions. This makes SAML an XML framework that can be extended with new assertions.

• Protocol ” An XML schema and definition for a request/response protocol. The requests are for policy decisions and enforcement from SAML authorities.

• Bindings ” Rules on using assertions with standard transport and messaging frameworks. These rules are described as a set of bindings and protocols.

The relationship among these three aspects of SAML is shown in Figure 6.2.

SAML assertions are encoded in a common XML Schema, which includes basic information and the claims the requestor is making (for example, "I claim to be Jothy"). The basic information specifies a unique identifier used for the assertion name , date and time of issuance, and the time interval for which the assertion is valid, as shown in Listing 6.1.

Listing 6.1. A Simple SAML Assertion

<saml:Assertion> MajorVersion="1" MinorVersion="0" AssertionID="192.168.0.1.12345" Issuer="Company.com" IssueInstant="2004-01-21T10:02:00Z"> <saml:Conditions> NotBefore="2004-01-21T10:02:00Z" NotAfter="2004-01-21T10:09:00Z" /> <saml:AuthenticationStatement> AuthenticationMethod="password" AuthenticationInstant="2004-01-21T10:02:00Z"> <saml:Subject> <saml:NameIdentifier SecurityDomain="Company.com" Name="jothy" /> </saml:Subject> </saml:AuthenticationStatement> </saml:Assertion>

Claims are made to an authority who returns another assertion (for example, "I vouch for the fact that this is Jothy"). An assertion may contain conditions and advice elements. For example, an assertion may be dependent on additional information from a validation service, and an assertion may be dependent on other assertions to be valid. Assertions may contain additional information as advice used to specify the assertions that were used to make a policy decision.

SAML assertions are submitted to authentication and authorization authorities through a request/response protocol exchange, as shown in Figure 6.3.

SAML authorities are trusted third parties such as certificate authorities (CA) that provide SAML assertions on request. SAML assertions can be signed to link back to a trusted entity that vouches for the initial claim. They are always subject to the authenticity of the entity making the claim (just like a CA's signature on a digital certificate containing a public key vouches for the authenticity for the contained public key).

SAML assertions are bound to the transport and messaging frameworks used in a particular application. For example, SAML defines how assertions are passed around using HTTP, SMTP, or Java Message Services within a SOAP (that is, Web services) or ebXML messaging framework. Of course, we are most interested in SAML used in the SOAP messaging framework.

WS-Security, really just a security extension to SOAP, specifies SAML assertions as one of the types of security tokens it supports in the SOAP header.

SAML Assertions

The elements shown in Table 6.1 are common to all SAML assertions.

Table 6.1. Elements Common to All SAML Assertions

A simple <saml:Assertion> issued by Smith Corporation with some conditions and advice is shown in Listing 6.2.

Listing 6.2. A SAML Assertion with Conditions and Advice

<saml:Assertion MajorVersion="1" MinorVersion="0" AssertionID="128.9.167.32.12345678" Issuer="Smith Corporation" IssueInstant="2001-12-03T10:02:00Z"> <saml:Conditions NotBefore="2001-12-03T10:00:00Z" NotOnOrAfter="2001-12-03T10:05:00Z"> <saml:AudienceRestrictionCondition> <saml:Audience>...URI...</saml:Audience> </saml:AudienceRestrictionCondition> </saml:Conditions> <saml:Advice> ...assertions and other elements go here... </saml:Advice> ...statements go here... </saml:Assertion>

Authentication Assertions

An authentication authority receives a subject's credentials. It processes those credentials according to its established policy. If the authentication process is successful, the authority asserts that subject S was identified and that the subject has authentically represented itself by method M at time T so that its digital identity can be trusted to represent its physical identity.

More specifically , if the authority determines that the presented credentials are valid, an <AuthenticationStatement> is created. This element contains the method, <AuthenticationMethod> , used for authentication, as well as the time, <AuthenticationInstant> , the authentication process occurred. The <AuthenticationStatement> element also optionally contains <SubjectLocality> , which specifies the DNS name and IP address of an authentication system, and <AuthorityBinding> , which indicates that additional information about the subject may be available.

The following authentication methods are supported:

Although SAML itself does not provide a revocation model, the fact that it can integrate digital certificates and digital signatures into its model provides a means to invalidate (revoke) an identity's validity before its lifetime expiration. Listing 6.3 shows a simple SAML <AuthenticationStatement> for someone named joeuser who was authenticated via a password:

Listing 6.3. A <saml:AuthenticationStatement> for joeuser Using a Password for Authentication

<saml:Assertion ...> <saml:AuthenticationStatement AuthenticationMethod="urn:oasis:names:tc:SAML: 1.0:am:password" AuthenticationInstant="2001-12-03T10:02:00Z"> <saml:Subject> <saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.0: assertion#emailAddress">joeuser@smithco.com <saml:SubjectConfirmation> <saml:ConfirmationMethod> ...specific to a profile or agreement... </saml:ConfirmationMethod> </saml:SubjectConfirmation> </saml:Subject> </saml:AuthenticationStatement> </saml:Assertion>

Attribute Assertions

An attribute issuing authority receives credentials for subject S with the intent of attaching certain attributes to this subject's identity. This authority asserts that subject S is associated with attributes A, B, and C with values "a", "b", "c." This type of information is probably in some sort of repository of user attribute information such as an LDAP directory. Examples of typical attributes might include this individual's current account paid status and her credit limit. Listing 6.4 is an attribute assertion for an unspecified subject specifying their PaidStatus and CreditLimit .

Listing 6.4. A <saml:AttributeStatement> Specifying PaidStatus and CreditLimit

<saml:Assertion ...> <saml:AttributeStatement> <saml:Subject>...</saml:Subject> <saml:Attribute AttributeName="PaidStatus" AttributeNamespace="http://smithco.com"> <saml:AttributeValue> PaidUp </saml:AttributeValue> </saml:Attribute> <saml:Attribute AttributeName="CreditLimit" AttributeNamespace="http://smithco.com"> <saml:AttributeValue xsi:type="my:type"> <my:amount currency="USD">500.00 </my:amount> </saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion>

Authorization Assertions

An authorization authority receives credentials for subject S along with a request for authorization. This authority asserts that subject S can be granted access of type A to resource R given evidence E. The subject could be human or a computer (Web service), and the requested resource could be another Web service. Listing 6.5 shows an authorization statement for an unspecified subject which authorizes ( permits ) the subject to access a resource specified by URL and to execute the accessed resource (it's a program) so specified.

Listing 6.5. A <saml:AuthorizationStatement> Permitting Access to a Program a Subject May Execute

<saml:Assertion ...> <saml:AuthorizationStatement Decision="Permit" Resource="http://jonesco.com/doit.cgi"> <saml:Subject>...</saml:Subject> <saml:Action Namespace= "urn:oasis:names:tc:SAML:1.0:action:rwedc">Execute </saml:Action> </saml:AuthorizationStatement> </saml:Assertion>

SAML Producers and Consumers

SAML is concerned with access control for authenticated subjects based on a set of policies. The two critical actions that must be taken with respect to access control are making decisions based on a set of policies and enforcing those decisions. The SAML architecture provides for defined roles for these actions. A Policy Decision Point ( PDP ) makes decisions about access control based on one or more parameters. Simple types of access can be granted, or complex conditional access ”such as a specific group on a specific day at a specific time ”can be granted. If the PDP is external to the system, it needs to have access to an additional component called the Policy Retrieval Point ( PRP ) to retrieve policies for the decisions it is required to make.

A Policy Enforcement Point ( PEP ) is called in when an enforcement decision is required. A PEP makes a connection to the appropriate PDP for the decision. The policy function is evaluated with data supplied from the PEP to the PDP. These SAML architectural elements are shown in Figure 6.4. PDPs most likely communicate to back-end policy stores using the XACML access control/policy language. We cover XACML in Chapter 9, "Trust, Access Control, and Rights for Web Services."

SAML Protocol

SAML defines a request/response protocol to generate and exchange assertions. The SAML protocol is a completely separate schema (with a different namespace urn:oasis:names:tc:SAML:1.0:protocol usually prefixed with the namespace prefix samlp ) from the assertions schema. A request contains a claim, and the response from the authority contains the resulting assertion. The queries are specifically targeted for authentication, attribute, and authorization. Requests contain the ID of the subject in question; that ID is included in the response to make sure the request and response are both talking about the same subject. An assumed trust relationship exists between the relying part and the asserting party. In other words, if you rely on the assertions presented to you, you need to trust the authority that vouches for the subject doing the asserting (making the claims).

The elements shown in Table 6.2 are common to all SAML requests.

Table 6.2. Elements Common to All SAML Requests

Authentication Request

An authentication request is like asking the question "What authentication assertions are available for this subject?" The response is in the form of an assertion containing an authentication statement. This response with an assertion is like a letter of introduction: "I would like to present to you my friend, whom I vouch for, Jothy."

The authentication authority receives a set of credentials about the subject from the credentials collector and processes them according to its policy. The assertion defines several authentication elements such as the identity of the issuer and the subject, the time the authentication was granted, and the lifetime for which it will be valid. The assertion clearly indicates that the subject was authenticated by a specific system at a specific time.

An <AuthenticationStatement> is generated after authentication is successful and contains the method used for authentication, the time it occurred, and the place it occurred. Listing 6.6 is a request for authentication that is signed using a digital signature to prove the source is valid. Authentication is requested for the Subject "jothy" from Company.com. The response will be an AuthenticationStatement .

Listing 6.6. A <samlp:AuthenticationQuery> Requesting Authentication for Subject jothy from Company.com

<samlp:Request MajorVersion="1" MinorVersion="0" RequestID="128.14.234.20.12345678" IssueInstant="2001-12-03T10:02:00Z"> <samlp:RespondWith>saml:AuthenticationStatement</samlp:RespondWith> <ds:Signature>...</ds:Signature> <samlp:AuthenticationQuery> <saml:Subject> <saml:NameIdentifier SecurityDomain="Company.com" Name="jothy" /> </saml:Subject> </samlp:AuthenticationQuery> </samlp:Request>

Attribute Request

An attribute request is like asking for "all available attributes for this subject." The response is in the form of an assertion containing an attribute statement. The request can ask for information on specified attributes A, B, and C or, if not specific, on all available attributes. Only the attributes allowed for this subject are returned. The requestor may be denied access to some or all of this subject's attributes.

The attribute request is sent to an attribute authority along with a previously obtained authentication assertion. The attribute authority uses a policy to determine the privileges of the subject. The attribute assertion can be passed to a PDP for authorization.

The <AttributeStatement> contains <Subject> , <Attribute> , <NameIdentifier> , <SubjectConfirmation> , <ConfirmationMethod> , and <SubjectConfirmationData> elements. <Attribute> contains the attribute value <AttributeValue> element for the underlying assertion. Listing 6.7 is an AttributeQuery for an unspecified Subject requesting information about the attribute "PaidStatus" within a specific account specified via a URL for AttributeNameSpace .

Listing 6.7. A <samlp:AttributeQuery> for a Subject's PaidStatus at a Specific Account

<samlp:Request ... > <samlp:AttributeQuery> <saml:Subject>...</saml:Subject> <saml:AttributeDesignator AttributeName="PaidStatus" AttributeNamespace="http://smithco.com"/> </samlp:AttributeQuery> </samlp:Request>

Authorization Request

An authorization request asks this question: "Is this subject allowed to access the requested resource in the specified manner, given this evidence?"

The response is an authorization assertion containing an authorization decision statement. This request is about whether a subject can access a specific resource, given an authentication assertion and an attribute assertion. This type of request directly involves the PDP and PEP for authorization decisions and enforcement, respectively. The resulting decision can be Permit, Deny, or Indeterminate.

The <AuthorizationDecisionStatement> specifies what decision was made with respect to the authorization request. The resulting <AuthorizationDecisionStatement> contains the URI of the resource that Subject is requesting access to, a decision of Permit or Deny, an action specifying what Subject is authorized to do, and the evidence on which the decision was based. Listing 6.8 is a request for authorization for "joeuser" at Company.com asking whether he is authorized to execute a resource (here, just a CGI script) to reserve a hotel room at the ChosenTravel.com resource.

Listing 6.8. A <samlp:AuthorizationDecisionQuery> for joeuser to Gain Permission to Execute a Resource to Reserve a Hotel Room

<samlp:Request ...> <samlp:AuthorizationDecisionQuery Resource="http://ChosenTravel.com/reserve_hotel.cgi"> <saml:Subject> <saml:NameIdentifier SecurityDomain="Company.com" Name="joeuser" /> </saml:Subject> <saml:Actions Namespace="urn:oasis:names:tc:SAML: 1.0:action:rwedc"> <saml:Action>Execute</saml:Action> </saml:Actions> <saml:Evidence> <saml:Assertion>...</saml:Assertion> </saml:Evidence> </samlp:AuthorizationDecisionQuery> </samlp:Request>

SAML Protocol Response

SAML protocol responses are signed to identify the issuing authority and to guarantee the response remains unaltered. A response is one or more assertions with the status of the response.

Table 6.3 identifies elements common to all SAML responses.

Table 6.3. Elements Common to All SAML Responses

Listing 6.9 is a response to an authentication request that shows the issuer of the response as Company.com and specifies specific time-based validity conditions on the authentication:

Listing 6.9. A <samlp:Response> to an Authentication Request

<samlp:Response MajorVersion="1" MinorVersion="0" ResponseID="128.14.234.20.90123456" InResponseTo="128.14.234.20.12345678" IssueInstant="2001-12-03T10:02:00Z" Recipient="...URI..."> <samlp:Status> <samlp:StatusCode Value="Success" /> <samlp:StatusMessage> ... </samlp:StatusMessage> </samlp:Status> <saml:Assertion MajorVersion="1" MinorVersion="0" AssertionID="128.9.167.32.12345678" Issuer="Company.com"> <saml:Conditions NotBefore="2001-12-03T10:00:00Z" NotAfter="2001-12-03T10:05:00Z" /> <saml:AuthenticationStatement ...>... </saml:AuthenticationStatement> </saml:Assertion> </samlp:Response>

SAML Bindings

SAML bindings are how SAML itself is made secure. SAML authorities are trusted Web services that an SAML system must consult . A binding is a way to transport SAML requests and responses to and from these authorities. A binding is the mapping of SAML request/response message exchanges into standard communication protocols. The SAML specification requires SOAP over HTTP as one binding. Other bindings will be specified over time. In the SOAP binding, the SAML information is contained inside the SOAP body. Later, when we discuss the WS-Security profile for SAML, we will see an alternate binding in which the SAML assertion sits in the SOAP header and the resource it refers to sits in the SOAP body.

SAML messages can be transported using SOAP without re-encoding from the "standard" SAML schema. An SAML requestor transmits an SAML <Request> element within the body of a SOAP message to an SAML responder. The SAML requestor includes only one SAML request per SOAP message. The SAML responder returns either a single <Response> element within the body of another SOAP message or a SOAP fault code.

With SOAP most commonly bound itself to HTTP, endpoint-to-endpoint authentication for SAML should be provided by SSL Transport Layer Security. Message integrity and confidentiality of the SAML payload are also provided by SSL. In other words, you need to use SSL when using SAML.

Listing 6.10 is an example of a SOAP request that asks for an assertion containing an authentication statement from an SAML authentication authority:

Listing 6.10. A Full SOAP Request Sent to an SAML Authority Containing a <samlp:AuthenticationQuery> Showing SAML Transported via SOAP Bound to HTTP

POST /SamlService HTTP/1.1 Host: www.example.com Content-Type: text/xml Content-Length: nnn SOAPAction: http://www.oasis-open.org/committees/security <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <samlp:Request xmlns:samlp:="..." xmlns:saml="..." xmlns:ds="..."> <ds:Signature> ... </ds:Signature> <samlp:AuthenticationQuery> ... </samlp:AuthenticationQuery> </samlp:Request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Listing 6.11, which follows , is an example of the corresponding SOAP response, which supplies an assertion containing the authentication statement as requested.

Listing 6.11. The SOAP Response to the Listing 6.10 SOAP Request with Contained <saml:AuthenticationStatement> 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:Body> <samlp:Response xmlns:samlp="..." xmlns:saml="..." xmlns:ds="..."> <Status> <StatusCodevalue="samlp:Success"/> </Status> <ds:Signature> ... </ds:Signature> <saml:Assertion> <saml:AuthenticationStatement> ... </saml:AuthenticationStatement> </saml:Assertion> </samlp:Response> </SOAP-Env:Body> </SOAP-ENV:Envelope>

SAML Profiles

SAML profiles describe how SAML assertions are embedded into and extracted from a framework or protocol. Browser profiles for SAML were specified first (SAML pre-dated Web services). Next, the profile for securing SOAP payloads was specified. WS-Security specifies an SAML profile as part of the WS-Security specification.

The SAML profile for SOAP is structured as shown in Figure 6.5.