|
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.
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.).
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.
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.).
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.
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).
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.
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 |
| Jeff Hodges | |
| NeuStar | |
| 2000 Broadway Street | |
| Redwood City, CA 94063 | |
| US | |
| Email: | Jeff.Hodges@neustar.biz |