Tag Archives: identity

Alice in Claims: the anatomy of a token


This is the fourth post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first three were:

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.

    IssueInstant="2010-07-04T22:57:50.284Z" Version="2.0"
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />

  • 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”.

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


For completeness, the next XML fragment presents the signature contents.

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        Algorithm="http://www.w3.org/…/xml-exc-c14n#" />
        Algorithm=http://www.w3.org/…#rsa-sha256 />
             Algorithm=http://...#enveloped-signature />
             Algorithm="http://…/xml-exc-c14n#" />
          Algorithm=http://www.w3.org/…#sha256 />
  <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
  • 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.

Alice in Claims: protocols


This is the third post of a series about claims based identity management and the Windows Identity Foundation (WIF).

The first two were:

The previous post presented the claims model, namely concepts such as identity provider, identity consumer, claims and security tokens. In this one, we will describe some of the protocols available for the communication between providers and consumers, namely for requesting security tokens and exchanging them.

Passive protocols

The following figure shows a typical interaction between the Identity Provider (IdP) and the Identity Consumer (a web app), when the user agent is a browser without javascript code (passive client).


  1. The protocol begins by Alice’s browser making the initial HTTP request to the web app.
  2. Since this request does not contain any identity information, the response is a redirect to the IdP. Alice’s browser fulfills this redirect by sending a GET request to the IdP. The redirect target URL contains information contextualizing the request, namely the identity of the requesting web app.
  3. After this request, typically there is an interaction between the IdP and Alice’s browser with the purpose of authenticating the user. For example, the IdP may respond with an HTML form for username+password authentication, which is followed by a POST containing this information, sent by Alice’s browser. This interaction may also include a step where the IdP and Alice agree on the issued claims, which is useful when Alice wants some control over releasing parts of her identity.
  4. Finally, the IdP responds with a security token containing the issued claims. This response may be:
    1. A redirect to the web app, with the token encoded in the target URL, or
    2. An auto submitting HTML form, containing the token in an hidden field. The form’s target is the web app.

Both the WS-Federation and SAML protocols use the interactions described above. The SAML protocols have some variants not described above, namely the artifact binding.

These protocols are named passive, because the user agent (Alice’s browser) does not plays an active role in the protocols. It just has to play the HTTP protocol game. Namely, no browser javascript support is required.

Active protocols

In the active protocols, the user-agent plays an active role in the protocols.


  1. The protocol starts by the user agent directly requesting a token from the IdP. This request must contain all the information required for the IdP to authenticate the requesting user and determine the claims to issue.
  2. Next, the IdP responds with the issued token.
  3. Finally, the user agent sends the request to the Identity Consumer (typically a service), with the token attached.

The WS-Trust is an example of an active protocols based using the SOAP and WS-* specifications.

In the next post we will show some examples of security tokens, namely the SAML assertion format.

Alice in Claims: the claims model


This is the second post of a series about claims based identity management and the Windows Identity Foundation (WIF).

The first one presented a scenario with decentralized identity authority. This posts uses this scenario to introduce the claims based model.

The following figure serves two goals:

· It presents the main claims model concepts, and

· Concretizes this concepts in the presented scenario


Claims model concepts

  • Identity is represented by a set of claims, where a claim is a declaration made by an entity. In this scenario, Alice, LeadDev, IssueMgr and IssueView are examples of claims that represent’s Alice’s identity.
  • An Identity Provider (or Issuer) is an entity that issues identity claims, typically containing information for which it is authoritative. In this scenario, WeDev is the identity provider, and it issues name and role claims (e.g Alice and IssueMgr).
  • An Identity Consumer (or Relying Party) is an entity that uses (consumes, relies on) identity claims. In the above example, the consumer is CloudTrack, which uses the consumed claims to make the authorization decisions..
  • A Security Token is a set of claims securely packaged for transportation between participants. This packaging ensures properties such as
    • Privacy: only the authorized receiver of the token is able to access the contained claims. This typically is obtained by encrypting the token to the authorized receiver.
    • Claim integrity and issuer authentication: the token receiver is able to determine the original claims producer. Usually, this property is achieved by the issuer digitally signing the token.
    • Subject authentication and proof of possession: the token receiver is able to determine who is the subject of the claims. The two more common proof of possession methods are
      • Bearer – any entity who has the token can allege that it is the claims subject. This is similar to bearer checks or bus tickets.
      • Holder of key – the claims subject is any entity who proves possession of a related key (e.g. by signing the message where the token is attached).


