SAML assertions defined in the SAML Token Profile standard

The Web Services Security SAML Token Profile OASIS standard specifies how to use Security Assertion Markup Language (SAML) assertions with the Web Services Security SOAP Message Security specification.

This product supports two versions of the OASIS SAML standard: Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V1.1 and Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

The standard describes the use of SAML assertions as security tokens in the <wsse:Security> header, as defined by the WSS: SOAP Message Security specification. An XML signature can be used to bind the subjects and statements in the SAML assertion to the SOAP message.

Subject confirmation methods define the mechanism by which an entity provides evidence (proof) of the relationship between the subject and the claims of the SAML assertions. The WSS: SAML Token Profile describes the usage of three subject confirmation methods: bearer, holder-of-key, and sender-vouches. This product supports all three confirmation methods. When using the bearer subject confirmation method, proof of the relationship between the subject and claims is implicit. No specific steps are taken to establish the relationship.

Since there is no key material associated with a bearer token, protection of the SOAP message, if required, must be performed using a transport level mechanism or another security token, such as an X.509 or Kerberos token, for message level protection. When using the holder-of-key subject confirmation method, proof of the relationship between the subject and claims is established by signing part of the SOAP message with the key specified in the SAML assertion. Since there is key material associated with a holder-of-key token, this token can be used to provide message level protection (signing and encryption) of the SOAP message.

The sender-vouches confirmation method is used when a server needs to propagate the client identity with SOAP messages on behalf of the client. This method is similar to identity assertion, but it has the added flexibility of using SAML assertions to propagate not only the client identity, but also propagate client attributes. The attesting entity must protect the vouched for SAML assertions and SOAP message content so that the receiver can verify that it has not been altered by another party. Two sender-vouches confirmation method usage scenarios are supported that ensure message protection either at the transport level or the message level. A receiver verifies that one of the following scenarios occurs:

A sender sets up a secure sockets layer (SSL) session with a receiver using client certificate authentication.
A sender digitally signs SAML assertions with the containing SOAP message using security token reference transformation algorithm. A sender can use either SSL or SOAP message encryption to protect confidentiality.

In either case, the SAML assertions are either issued by an external Security Token Services (STS) or self- issued by the application server.

Bearer assertion

A SAML assertion is a bearer assertion if it includes the bearer <saml:ConfirmationMethod> element, as defined in the OASIS Web Services Security specifications. For more information, refer to the specification documents.

A SAML Version 1.1 bearer assertion must also contain the following SubjectConfirmation element:

<saml:SubjectConfirmation> 
	 <saml:ConfirmationMethod> 
		urn:oasis:names:tc:SAML:1.0:cm:bearer
	 </saml:ConfirmationMethod>
</saml:SubjectConfirmation>

A SAML Version 2.0 bearer assertion must also contain the following SubjectConfirmation element:

<saml2:SubjectConfirmation     
      Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
</saml2:SubjectConfirmation>

Holder-of-key assertion

A SAML assertion is a holder-of-key assertion if it includes the SubjectConfirmation element containing a saml:ConfirmationMethod element with the value of holder-of-key, and a ds:KeyInfo element. For more information, refer to the specification documents.

The ds:KeyInfo information inside the SubjectConfirmation element identifies a public or secret key that is used to confirm the identity of the subject. The holder-of-key assertion also contains a ds:Signature element that protects the integrity of the confirmation ds:KeyInfo element as established by the assertion authority.

A SAML Version 1.1 holder-of-key assertion must contain the following SubjectConfirmation element:

<saml:SubjectConfirmation> 
  <saml:ConfirmationMethod> 
   urn:oasis:names:tc:SAML:1.0:cm: holder-of-key
   </saml:ConfirmationMethod>
  <ds:KeyInfo>
  <ds:KeyValue>. . .</ds:KeyValue>
  </ds:KeyInfo>
</saml:SubjectConfirmation>

A SAML Version 2.0 holder-of-key assertion must contain the following SubjectConfirmation element:

