Security Assertion Markup Language

Security Assertion Markup Language (SAML) is an XML standard for exchanging authentication and authorization data between security domains, that is, between an identity provider and a service provider. SAML is a product of the OASIS Security Services Technical Committee.

The single most important problem that SAML is trying to solve is the web identity federation problem. Single Sign On solutions at the intranet level abound (using cookies, e.g.) but extending these solutions beyond the intranet has been problematic and has led to the proliferation of proprietary technologies that do not interoperate. SAML has become the definitive standard underlying many web SSO (Single Sign On) solutions in the identity management problem space.

SAML assumes the principal (often a user) has enrolled with at least one identity provider. This identity provider is expected to provide local authentication services to the principal. However, SAML does not specify the implementation of these local services; indeed, SAML does not care how local authentication services are implemented (although individual service providers most certainly will).

While this page still mostly focusses on SAML 1, the most current version of the SAML standard is V2.0, which was approved on 15 March 2005.

SAML 1.0

SAML 1.0 was adopted as an OASIS standard in Nov 2002. SAML has undergone one minor and one major revision since V1.0, which itself is a relatively simple protocol. SAML 1.0 is not just of historical interest since the US Federal E-Authentication Initiative has adopted SAML 1.0 as its core technology.

Fortunately, versions 1.0 and 1.1 of SAML are similar. See #SAMLDiff for specific differences between the two standards. This article concentrates on SAML 1.1 since it is the definitive standard on which most other standards and implementations depend.

SAML 2.0 was approved in March 2005. SAML2.0 conforms to SAML 1.1 and Liberty Alliance.

SAML 1.1

SAML 1.1 was ratified as an OASIS standard in Sep 2003. The critical aspects of SAML 1.1 are covered in detail in the official documents #SAMLConform, #SAMLCore, and #SAMLBind. If you are new to SAML, you should probably read #SAMLOverview first.

SAML 1.1 Assertions

SAML assertions are usually transferred from identity providers to service providers. Assertions contain statements that service providers use to make access control decisions. Three types of statements are provided by SAML:

1. Authentication statements
2. Attribute statements
3. Authorization decision statements

Authentication statements assert to the service provider that the principal did indeed authenticate with the identity provider at a particular time using a particular method of authentication. Other information about the principal may be disclosed in an authentication statement. For example, in the authentication statement below, the e-mail address of the principal is disclosed to the service provider:

<saml:Assertion
 xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
 MajorVersion="1" MinorVersion="1"
 AssertionID="..."
 Issuer="https://idp.org/saml/"
 IssueInstant="2002-06-19T17:05:37.795Z">
 <saml:Conditions 
   NotBefore="2002-06-19T17:00:37.795Z"
   NotOnOrAfter="2002-06-19T17:10:37.795Z"/>
 <saml:AuthenticationStatement
   AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
   AuthenticationInstant="2002-06-19T17:05:17.706Z">
   <saml:Subject>
     <saml:NameIdentifier
       Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
       user@mail.idp.org
     </saml:NameIdentifier>
     <saml:SubjectConfirmation>
       <saml:ConfirmationMethod>
         urn:oasis:names:tc:SAML:1.0:cm:artifact
       </saml:ConfirmationMethod>
     </saml:SubjectConfirmation>
   </saml:Subject>
 </saml:AuthenticationStatement>
</saml:Assertion>

An e-mail address (as in the above example) will suffice in a large number of situations. In some cases, however, additional information is needed before a service provider can make an access control decision. As an example, suppose that students are allowed to access scholarships data. An attribute statement can indicate whether or not the principal has an affiliation of "student", which the service provider uses to allow or deny access (resp.) to the scholarships application:

<saml:Assertion 
 xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
 MajorVersion="1" MinorVersion="1"
 Issuer="https://idp.edu/saml/" ...>
 <saml:Conditions NotBefore="..." NotAfter="..."/>
 <saml:AuthenticationStatement
   AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:X509-PKI"
   AuthenticationInstant="...">
   <saml:Subject>...</saml:Subject>
 </saml:AuthenticationStatement>
 <saml:AttributeStatement>
   <saml:Subject>...</saml:Subject>
   <saml:Attribute 
     AttributeName="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
     AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
     <saml:AttributeValue Scope="idp.edu">
       member
     </saml:AttributeValue>
     <saml:AttributeValue Scope="idp.edu">
       student
     </saml:AttributeValue>
   </saml:Attribute>
 </saml:AttributeStatement>