The “Proposal for a Common Identity Framework: A User-Centric Identity Metasystem” contains an interesting taxonomy of claims

  • Claims are divided between primordial and substantive
    • Primordial (or primitive) claims are proofs presentable by only one subject
    • Substantive claims are claims produced by claims providers, typically after the subject presenting a primordial or other substantive claim.
  • Substantive claims are further subdivided in
    • Static – properties of the subject (e.g. National Identifier Number; Date-of-Birth)
    • Derived – derived from other claims (e.g. Portuguese Citizen; Over-18)
    • Membership – role or group membership, relation with other subject (e.g. Administrator; Lead Developer; Purchase Officer)
    • Capability – authorization to something (e.g. Can-emit-purchase-order; Can-admin-CI-server)
    • Contextual – information about the context (e.g. Authentication method, location and time)

Claims transformers

A Claims Transformer is an entity or module that produces claims based on claims that it receives (consumes).

For instance, in above scenario, the WeDev identity provider can also be seen as a claims transformer since it produces the name and role claims (substantive claims) upon receiving and validating Alice’s credentials (primordial claims).

We also can see the CloudTrack’s web app as divided in to two modules:

  • The first module is a claims transformer, transforming the input role claims (LeadDev) into application specific roles (IssueMgr) and authorization roles (IssueView).
  • The second module is an identity consumer, using the input authorization claims (IssueView) to decide if the access is allowed or not.

Notice that the claims exchange between these two modules doesn’t have to use a token, since no unprotected communication channel is used.

In the next post, we will present some of the protocols that are used for requesting and communicating claims and tokens.

Geneva’s Beta 2 Authorization

The beta 2 “Geneva” framework contains the concept of a claims authorization manager, represented by the ClaimsAuthorizationManager base class. This class contains a single method

public virtual bool CheckAccess(AuthorizationContext context)

that computes the authorization decision for the access represented by context. This object, of AuthorizationContext type, contains the following properties

  • Subject, of IClaimsPrincipal type, represents the subject performing the access.
  • Resource, of Collection<Claim> type, represents the accessed resource.
  • Action, of Collection<Claim> type, represents the action to be performed on the resource.

The CheckAccess method is called in three distinct cases.

On a WCF scenario, the CheckAccess method is called by the Geneva’s service authorization manager, before the service’s method is called. In this case, the AuthorizationContext’s Resource and Action properties are given, respectively, by the To and the Action message headers.

On an ASP.NET scenario, the CheckAccess method is called by the Geneva’s pipeline authorization module, before the HTTP request is delivered to the HTTP handler. In this case, the AuthorizationContext’s Resource and Action properties are given, respectively, by the HTTP request’s URL and method.


The authorization decisions are also performed when the application explicitly demands it. The Geneva framework includes a new IPermission implementation: the ClaimsPrincipalPermission. This new class is similar to the PrincipalPermission, which is used to check if the current thread’s principal has the demanded identity characteristics (name and/or roles). However, there are two significant differences.

First, the ClaimsPrincipalPermission is based on the new claims model, namely it expects that the current principal is an instance of ClaimsPrincipal.

Second, the ClaimsPrincipalPermission does not receives the demanded claims. Instead, it only receives the (resource, action) pair that the principal permission is guarding. This solves one of the problems associated with the PrincipalPermission class: the need to explicitly pass the roles in the creation of PrincipalPermission objects, which typically meant the hard-coding of roles in the application code.

The resource and action information, added with the current principal, is used to build an authorization context that is passed to the CheckAccess method of the configured claims authorization manager.

This new permission also has an associated attribute, ClaimsPrincipalPermissionAttribute, for declarative demanding.

Geneva’s Beta 2 Claims Model

This week was released the beta 2 of the “Geneva” framework. This framework aims to provide an unified model for claims based identity management and access control. This includes a class model for representing claims-based identities, showed in the next diagram.



This class model, present in the Microsoft.IdentityModel.dll assembly, is similar to the one present in the code name “Zermatt” framework. One important difference is that issuers are not represented by IClaimsIdentity objects but by simple strings. The previous Zermatt’s model seems more complete, since it contains more information about an issuer. However, this added information implies that claim inference and authorization decision processes are typically more complex. The new model aims to reduce this complexity by translating the issuer’s claims set into a string, which will be used in the claim inferences and authorization decisions. This translation is the responsibility of IssuerNameRegistry objects.

