Tuesday, October 12, 2004

SAML1

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 single sign-on (SSO) problem. SSO 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 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).

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 of more than historical interest, however, since the 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 the document

  • Differences between OASIS Security Assertion Markup Language (SAML) V1.1 and V1.0 [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 1.1

Assertions | Protocol | Bindings | Profiles ]

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 following three documents:

  • Conformance Program Specification for the OASIS Security Assertion Markup Language (SAML) [SAMLConform]
  • Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) [SAMLCore]
  • Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) [SAMLBind]

If you are new to SAML, your first reading should probably be the following document:

  • Technical Overview of the OASIS Security Assertion Markup Language (SAML) [SAMLOverview]

There are at least two open source implementations of SAML 1.1:

  1. OpenSAML <http://www.opensaml.org/>
  2. SourceID SAML 1.1 Toolkit <http://www.sourceid.org/download.do>

OpenSAML is associated with Shibboleth while the SourceID tookit has its roots in Project Liberty. Both are based on the same standard and should therefore interoperate.

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. We will revisit this question in the thread on Federations.

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 preferrable 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 (a 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 SOAP 1.1 (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

Browser/Artifact Profile | Browser/POST Profile ]

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
  2. Browser/POST Profile

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 (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 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/Artifact 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.