<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:holder-of-key">
    <saml2:SubjectConfirmationData>
			<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    ......
			</ds:KeyInfo>
     </saml2:SubjectConfirmationData>
</saml2:SubjectConfirmation>

Sender-vouches assertion

A SAML assertion is a sender-vouches assertion if it includes the sender-vouches <saml:ConfirmationMethod> element, as defined in the OASIS Web Services Security specifications. A SAML Version 1.1 sender-vouches assertion must contain the following SubjectConfirmation element:

<saml:SubjectConfirmation> 
	 <saml:ConfirmationMethod> 
		urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
	 </saml:ConfirmationMethod>
</saml:SubjectConfirmation>

A SAML Version 2.0 sender-vouches assertion must contain the following SubjectConfirmation element:

<saml2:SubjectConfirmation 
          Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches">
</saml2:SubjectConfirmation>

Symmetric key in the holder-of-key assertion

A SAML holder-of-key assertion is used as a protection token. This type of protection token can use a symmetric key as a proof key. The client uses the proof key to demonstrate to the relying party that the client actually owns the issued SAML token. When a Security Token Service (STS) issues a SAML token that uses a symmetric proof key, the token contains a key that is encrypted for the target service. The STS also sends the same proof key to the requester in a <RequestedProofToken> element as part of the RequestSecurityTokenResponse (RSTR). The web service client then presents the SAML token to the target service, also known as the relying party, and signs the application message with the received proof key.

The STS can be pre-configured to issue a symmetric proof key. Typically, the following two parameters are specified inside the RequestSecurityTokenTemplate in the RequestSecurityToken (RST) when the symmetric key is requested from the STS:

<t:KeyType> http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
  </t:KeyType>
<t:KeySize>256</t:KeySize>

The following sample SubjectConfirmation element contains a SymmetricKey encrypted for the relying party.

<saml:SubjectConfirmation>
      <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key</saml:ConfirmationMethod> 
          <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
             <enc:EncryptedKey xmlns:enc="http://www.w3.org/2001/04/xmlenc#">
             <enc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
          <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
             </enc:EncryptionMethod>
          <ds:KeyInfo>
            <ds:X509Data>
              <ds:X509Certificate>MIIB3 . . . vO3bdg</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
     <enc:CipherData>
         <enc:CipherValue>P5Kb . . . rOTvII</enc:CipherValue> 
            </enc:CipherData>
            </enc:EncryptedKey>
     </ds:KeyInfo>
</saml:SubjectConfirmation>

Public key in the holder-of-key assertion

When a SAML holder-of-key assertion is used as a protection token, the token can use a public key as a proof key. The client uses the proof key to demonstrate to the relying party that the client actually owns the issued SAML token. The advantage of a public proof key over a symmetric key is that the client does not share the secret key with the Security Token Service (STS) and relying party. The public proof key can be an X509 certificate, or a Rivest Shamir Adleman (RSA) public key.

The STS can be pre-configured to issue a public key as a proof key. Typically, the parameter <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType> is specified inside a RequestSecurityTokenTemplate as part of the RequestSecurityToken (RST) when the public key is requested from the STS. The optional UseKey element could also be used by the client to indicate the key, as follows:

<trust:UseKey>
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <X509Data>
        <X509Certificate>MIIGCzCCBPOgAwIBAgIQcSgVwaoQv6dG. . .1GqB
        </X509Certificate>
      </X509Data>
    </KeyInfo> 
</trust:UseKey>

The following example is a SubjectConfirmation that contains a PublicKey proof key.

<saml:SubjectConfirmation>
         <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key</saml:ConfirmationMethod> 
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:KeyValue>
                    <ds:RSAKeyValue>
                      <ds:Modulus>hYHQm. . . ZnH1S0=</ds:Modulus> 
            <ds:Exponent>AQAB</ds:Exponent> 
                    </ds:RSAKeyValue>
                </ds:KeyValue>
            </ds:KeyInfo>
</saml:SubjectConfirmation>