The System.IdentityModel.dll assembly, used by Windows Communication Foundation (WCF), also provides a class model for claims. However, there are significant differences between both models:

  • The System.IdentityModel.dll (SIM) model does not integrates with the IPrincipal/IIdentity principal model. The Microsoft.IdentityModel.dll (MIM) does.
  • The SIM model does not includes explicit support for claims-based delegation. The MIM model includes the concepts of delegated identity and original issuer.
  • In the SIM model, an issuer is represented by a claim set. In the MIM model, an issuer is represented by a string returned by an IssuerNameRegistry, as described above.

Zermatt’s claims model

In the last couple of posts, I’ve written about the claims and security token concepts, and also about how WCF models them:

In this post I will start writing about how these concepts are modeled in Zermatt:

The Microsoft Code Name “Zermatt” is a framework targeted for .Net developers to help them to build claims-aware applications to address today’s application security requirements using a simplified model that is open and extensible and can improve security

Disclaimer: my conclusions and remarks are based solely on public documentation and on observing the code of the beta release, so use them at your own risk.

A new claims model

Zermatt introduces a new class model for claims, implemented in the Microsoft.IdentityModel namespace and depicted in the following figure




This new model extends the classical .NET model, based on the IPrincipal and IIdentity interfaces, by creating two specialized interfaces: IClaimsPrincipal and IClaimsIdentity



The IClaimsIdentity interface, derived from the .NET framework’s IIdentity interface, represents a claims-based identity. It contains the Claims property, that references a collection of claims.
A claim is represented by the Claim class, namely by three properties:

  • ClaimType (string) containing the claim’s type
  • Value (string) with the claim’s value
  • ValueType (string) with the claim’s value type

There are some differences in the representation of claims, when compared with the “older” System.IdentityModel model.

  • In the new model, a claim value is always represented by a string. When this value is not a string but a more structured object, then this object must be serialized into a string. The ValueType property contains the type of the value represented by the string in Value. The ClaimValuesTypes class contains a set of constants with the most commonly used claim value types (strings).
    The ClaimTypes class contains a set of constants with some used claim types (strings).
  • There is no equivalent to the Right property.
  • A claim also has the following two properties, of IClaimsIdentity type:
    • The Subject property references the IClaimsIdentity partially defined by the claim.
    • The Issuer property references the identity of the claim issuer
  • There is no claim set concept. Namely, in the “new” model, each claims points to its issuer, that is modeled as a IClaimsIdentity.

The NameClaimType property of IClaimsPricipal is used to define the value of the Name property (inherited from IIdentity): this value is the value of the claim whose type equals NameClaimType.
The RoleClaimsType property has a similar goal: it defines the types of claims that define roles. This is used by classes implementing the IClaimPrincipal interface.

Finally, the IClaimsIdentity also possesses a Delegate property, of type IClaimsIdentity. This property is used in delegation scenarios, and will be described in a future post.


This new model also introduces the IClaimPrincipal as a specialization of the .NET framework’s IPrincipal interface. Namely, this new interface adds a Identities collection that references a set of IClaimIdentity.

Note that the base interface IPrincipal already had a Identity property. The new Identities property (plural) is need because a principal can be associated with several identities, e. g., on delegation scenarios.

The implementation of the IsInRole interface method should/can use the RoleClaimTypes property of the identities referenced by the Identities property.


The Zermatt’s claims model also contains an implementation of IClaimsPrincipal, called ClaimsPrincipal, with a static Current property – the IClaimsPrincipal associated with the current context.


Authorization policies in WCF: from tokens to claim sets

In a previous post, I presented some classes for handling security tokens in WCF. This post describes the process that begins with the authentication of a token and ends with a collection of claim sets, available at the AuthorizationContext (see this previous post).

One of the classes referred in the last post is the SecurityTokenAuthenticator class, containing the following method

