ClaimsAuthenticationManager, ClaimsAuthorizationManager, and OriginalIssuer
[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]
ClaimsAuthenticationManager lets you perform claims transformation, including adding, modifying, and deleting claims extracted from an incoming token before they are received by your RP application. It provides a single place to authenticate claims. This is a common place between an ASP.NET and a WCF application where you ask the question: “Do I trust the issuer to make these claims?”
To intercept incoming claims, create a class that derives from ClaimsAuthenticationManager and implements its only method, Authenticate. Just before your RP application receives the claims extracted from the token, WIF calls this method and passes in a ClaimsIdentityCollection that contains claims extracted from an incoming token. You can modify this collection and then return it from the method. Your RP application then receives the modified collection of claims.
To use ClaimsAuthenticationManager, you must also add it to your RP’s application configuration file, or set it on the ClaimsAuthenticationManager of the ServiceConfiguration object. For more information about the ServiceConfiguration object, see Configuration.
ClaimsAuthorizationManager provides a single place to authorize or deny incoming requests before they are received by your RP application. This is the place where you ask the question: “Do I allow the requestor to take this action on this resource?”
To intercept incoming requests, create a class that derives from ClaimsAuthorizationManager and implements its only method, CheckAccess. The AuthorizationContext parameter contains the following members:
Action, a collection of Claims that represents the action.
Principal, the IClaimsPrincipal of the requestor.
Resource, a collection of Claims that represents the resource.
AuthorizationContext.Action corresponds to
ClaimsPrincipalPermission.Operation, not to
AuthorizationContext.Resource corresponds to
To use ClaimsAuthorizationManager, you must also add it to your RP’s application configuration file, or set it on the ClaimsAuthorizationManager of the ServiceConfiguration object. For more information about the ServiceConfiguration object, see Configuration.
Note that for WCF service endpoints, the resource passed to the ClaimsAuthorizationManager is typically an endpoint URI. This is true for the following endpoints:
REST services invoked with the POST method.
ASP.NET applications with a ClaimsAuthorizationModule that are invoked with the POST method.
This is not true for the following endpoints:
REST services invoked with the GET method.
ASP.NET applications with a ClaimsAuthorizationModule that are invoked with the GET method.
To authorize or deny requests based on the endpoint URI, you cannot perform a strict string comparison, because the URI varies per request depending on the request string query parameters.
Also note that you should not make authorization decisions in asynchronous callback methods, as the ClaimsAuthorizationManager is not invoked for these methods. You can make authorization decisions in a Beginxxx method, but not in an asynchronous callback or Endxxx method.
When your relying party application (RP) is required to make a policy decision based on the STS that originally issued the claim, you can use the OriginalIssuer property. This property is set by the Security Token Service (STS) that issues the token that contains the claim.
As an example, suppose your RP receives a token from its Relying Party STS (RP-STS). The RP-STS itself trusts multiple Identity Provider STSes (IP-STSes). The RP trusts its RP-STS, which by extension means that it trusts the IP-STSes also. However, the RP must make a policy decision based on whether the token contains claims that were originally issued by the RP-STS or by one of the IP-STSes. The OriginalIssuer property lets it do so.
The value of the OriginalIssuer property is not cryptographically verifiable. Therefore you can use it to make policy decisions, but you should not use it to make security decisions.
An STS in a delegation chain must preserve the value of OriginalIssuer on all the claims it received while issuing another token that contains these claims.