A SAML Whitepaper                                              J. Hodges
                                                            Unaffiliated
                                                        November 4, 2008


                      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] 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].

   This relationship between SAML specifications, as well as SAML-
   dependent specifications, is illustrated below in Figure 1.  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-05 ]           |                     |
   |                                         |  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 and Protocols" specification, also
   known as the "SAML Core" specification, 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] (note that this specification is called
   out in the "SAML Profiles" box in Figure 1).  An example of a
   different, non-Web-SSO SAML profile is given in [I-D.ietf-sip-saml].


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":


   o  Begin by studying various SAML Profiles, e.g. those given in
      [OASIS.saml-profiles-2.0-os] and [I-D.ietf-sip-saml].  One will
      likely find the SAML Technical Overview whitepaper
      [OASIS.sstc-saml-tech-overview-2.0-draft-16] helpful in this
      endeavor.  It provides a detailed, illustrated expose of several
      of the SAML Web SSO profiles along with driving use cases.


   o  Refer to the SAML bindings specifications that the profiles you
      are studying refer to, e.g.  [OASIS.saml-bindings-2.0-os].


   o  Only refer to the SAML Core specification [OASIS.saml-core-2.0-os]
      as necessary for definitions and semantics of particular items
      refered to in the profiles and bindings you are studying.

      Also, refer to the other SAML specifications and documents as
      necessary:


      *  The SAML glossary [OASIS.saml-glossary-2.0-os] defines many of
         the key terms used throughout the SAML specification set.


      *  SAML profiles often reference the SAML Metadata specification
         [OASIS.saml-metadata-2.0-os].  This spec defines how one
         "discovers" various configuration aspects of a SAML deployment.
         Often one needs to determine this information in order to
         establish communication.


      *  The characteristics of specific SAML entity implementations--
         based upon the profiles in [OASIS.saml-profiles-2.0-os], such
         as a "SAML Authority", or a "SAML-based service provider"--are
         given in the SAML Conformance specification
         [OASIS.saml-conformance-2.0-os].


      *  Various security aspects of the SAML profiles and bindings
         given in the SAMLv2 specification set are discussed and
         analyzed in the SAML Security Considerations specification
         [OASIS.saml-sec-consider-2.0-os].


   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].

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:

   o  The SAML assertion must contain at least one authentication
      statement and no other statements.  The relying party must be
      represented in the <AudienceRestriction> element.  The
      SubjectConfirmation Method must be Foo. etc.


   o  The SAML assertion must contain at least one attribute statement
      and may contain more than one.  The values for the subject's
      profile attributes named "Foo" and "Bar" must be present.  An
      authentication statement may be present. etc.


   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].

   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] 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.

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].  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]).  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, 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, 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., Hodges, J., Peterson, J., Polk, J., and D.
              Sicker, "SIP SAML Profile and Binding",
              draft-ietf-sip-saml-05 (work in progress), November 2008.

   [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-16]
              Ragouzis, N., Hughes, J., Philpott, R., Maler, E., Madsen,
              P., and T. Scavo, "Security Assertion Markup Language
              (SAML) V2.0 Technical Overview", OASIS SSTC Working
              Draft sstc-saml-tech-overview-2.0-draft-16, May 2008.


Author's Address

   Jeff Hodges
   Unaffiliated

   Email: Jeff.Hodges@KingsMountain.com