Introduction
This is the fourth post in a series about claims based identity management and the Windows Identity Foundation (WIF).
The first three were:
- Alice in Claims: decentralized identity
- Alice in Claims: the claims model
- Alice in Claims: protocols
The previous post presented the protocols for requesting and exchanging security tokens between identity providers and identity consumers. In this post, we dissect the structure of a commonly used token type: SAML assertions.
A SAML assertion
The following excerpt shows the high-level structure of a SAML 2.0 assertion.
<Assertion
ID="_6c955290-65d2-4b84-8f95-a2c200619f60"
IssueInstant="2010-07-04T22:57:50.284Z" Version="2.0"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<Issuer>http://identity-provider-url</Issuer>
<ds:Signature>...</ds:Signature>
<Subject>
<SubjectConfirmation
Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />
</Subject>
<Conditions
NotBefore="2010-07-04T22:57:50.225Z"
NotOnOrAfter="2010-07-04T23:57:50.225Z">
<AudienceRestriction>
<Audience>
https://identity-consumer-url
</Audience>
</AudienceRestriction>
</Conditions>
<AttributeStatement>
...
</AttributeStatement>
<AuthnStatement
AuthnInstant="2010-07-04T22:57:49.396Z">
...
</AuthnStatement>
</Assertion>
- The top-level element is the Assertion element.
- The Assertion/Issuer element defines the token issuer’s identity, in the form of an URL.
- The Assertion/ds:Signature contains a signature computed over the assertion contents.
- The Assertion/Subject contains information regarding the assertion’s subject, i. e., to whom or what do the contained claims apply. This information is carried in the SubjectConfirmation element, which in this case states that this token is a bearer token: the token subject is anyone in possession of the token.
- The Assertion/Condition define the conditions for token acceptance by a consumer, which in this case are:
- Time period (NotBefore and NotOnOrAfter attributes)
- Consumer identity (AudienceRestriction element). Any consumer that does not match any of the audience restriction URLs should not accept the token.
- Finally, the Assertion/AttributeStatement and Assertion/AuthnStatement contains the issued claims, which will be detailed next.
Attribute statement
The following XML excerpt shows the AttributeStatement contents, defining the issued claims:
- One name claim (type = “http://…/name”) with value “Alice”
- Two role claims (type = “http://…/role”) with values “Developer” and “LeadDeveloper”.
<AttributeStatement>
<Attribute Name=http://…xmlsoap.org/ws/…/claims/name>
<AttributeValue>Alice</AttributeValue>
</Attribute>
<Attribute Name=http://….microsoft.com/ws/…/claims/role>
<AttributeValue>Developer</AttributeValue>
<AttributeValue>LeadDeveloper</AttributeValue>
</Attribute>
</AttributeStatement>
Authentication Statement
Finally, the next XML fragment shows the AuthnStatement element containing the authentication type claim, also called authentication context. In this example, Alice used a password based mechanism to authenticate herself when requesting the claims from the identity provider.
<AuthnStatement AuthnInstant="2010-07-04T22:57:49.396Z">
<AuthnContext>
<AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
</AuthnContextClassRef>
</AuthnContext>
</AuthnStatement>
Signature
For completeness, the next XML fragment presents the signature contents.
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/…/xml-exc-c14n#" />
<ds:SignatureMethod
Algorithm=http://www.w3.org/…#rsa-sha256 />
<ds:Reference
URI="#_6c955290-65d2-4b84-8f95-a2c200619f60">
<ds:Transforms>
<ds:Transform
Algorithm=http://...#enveloped-signature />
<ds:Transform
Algorithm="http://…/xml-exc-c14n#" />
</ds:Transforms>
<ds:DigestMethod
Algorithm=http://www.w3.org/…#sha256 />
<ds:DigestValue>...</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...</ds:SignatureValue>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>...</X509Certificate>
</X509Data>
</KeyInfo>
</ds:Signature>
- The Signature/Element defines the signed data, which is this case is the complete SAML Assertion. Note that the URI attribute matches the ID attribute in the Assertion element. Since the signature is inside the signed data, an “enveloped-signature” transform is used.
- The Signature/KeyInfo/X509Data/X509Certificate contains the issuer’s certificate. There are several WIF configuration aspects that relate to this certificate, so its existence should be noted.