A SAML WhitepaperJ. Hodges
 NeuStar
 September 6, 2006


How to Study and Learn SAML

Abstract

This brief whitepaper provides a functional introduction to the SAMLv2 specifications tailored to protocol designer and developer's perspectives. First a conceptual introduction is presented, next suggestions on how to study and learn SAML are given, and then more detailed aspects are discussed.



1.  Conceptual Introduction to SAML

SAML [OASIS.sstc‑saml‑exec‑overview‑2.0‑cd‑01] (Madsen, P. and E. Maler, “SAML V2.0 Executive Overview,” April 2005.) defines an XML-based framework for crafting "security assertions", and exchanging them between entities. In the course of creating, or relying upon such assertions, SAML system entities may use SAML protocols, or other protocols, to convey an assertion itself, or to communicate about the "subject" of an assertion.

Thus one can employ SAML to make statements such as:

"Alice has these profile attributes and her domain's certificate is available over there, and I'm making this statement, and here's who I am."

Then one can cause such an assertion to be conveyed to some party who can then rely on it in some fashion for some purpose, for example input it into a local policy evaluation gating access to some resource.

Such applications of SAML are done in a particular "context of use". A particular context of use could be, for example, deciding whether to accept and act upon a SIP-based invitation to initiate a communication session.

The specification of just how SAML is employed in any given context of use is known as a "SAML profile". The specification of how SAML assertions and/or protocol messages are conveyed in, or over, another protocol is known as a "SAML Binding". Typically, a SAML profile specifies the SAML bindings that may be used in its context. Both SAML profiles and SAML bindings in turn reference other SAML specifications, especially the SAML Assertions and Protocols, aka "SAML Core", specification [OASIS.saml‑core‑2.0‑os] (Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.).

This relationship between SAML specifications, as well as SAML-dependent specifications, is illustrated below in Figure 1 (Conceptual Dependencies between SAML Profiles, Bindings, and Core Specifications, as well as Target Protocols). The relationships between the various boxes in the diagrams is one of dependencies. Note how the boxes representing SAML Profiles—this means any SAML profile—depends upon both the SAML Core specification as well as SAML Bindings, and and of course also upon the specifications of the target profile(s).