public ReadOnlyCollection<IAuthorizationPolicy> ValidateToken(
    SecurityToken token

This method “Authenticates the specified security token and returns the set of authorization policies for the security token

Surprisingly, this method does not return a set of claims. Instead it returns a collection of IAuthorizationPolicy.

What is an authorization policy?

An authorization policy defines a rule for adding claims to a claim evaluation context. More precisely, the IAuthorizationPolicy interface has an Evaluate method that receives an EvaluationContext.


This class represents the context on which the authorization policies are evaluated. It exposes a property with a read-only collection of claim sets – the claim sets previously added to the context – and a method to add claims sets to the context. So, an authentication policy, via the Evaluate method, conditionally adds claim sets into the context based on the claim sets already there. This conditional addition can be used to implement claim normalization or claim inference policies.

An example of claim normalization is a policy that adds the claim “Teacher of X” to the context if it contains the claims “Professor of X” or “Teaching Assistant of X”. In this case, normalization means to represent a set of syntactically different (but semantically equal claims) by only one claim.

An example of claim inference is a policy that adds the claim “Authorized to post CS101 grades” if the context already contains the claim “Teacher of CS101”.

Unconditional policies

A particular case of policy is the unconditional authorization policy, i. e., a policy that always add the same claims sets to the evaluation context, independently of the claim sets already there. These are the type of authorization policy typically returned by token authenticators.

Policy evaluation process

The policy evaluation process uses policies from two origins:

  • Policies resulting from token authentication. These policies represent the claims issued to the message originator.
  • External policies, representing additional policy rules (e.g. normalization and inference rules).


The claim sets resulting from the policy evaluation process are inserted into the AuthorizationContext.

Since there might be interdependencies between the policies, the policy evaluation process can call the Evaluate method of the same policy more than once. An example of interdependent policies is:

  • P1 (external policy): Add “Authorized to post CS101 grades” if “Teacher of CS101”.
  • P2 (external policy): Add “Teacher of CS101” if “Professor of CS101” or “Teaching Assistant of CS101”.
  • P3 (token policy): Add “Professor of CS101” unconditionally.

In this example, P2 must be evaluated after P3 adds the “Professor of CS101” claim, and P1 must be evaluated after P2 adds the “Teacher of CS101” claim. This results in more that one call to the Evaluate method, since there is no predefined order between the policies.

When a policy wants to be called again if additional claim sets are inserted by other policies, its Evaluate method must return false. If this method returns true, it means that no more claim sets will be added by the policy.

The policy evaluation process keeps repeatedly evaluating all the policies while

  • At least one policy returns false (meaning that it wants to be called again if new claim sets are added)
  • And the last policy evaluation cycle resulted in at least one new claim set added to the context.

If we model a authorization policy as a function mapping claim sets into claim sets, then the result of this evaluation process is the least fixed point of the policy set.

Security tokens in WCF

In WCF, security tokens are represented by classes derived from the SecurityToken abstract class. However, this class exposes little functionality:

  • A SecurityKeys property, to access the keys associated with this token.
  • Two properties, ValidFrom and ValidTo, with the token’s validity period.
  • A couple of methods for creating and matching key identifiers.

Most of the functionality related to security tokens is associated with three classes:

  • SecurityTokenProvider abstract class – Defines the interface for the creation of security tokens, i. e., for token factories. Typically, there is one concrete derived class for each token type (e. g. X509SecurityTokenProvider).
    Instances of classes derived from this one are used by the security protocol channel, at the message originator side, to create the tokens that are attached to the sent messages.


  • SecurityTokenSerializer abstract class – Defines the interface for serialization/deserialization into/from XML (XmlWriter/XmlReader) of token instances. The majority of token types are handled by the concrete WSSecurityTokenSerializer class.
    Instances with this type are used both at the message originator side and at the message recipient side.


  • SecurityTokenAuthenticator abstract class – Defines the interface for token verification and also for extracting the token’s claims. Typically, there is one concrete derived class for each token type (e. g. X509SecurityTokenAuthenticator).
    Instances with this type are used by the security protocol channel, at the message recipient side, to validate and extract the claims from the tokens attached to the received messages.

The figure below shows these classes, with some members hidden for legibility.



How are the provider/serializer/authenticator instances created?

The WCF runtime uses an object with type SecurityTokenManager (abstract class) to create a provider/serializer/authenticator instance, via the methods:

  • public abstract SecurityTokenProvider CreateSecurityTokenProvider(
        SecurityTokenRequirement tokenRequirement
  • public abstract SecurityTokenSerializer CreateSecurityTokenSerializer(
        SecurityTokenVersion version
  • public abstract SecurityTokenAuthenticator CreateSecurityTokenAuthenticator(
        SecurityTokenRequirement tokenRequirement,
        out SecurityTokenResolver outOfBandTokenResolver

How is the SecurityTokenManager instance created? 

Both the ClientCredentials and ServiceCredentials classes derives from the abstract class SecurityCredentialsManager, that contains a CreateSecurityTokenManager method.

Note that the ClientCredentials and ServiceCredentials classes hold the security configuration settings. These settings are reflected on the used token provider/serializer/authenticator via the chain of factories

  • ClientCredentials and ServiceCredentials creates SecurityTokenManager
  • SecurityTokenManager creates SecurityToken[Provider|Serializer|Authenticator]