</saml:Assertion>

Attributes are often obtained from an LDAP directory, so consistent representations of attributes across security domains is crucial.

In the above example showing how a student might obtain access to a scholarships application, the service provider is functioning as both a policy enforcement point and a policy decision point. In some situations, it may be preferable to associate the policy decision point with the identity provider. In this case, the service provider passes a URI to the identity provider who asserts an authorization decision statement that dictates whether or not the principal should be allowed access to the secured resource at the given URI.

<saml:Assertion 
 xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
 MajorVersion="1" MinorVersion="1"
 Issuer="https://idp.org/saml/" ...>
 <saml:Conditions .../>
 <saml:AuthorizationDecisionStatement
   Decision="Permit"
   Resource="https://sp.org/confidential_report.html">
   <saml:Action>read</saml:Action>
   <saml:Subject>...</saml:Subject>
 </saml:AuthorizationDecisionStatement>
</saml:Assertion>

The three statement types are not mutually exclusive. For example, both authentication statements and attribute statements may be included in a single assertion (as shown above). This precludes the need to make subsequent round trips between the service provider and identity provider.

SAML 1.1 Protocol

The SAML protocol is a simple request-response protocol. A SAML requester sends a SAML Request element to a responder:

<samlp:Request 
 xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
 MajorVersion="1" MinorVersion="1" 
 RequestID="..." 
 IssueInstant="...">
 <!-- insert other SAML elements here -->
</samlp:Request>

Similarly, a SAML responder returns a SAML Response element to the requester:

<samlp:Response
 xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
 MajorVersion="1" MinorVersion="1"
 ResponseID="..."
 InResponseTo="..."
 IssueInstant="...">
 <!-- insert other SAML elements here, including assertions -->
</samlp:Response>

The bindings and profiles needed to affect this message exchange are detailed in the following sections.

SAML 1.1 Bindings

SAML 1.1 defines just one binding, the SAML SOAP binding. A compatible SAML 1.1 implementation must implement SAML over SOAP over HTTP (synchronous protocol). Other transport mechanisms are permitted provided the protocol-independent aspects of the SAML SOAP binding are observed (see section 3.1.2 of #SAMLBind).

The SAML 1.1 SOAP binding is built on top of version 1.1 of SOAP (the numbering is purely coincidental). A SAML requester wraps a SAML Request element within the body of a SOAP message. Similarly, a SAML responder returns a SAML Response element within the body of a returned SOAP message. If there is an error, the responder returns a SOAP fault code instead.

Any SAML markup must be included in the SOAP body. SAML 1.1 does not define any SAML-specific SOAP headers. A requester is free to insert any SOAP headers it wishes (although none are required).

Recall that in SOAP 1.1, a SOAPAction HTTP header must be included with each HTTP request (although its value may be empty). A SAML requester may give the following value to the SOAPAction header:

SOAPAction: http://www.oasis-open.org/committees/security

A SAML responder must not depend on this value, however.

A secure connection is not required for SAML requests and responses, but in those situations where message integrity and confidentiality are required, HTTP over SSL 3.0 or TLS 1.0 with a server-side certificate is required.

A SAML responder may return a "403 Forbidden" response when it refuses to respond to a SAML requester. A responder must return a "500 Internal Server Error" response in the event of a SOAP error (a SOAP fault element must be included as well). Otherwise, a "200 OK" response is returned, even in the presence of a SAML processing error. Such a response will include a SAML Status element in the SOAP body.

SAML 1.1 Profiles

In general, profiles describe the HTTP exchanges required to ultimately transfer assertions from an identity provider to a service provider. SAML 1.1 specifies two browser-based, single sign-on profiles:

1. Browser/Artifact Profile (subject confirmation method identifier of "urn:oasis:names:tc:SAML:1.0:cm:artifact")
2. Browser/POST Profile (subject confirmation method identifier of "urn:oasis:names:tc:SAML:1.0:cm:bearer")

These profiles support cross-domain single sign-on (SSO). The specification does not define any additional profiles. In particular, SAML 1.1 does not support a profile to secure a web service message nor does it support a single logout profile.

Both SAML 1.1 profiles begin at the inter-site transfer service, which is managed by the identity provider. How the principal arrives at the transfer service in the first place is not dictated by the specification. See sections 4.1 and 4.2 of #SAMLOverview for possible scenarios. In practice, a client accessing a secured resource at a service provider will be redirected to the inter-site transfer service at the identity provider. Note, however, that the precise sequence of steps needed to accomplish this is not outlined by SAML 1.1. (See section 4.3 of #SAMLOverview for some rough ideas along these lines.) This issue is thoroughly addressed in SAML 2.0.

After visiting the inter-site transfer service, the principal is transferred to the assertion consumer service at the service provider. Exactly how the principal is transferred from the inter-site transfer service to the assertion consumer service depends on the profile used. In the case of the Browser/Artifact Profile, a redirect is used; in the case of the Browser/POST Profile, the client issues a POST request (with or without user intervention).

To expedite processing by the assertion consumer service, two separate URLs are specified:

1. Artifact Receiver URL (Browser/Artifact Profile)
2. Assertion Consumer URL (Browser/POST Profile)

These and other URLs may be recorded in a SAML metadata archive.

Note that a conforming SAML 1.1 identity provider must provide an inter-site transfer service. Similarly, a SAML 1.1 service provider must provide an assertion consumer service.

SAML 1.1 Browser/Artifact Profile

The Browser/Artifact Profile employs a "pull" mechanism. The profile essentially passes an SSO assertion from the identity provider to the service provider by reference, which is subsequently dereferenced via a back-channel exchange (i.e., the service provider "pulls" the assertion from the identity provider).

The SAML 1.1 Browser/Artifact Profile specifies the following six (6) steps:

1) Request the Inter-site Transfer Service