+-----------------------------------------+---------------------+
|                                         |                     |
|       SAML Profiles                     |  SAML Assertions &  |
|        <CONCRETE>                       |      Protocols      |
|                                         |                     |
|    saml-profiles-2.0-os                 |   aka "SAML Core"   |
|                                         |                     |
|    [for example, see:                   |     <ABSTRACT>      |
|      draft-ietf-sip-saml-00 ]           |                     |
|                                         |  saml-core-2.0-os   |
|              +--------------------------+                     |
|              |                          |                     |
|              |      SAML Bindings       |                     |
|              |        <CONCRETE>        |                     |
|              |                          |                     |
|              |   saml-bindings-2.0-os   |                     |
|              |                          |                     |
+--------------+--------------------------+---------------------+
|                                         |
|         Target protocol(s)              |
|         ------------------              |
|            <CONCRETE>                   |
|                                         |
| [..in a particular overall "context of  |
| use", eg. using SIP to establish        |
| multi-media sessions on a user's        |
| behalf, Web SSO, or DAV, etc.           |
|                                         |
| Such a profile may depend upon more     |
| than one protocol in conjunction        |
| -- eg HTTP & SIP -- to accomplish the   |
| profile's mission (see sip-saml draft)] |
|                                         |
+-----------------------------------------+
|                                         |
|  underlying protocols (or technologies) |
|  -------------------------------------- |
|             <CONCRETE>                  |
|                                         |
|  eg TLS, and/or  TCP, IP, as            |
|  appropriate.                           |
|                                         |
+-----------------------------------------+

 Figure 1: Conceptual Dependencies between SAML Profiles, Bindings, and Core Specifications, as well as Target Protocols 

Note that the SAML Assertions & Protocols specification, the SAML Core, is conceptually "abstract". It defines the bits and pieces that make up SAML Assertions, and their nominal semantics, but does not define how to actually put them to use in any particular context. That, as we've said, is left to SAML Profiles, of which there can be many.

The original SAML profiles, which concentrate on the problem domain of "Web Single Sign-On", are specified in [OASIS.saml‑profiles‑2.0‑os] (Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, “Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.) (note that this specification is called out in the "SAML Profiles" box in Figure 1 (Conceptual Dependencies between SAML Profiles, Bindings, and Core Specifications, as well as Target Protocols)). An example of a different, non-Web-SSO SAML profile is given in [I‑D.ietf‑sip‑saml] (Tschofenig, H., “SIP SAML Profile and Binding,” June 2006.).



2.  How to Study and Learn SAML

Given the gist of the above discussion—that the descriptions of SAML applied in concrete contexts is given in SAML profiles—here is a suggested approach for reading the SAML specification set if one has as their goal "learning SAML":

Studying SAML in this fashion is a more concrete, context-rich approach than, say, beginning with reading the rather abstract SAML Core specification.



3.  SAML in More Detail

This section first discusses the notion of "SAML assertion profiles", and then follows with a more detailed description of SAML assertions as well as the abstract SAML request/response protocol—both of which are defined in the SAML Core specification [OASIS.saml‑core‑2.0‑os] (Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.).



3.1.  SAML Assertion Profiles

There is an additional subtle aspect of SAML profiles that is worth highlighting—the notion of "SAML assertion profiles". A SAML assertion profile is the specification of the specific SAML assertion contents in the context of a particular SAML profile. It is possibly further qualified by a particular implementation and/or deployment context. Two condensed examples of SAML assertion profiles are:

For a more in-depth example of an explicit SAML assertion profile, see section 6.1.4 "Assertion Profile Description" of [I‑D.ietf‑sip‑saml] (Tschofenig, H., “SIP SAML Profile and Binding,” June 2006.).

Note that all SAML profiles will more or less explicitly encompass one or more assertion profiles. For example, all the SAML profiles specified in [OASIS.saml‑profiles‑2.0‑os] (Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, “Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.) do so, however their "assertion profiles" are not explicitly labeled as such.



3.2.  SAML Assertions

A SAML assertion is a package of information including issuer and subject, conditions and advice, and/or attribute statements, and/or authentication statements and/or other statements. Statements may or may not be present. The SAML assertion "container" itself contains the following information:

Issuing information:

Who issued the assertion, when was it issued and the assertion identifier.

Subject information:

The name of the subject, the security domain and optional subject information, like public key.

Conditions under which the assertion is valid:

Special kind of conditions like assertion validity period, audience restriction and target restriction.

Additional advice:

Explaining how the assertion was made, for example.

In terms of SAML assertions containing SAML attribute statements or SAML authentication statements, here are explanatory examples:

With a SAML assertion containing a SAML attribute statement, an issuing authority is asserting that the subject is associated with certain attributes with certain subject profile attribute values. For example, user jon@cs.example.com is associated with the attribute "Department", which has the value "Computer Science".

With a SAML assertion containing a SAML authentication statement, an issuing authority is asserting that the subject was authenticated by certain means at a certain time.

With a SAML assertion containing both a SAML attribute statement and a SAML authentication statement, an issuing authority is asserting the union of the above.

Examples of actual SAML assertions are given below in Section 4 (Example SAML Assertions).



3.3.  Abstract Request/Response Protocol

SAML defines an abstract request/response protocol for obtaining assertions. See Section 3 "SAML Protocols" of [OASIS.saml‑core‑2.0‑os] (Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.). A request asks for an assertion. A response returns the requested assertion or an error. This abstract protocol may then be cast into particular contexts of use by binding it to specific underlying protocols, e.g., HTTP or SIP, and "profiling" it for the specific use case at hand. The SAML HTTP-based web single sign-on profile is one such example (see Section 4.1 Web Browser SSO Profile of [OASIS.saml‑profiles‑2.0‑os] (Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, “Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.)). Trait-based SIP communication session establishment, the topic of this specification, is another.



4.  Example SAML Assertions

This section presents two examples of a SAML assertion, one unsigned, the other signed and thus is integrity protected, and attests to the originating author.

In the first example, Figure 2 (Unsigned SAML Assertion Illustrating Conveyance of Subject Attribute), the assertion is attesting with respect to the subject (lines 7-15) "Alice@example.com" (line 11). The validity conditions are expressed in lines 16-23, via both a validity period expressed as temporal endpoints, and an "audience restriction" stating that this assertion's semantics are valid for only the relying party named "example2.com". Also, the assertion's issuer is noted in lines 4-5.

In lines 24-36, Alice's telephone number is conveyed, in a "typed" fashion, using LDAP/X.500 schema as the typing means.




 1 <Assertion ID="_a75adf55-01d7-40cc-929f-dbd8372ebdfc"
 2    IssueInstant="2003-04-17T00:46:02Z" Version="2.0"
 3    xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
 4    <Issuer>
 5       example.com
 6    </Issuer>
 7    <Subject>
 8       <NameID
 9         Format=
10         "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
11         Alice@example.com
12       </NameID>
13       <SubjectConfirmation
14         Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches"/>
15    </Subject>
16    <Conditions NotBefore="2003-04-17T00:46:02Z"
17                NotOnOrAfter="2003-04-17T00:51:02Z">
18       <AudienceRestriction>
19          <Audience>
20             example2.com
21          </Audience>
22       </AudienceRestriction>
23    </Conditions>
24    <AttributeStatement>
25       <saml:Attribute
26    xmlns:x500=
27      "urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"
28    NameFormat=
29      "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
30    Name="urn:oid:2.5.4.20"
31    FriendlyName="telephoneNumber">
32          <saml:AttributeValue xsi:type="xs:string">
33                +1-888-555-1212
34          </saml:AttributeValue>
35       </saml:Attribute>
36    </AttributeStatement>
37 </Assertion>

 Figure 2: Unsigned SAML Assertion Illustrating Conveyance of Subject Attribute 

In the second example, Figure 3 (Signed SAML Assertion Illustrating Conveyance of Subject Attribute), the information described above is the same, the addition is that this version of the assertion is signed. All the signature information is conveyed in the <ds:signature> element, lines 7-47. Thus this assertion's origin and its integrity are assured. Since this assertion is the same as the one in the first example above, other than having a signature added, the second example below addresses the same Security Considerations aspects, plus those requiring a Signature.




 1 <Assertion ID="_a75adf55-01d7-40cc-929f-dbd8372ebdfc"
 2    IssueInstant="2003-04-17T00:46:02Z" Version="2.0"
 3    xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
 4    <Issuer>
 5       example.com
 6    </Issuer>
 7    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
 8       <ds:SignedInfo>
 9          <ds:CanonicalizationMethod
10             Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
11          <ds:SignatureMethod
12           Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
13          <ds:Reference
14           URI="#_a75adf55-01d7-40cc-929f-dbd8372ebdfc">
15             <ds:Transforms>
16                <ds:Transform
17                    Algorithm=
18          "http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
19                <ds:Transform
20                   Algorithm=
21                      "http://www.w3.org/2001/10/xml-exc-c14n#">
22                   <InclusiveNamespaces
23                      PrefixList="#default saml ds xs xsi"
24                      xmlns=
25                       "http://www.w3.org/2001/10/xml-exc-c14n#"/>
26                </ds:Transform>
27             </ds:Transforms>
28             <ds:DigestMethod
29              Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
30             <ds:DigestValue>
31                Kclet6XcaOgOWXM4gty6/UNdviI=
32             </ds:DigestValue>
33          </ds:Reference>
34       </ds:SignedInfo>
35       <ds:SignatureValue>
36         hq4zk+ZknjggCQgZm7ea8fI7...Hr7wHxvCCRwubfZ6RqVL+wNmeWI4=
37       </ds:SignatureValue>
38       <ds:KeyInfo>
39          <ds:X509Data>
40              <ds:X509Certificate>
41     MIICyjCCAjOgAwIBAgICAnUwDQYJKoZIhvcNAQEEBQAwgakxNVBAYTAlVT
42     MRIwEAYDVQQIEwlXaXNjb .....  dnP6Hr7wHxvCCRwubnZAv2FU78pLX
43     8I3bsbmRAUg4UP9hH6ABVq4KQKMknxu1xQxLhpR1ylGPdioG8cCx3w/w==
44              </ds:X509Certificate>
45          </ds:X509Data>
46       </ds:KeyInfo>
47    </ds:Signature>
48    <Subject>
49       <NameID
50         Format=
51       "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
52         Alice@example.com
53       </NameID>
54       <SubjectConfirmation
55        Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches"/>
56    </Subject>
57    <Conditions NotBefore="2003-04-17T00:46:02Z"
58                NotOnOrAfter="2003-04-17T00:51:02Z">
59       <AudienceRestriction>
60          <Audience>
61             example2.com
62          </Audience>
63       </AudienceRestriction>
64    </Conditions>
65    <AttributeStatement>
66       <saml:Attribute
67    xmlns:x500=
68      "urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"
69    NameFormat=
70      "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
71    Name="urn:oid:2.5.4.20"
72    FriendlyName="telephoneNumber">
73          <saml:AttributeValue xsi:type="xs:string">
74                +1-888-555-1212
75          </saml:AttributeValue>
76       </saml:Attribute>
77    </AttributeStatement>
78 </Assertion>

 Figure 3: Signed SAML Assertion Illustrating Conveyance of Subject Attribute 



5. References

[I-D.ietf-sip-saml] Tschofenig, H., “SIP SAML Profile and Binding,” draft-ietf-sip-saml-00 (work in progress), June 2006.
[OASIS.saml-bindings-2.0-os] Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E. Maler, “Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0,” OASIS Standard saml-bindings-2.0-os, March 2005.
[OASIS.saml-conformance-2.0-os] Mishra, P., Philpott, R., and E. Maler, “Conformance Requirements for the Security Assertion Markup Language (SAML) V2.0,” OASIS Standard saml-conformance-2.0-os, March 2005.
[OASIS.saml-core-2.0-os] Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” OASIS Standard saml-core-2.0-os, March 2005.
[OASIS.saml-glossary-2.0-os] Hodges, J., Philpott, R., and E. Maler, “Glossary for the Security Assertion Markup Language (SAML) V2.0,” OASIS Standard saml-glossary-2.0-os, March 2005.
[OASIS.saml-metadata-2.0-os] Cantor, S., Moreh, J., Philpott, R., and E. Maler, “Metadata for the Security Assertion Markup Language (SAML) V2.0,” OASIS Standard saml-metadata-2.0-os, March 2005.
[OASIS.saml-profiles-2.0-os] Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, “Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,” OASIS Standard OASIS.saml-profiles-2.0-os, March 2005.
[OASIS.saml-sec-consider-2.0-os] Hirsch, F., Philpott, R., and E. Maler, “Security and Privacy Considerations for the OASIS Security Markup Language (SAML) V2.0,” OASIS Standard saml-sec-consider-2.0-os, March 2005.
[OASIS.sstc-saml-exec-overview-2.0-cd-01] Madsen, P. and E. Maler, “SAML V2.0 Executive Overview,” OASIS SSTC Committee Draft sstc-saml-exec-overview-2.0-cd-01, April 2005.
[OASIS.sstc-saml-tech-overview-2.0-draft-08] Hughes, J. and E. Maler, “Security Assertion Markup Language (SAML) V2.0 Technical Overview,” OASIS SSTC Working Draft sstc-saml-tech-overview-2.0-draft-08, September 2005.


Author's Address

  Jeff Hodges
  NeuStar
  2000 Broadway Street
  Redwood City, CA 94063
  US
Email:  Jeff.Hodges@neustar.biz