Frequently Asked Questions

[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.]

Frequently Asked Questions

ActAs and OnBehalfOf

Q: What is the difference between ActAs and OnBehalfOf?

From the WS-Trust procotol standpoint:

• An ActAs RST element indicates that the requestor wants a token that contains claims about two distinct entities: the requestor, and an external entity represented by the token in the ActAs element.

• An OnBehalfOf RST element indicates that the requestor wants a token that contains claims only about one entity: the external entity represented by the token in the OnBehalfOf element.

The ActAs feature is typically used in scenarios that require composite delegation, where the final recipient of the issued token can inspect the entire delegation chain and see not just the client, but all intermediaries. This lets it perform access control, auditing and other related activities based on the entire identity delegation chain. The ActAs feature is commonly used in multi-tiered systems to authenticate and pass information about identities between the tiers without having to pass this information at the application/business logic layer.

The OnBehalfOf feature is used in scenarios where only the identity of the original client is important and is effectively the same as the identity impersonation feature available in Windows. When OnBehalfOf is used, the final recipient of the issued token can only see claims about the original client, and the information about intermediaries is not preserved. One common pattern where the OnBehalfOf feature is used is the proxy pattern where the client cannot access the STS directly but instead communicates through a proxy gateway. The proxy gateway authenticates the caller and puts information about the caller into the OnBehalfOf element of the RST message that it then sends to the real STS for processing. The resulting token contains only claims related to the client of the proxy, making the proxy completely transparent to the receiver of the issued token.

Note that WIF does not support <wsse:SecurityTokenReference> or <wsa:EndpointReferences> as a child of <wst:OnBehalfOf>. The WS-Trust specification allows for three ways to identity the original requestor (on behalf of whom the proxy is acting). These are:

1. Security token reference. A reference to a token, either in the message, or possibly retrieved out of band).

2. Endpoint reference. Used as a key to look up data, again out of band.

3. Security token. Identifies the original requestor directly.

WIF supports only security tokens, either encrypted or unencrypted, as a direct child element of <wst:OnBehalfOf>.

IIS Request Size Limit

Q: Why do I get a 400 Bad Request - Request Too Large error when using Cardspace or WS-Fed?

A: Please see http.sys Registry Settings for IIS. This article describes IIS settings. The two settings of interest are:

• MaxFieldLength: Sets an upper limit for each header. This limit translates to approximately 32k characters for a URL.

• MaxRequestBytes: Determines the upper limit for the total size of the Request line and the headers. Its default setting is 16KB. If this value is lower than MaxFieldLength, the MaxFieldLength value is adjusted.

Claims Authentication Manager

Q: When is the claims authentication manager invoked?

A: The claims authentication manager is typically invoked once per session, with the following exceptions:

• For transport security, tokens present at the transport layer will invoke the claims authentication once per call, even if sessions are present.

• If there is more than one token at the message security layer, each token will invoke the claims authentication manager separately. For example, two tokens in the security header will invoke the claims authentication manager twice per session.

• The claims authentication manager is not invoked when no tokens are present: that is, for all the AnonymousForxxx authentication modes. Here, the recommendation is to use the claims authorization manager as a gatekeeper.

Note

It is recommended that you do not call Thread.CurrentPrincipal in the claims authentication manager or claims authorization manager. Rather, you should use the incomingPrincipal parameter on the Authenticate method:

class CustomClaimsAuthenticationManager : ClaimsAuthenticationManager
{
    public override IClaimsPrincipal Authenticate(string resourceName, IClaimsPrincipal incomingPrincipal)
    {
        return base.Authenticate(resourceName, incomingPrincipal);
    }
}

Duplicate RSTs and Duplicate RST Elements

Q: How does WIF handle duplicate RSTs and duplicate elements within RSTs?

A: If an RST is duplicated, only the first RST is parsed; all other RSTs are ignored. If an RST contains duplicate elements, only the last element's value is used; all other element values are ignored.

Deny-Only SIDs

Q: What is a deny-only Security Identifier (SID)?

A: For more information, see SID Attributes in an Access Token

IssuerNameRegistry

Q: How does a relying party application validate the trust relation with an issuer?

A: WIF has the concept of an IssuerNameRegistry which is an extensibility point for validating the trust relationship with an issuer. There are two ways this extensibility point can be used:

1. ConfigurationBasedIssuerNameRegistry, where you configure the signing certificate of the issuer in the relying party application’s configuration file.

2. A custom IssuerNameRegistry that can be derived from the IssuerNameRegistry class exposed in WIF. Refer to Samples\End-to-end\Authentication Assurance\AuthAssuranceRP\App_Code\TrustedIssuerNameRegistry.cs file for a sample implementation of custom IssuerNameRegistry.

Runtime Distribution

Q: My application uses WIF and requires that it be installed as a prerequisite. Can I distribute the runtime files with my application?

A: Absolutely. There is now an additional EULA for the WIF SDK that allows developers to redistribute the WIF runtime with their application when they develop an application using WIF. See the WIF SDK supplemental EULA in the list of possible downloads.

Installation

Q: Under what registry key is WIF installed?

A: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsIdentityFoundation\setup\v3.5\.

Do Not Call SecurityTokenService.Issue across Multiple Token Requests

Q: Can an STS instance be used for Issue calls across multiple token requests?

A: The WIF STS instancing model is per-call. This means that an STS instance is intended only for a single use: that is, you create a new instance of an STS, make the necessary method calls (such as Issue), and then clear that STS instance. If you try to use the same STS instance to call Issue across multiple token requests, rather than creating a new STS instance for each token request, the behavior is undefined.