The principal (user) requests the inter-site transfer service at the identity provider:

https://idp.org/saml/TransferService?TARGET=target

where target is the location of the desired resource at the service provider, say, https://www.sp.org/home. In other words, the following GET request is issued by the client:

GET /saml/TransferService?TARGET=target HTTP/1.1
Host: idp.org

The profile does not specify how the URL to the transfer service (with target parameter) is obtained by the client.

2) Redirect to the Assertion Consumer Service

The principal is redirected to the assertion consumer service at the service provider; that is, the following response is returned to the client:

HTTP/1.1 302 Found
Location: https://sp.org/saml/ACS/Artifact?TARGET=target&SAMLart=artifact

where artifact is a reference to an assertion the identity provider is willing to provide upon request. Important: It is assumed that the principal has already established a security context at the identity provider, otherwise the identity provider would not be able to subsequently assert the authenticity of the principal.

3) Request the Assertion Consumer Service

The client requests the assertion consumer service at the service provider:

https://sp.org/saml/ACS/Artifact?TARGET=target&SAMLart=artifact

where target and artifact are as before. In other words, the following GET request is issued by the client:

GET /saml/ACS/Artifact?TARGET=target&SAMLart=artifact HTTP/1.1
Host: sp.org

4) Request the Artifact Resolution Service

The assertion consumer service at the service provider begins a back-channel exchange with the artifact resolution service at the identity provider. The following SAML SOAP message is bound to an HTTP POST request:

POST /saml/ArtifactResolutionService HTTP/1.1
Host: idp.org
Content-Type: text/xml
Content-Length: nnn
SOAPAction: http://www.oasis-open.org/committees/security

<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <samlp:Request 
      xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
      MajorVersion="1" MinorVersion="1" 
      RequestID="_192.168.16.51.1024506224022" 
      IssueInstant="2002-06-19T17:03:44.022Z">
      <samlp:AssertionArtifact>
        artifact
      </samlp:AssertionArtifact>
    </samlp:Request>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

where artifact was previously sent from the identity provider to the service provider in steps 2 and 3.

5) Respond with a SAML Assertion

The artifact resolution service at the identity provider completes the back-channel exchange by responding with a SAML assertion:

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: nnnn

<?xml version="1.0"?>
<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"
      MajorVersion="1" MinorVersion="1"
      ResponseID="_P1YaA+Q/wSM/t/8E3R8rNhcpPTM="
      InResponseTo="_192.168.16.51.1024506224022"
      IssueInstant="2002-06-19T17:05:37.795Z">
      <samlp:Status>
        <samlp:StatusCode Value="samlp:Success"/>
      </samlp:Status>
      <!-- insert Assertion element here -->
    </samlp:Response>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

