SAML Tokens and Claims

Security Assertions Markup Language (SAML) tokens are XML representations of claims. By default, SAML tokens Windows Communication Foundation (WCF) uses in federated security scenarios are issued tokens.

SAML tokens carry statements that are sets of claims made by one entity about another entity. For example, in federated security scenarios, the statements are made by a security token service about a user in the system. The security token service signs the SAML token to indicate the veracity of the statements contained in the token. In addition, the SAML token is associated with cryptographic key material that the user of the SAML token proves knowledge of. This proof satisfies the relying party that the SAML token was, in fact, issued to that user. For example, in a typical scenario:

  1. A client requests a SAML token from a security token service, authenticating to that security token service by using Windows credentials.

  2. The security token service issues a SAML token to the client. The SAML token is signed with a certificate associated with the security token service and contains a proof key encrypted for the target service.

  3. The client also receives a copy of the proof key. The client then presents the SAML token to the application service (the relying party) and signs the message with that proof key.

  4. The signature over the SAML token tells the relying party that the security token service issued the token. The message signature created with the proof key tells the relying party that the token was issued to the client.

From Claims to SamlAttributes

In WCF, statements in SAML tokens are modeled as SamlAttribute objects, which can be populated directly from Claim objects, provided the Claim object has a Right property of PossessProperty and the Resource property is of type String. For example:

Claim myClaim = new Claim(
    ClaimTypes.GivenName, "Martin", Rights.PossessProperty);
SamlAttribute sa = new SamlAttribute(myClaim);
Dim myClaim As New Claim(ClaimTypes.GivenName, "Martin", _
Dim sa As New SamlAttribute(myClaim)

When SAML tokens are serialized in messages, either when they are issued by a security token service or when they are presented by clients to services as part of authentication, the maximum message size quota must be sufficiently large to accommodate the SAML token and the other message parts. In normal cases, the default message size quotas are sufficient. However, in cases where a SAML token is large because it contains hundreds of claims, you may need to increase the quotas to accommodate the serialized token. For more information, seeSecurity Considerations for Data.

From SamlAttributes to Claims

When SAML tokens are received in messages, the various statements in the SAML token are turned into IAuthorizationPolicy objects that are placed into the AuthorizationContext. The claims from each SAML statement are returned by the ClaimSets property of the AuthorizationContext and can be examined to determine whether to authenticate and authorize the user.

See Also

How to: Create a Federated Client
How to: Configure Credentials on a Federation Service
Managing Claims and Authorization with the Identity Model
Claims and Tokens
Claim Creation and Resource Values
How to: Create a Custom Claim