where the Assertion element was discussed earlier.

6) Respond to the Principal's Original Request

The assertion consumer service inspects the SAML Response element returned by the artifact resolution service, creates a security context at the service provider and redirects the client to the target resource.

SAML 1.1 Browser/POST Profile

The Browser/POST Profile relies on a "push" operation. In contrast to the Browser/Artifact Profile, the Browser/POST Profile passes an SSO assertion by value. No back-channel communication is needed in this case. In effect, the identity provider "pushes" the assertion to the service provider.

The SAML 1.1 Browser/POST Profile specifies the following four (4) steps (the terminology used in the original document has been modified slightly to conform to the emerging SAML 2.0 specification):

1) Request the Inter-Site Transfer Service

The principal (user) requests the inter-site transfer service at the identity provider:

https://idp.org/saml/TransferService?TARGET=target

where target is the desired resource at the service provider, say, https://www.sp.org/home. In other words, the following GET request is issued by the client:

GET /saml/TransferService?TARGET=target HTTP/1.1
Host: idp.org

The profile does not specify how the URL to the transfer service (with target parameter) is obtained by the client.

2) Respond with an HTML Form

The inter-site transfer service returns an HTML document containing a FORM element whose ACTION attribute is the URL of the assertion consumer service:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: nnnn

...
<form method="post" 
      action="https://sp.org/saml/ACS/post" ...>
  <input type="hidden" name="TARGET" value="target">
  <input type="hidden" name="SAMLResponse" value="response">
  ...
  <input type="submit" value="Submit">
</form>
...

where the value of the TARGET parameter has been preserved from step 1. The value of the SAMLResponse parameter is the base64 encoding of a SAML Response element, more-or-less the same SAML Response element returned by the identity provider in step 5 of the Browser/Artifact Profile. In the case of the Browser/POST Profile, however, the SAML Response must be digitally signed by the identity provider.

Important: It is assumed that the principal has already established a security context at the identity provider, otherwise the inter-site transfer service would not be able to provide an authentication statement in the SAML Response element.

3) Request the Assertion Consumer Service

The client requests the assertion consumer service at the service provider:

POST /saml/ACS/post HTTP/1.1
Host: sp.org
Content-Type: application/x-www-form-urlencoded
Content-Length: nnnn

TARGET=target&SAMLResponse=response

To automate the submission of the form, the following line of JavaScript may appear anywhere on the page:

window.onload = function () { document.forms[0].submit(); }

This assumes of course that the page contains a single FORM element.

4) Respond to the Principal's Original Request

The assertion consumer service inspects the SAML Response element, creates a security context on the service provider and redirects the client to the target resource.

SAML 2.0

SAML 2.0 was approved on 15 March 2005. It includes a profile for ECP: Enhanced Client or Proxy[1]. This requires a client similar to the Windows CardSpace Identity Selector.

References

• [SAMLBind] E. Maler et al., Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS, September 2003. Document ID oasis-sstc-saml-bindings-profiles-1.1 http://www.oasis-open.org/committees/security/

• [SAMLConform] E. Maler et al., Conformance Program Specification for the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS, September 2003. Document ID oasis-sstc-saml-conform-1.1 http://www.oasis-open.org/committees/security/

• [SAMLCore] E. Maler et al., Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML). OASIS, September 2003. Document ID oasis-sstc-saml-core-1.1 http://www.oasis-open.org/committees/security/

• [SAMLDiff] P. Mishra et al., Differences between OASIS Security Assertion Markup Language (SAML) V1.1 and V1.0. OASIS, May 2003. Document ID sstc-saml-diff-1.1-draft-01 http://www.oasis-open.org/committees/security/

• [SAMLOverview] J. Hughes et al., Technical Overview of the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS, May 2004. Document ID sstc-saml-tech-overview-1.1-cd http://www.oasis-open.org/committees/security/

See also

• Single sign-on
• Identity Centric Architecture
• Shibboleth
• Light-Weight Identity
• OpenID
• Yadis
• OASIS

External links

• OASIS SSTC homepage
• Cover Pages article on SAML
• Demystifying SAML
• The Java (TM) Web Services Tutorial - SAML Sample Application