Compartilhar via

WCF Application Compatibility

  • Artigo

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

This topic, intended for the Windows Communication Foundation (WCF) developer who is new to Windows® Identity Foundation (WIF), and it addresses the following questions:

  • What works in WCF but no longer works in WIF?

  • What new features are available in WIF?

How to Enable WIF on a WCF Service

You can enable WIF on an existing WCF service in two ways:

  1. Have your service call ConfigureServiceHost or one of its overloads. For more information, see How to: Programmatically Enable WIF on a WCF Service.

  2. Edit your service’s configuration file. For more information, see How to: Build a WCF Relying Party Application and Establishing Trust from a WCF Relying Party Service to an STS using FedUtil. Specifically, you must add a new behavior to the list of service behaviors, as in the following example.

    <behaviors>
    <serviceBehaviors>
        <behavior name="ClaimsAwareService1.ServiceBehavior" > 
        <!-- Behavior extension to make the service claims aware -->
        <federatedServiceHostConfiguration/>
        <!-- To avoid disclosing metadata information, set the value below to false and remove the metadata endpoint above before deployment -->
        <serviceMetadata  httpGetEnabled="true"/>
        <!-- To receive exception details in faults for debugging purposes, set the value below to true.  Set to false before deployment to avoid disclosing exception information -->
        <serviceDebug includeExceptionDetailInFaults="false"/>
        </behavior>
    </serviceBehaviors>
</behaviors>

If you have multiple services on a single application, you can choose to enable WIF on a per-service basis.

WIF is wire format compliant, so that a WIF-enabled WCF service is compatible with a WCF 3.5 client.

Changes in Windows Identity Foundation for WCF Service Developers

Enabling WIF on an existing WCF service causes the following changes:

Claims Model

  1. The claims model in WIF replaces the claims model in WCF. For more information, see Claim.

  2. Similarly, when WIF is enabled on a WCF service, the Claims property of ServiceSecurityContext.Current is no longer available. You should use Thread.CurrentPrincipal to obtain the caller’s information. The other properties of ServiceSecurityContext.Current are still available, however.

  3. OperationContext no longer contains WCF claims. Instead, you should obtain these claims from Thread.CurrentPrincipal.

Authorization

  1. WCF policy authorization objects are not supported in WIF. Typically, a WCF developer overrides GetAuthorizationPolicy to perform claims transformation. In WCF, each token authenticator contains policies that in turn contain sets of claims. By default, WCF accepts all of these policies. Claims transformation in WCF consists of accepting or rejecting these policies individually. However, in WIF, token authenticators are replaced by token handlers. Token handlers contain sets of claims, based on the new claims model. You can perform claims transformation—that is, accept or reject these claims—in the ClaimsAuthenticationManager. Overriding GetAuthorizationPolicy is no longer supported, so if you have claims transformation logic there, you should move it to a custom ClaimsAuthenticationManager.

  2. WCF authorization policy is no longer supported. Typically a WCF developer makes authorization decisions in a custom authorization manager that is plugged into the service host, based on the claims in the ServiceSecurityContext. However, WIF replaces WCF authorization policy with the ClaimsAuthorizationManager class. You should implement the methods of this class and make authorization decisions using the user’s IClaimsPrincipal, which you can obtain by calling Thread.CurrentPrincipal.

    WIF replaces the default ServiceAuthorizationManager with its own IdentityModelServiceAuthorizationManager in order to integrate into the WCF hosting environment. If you configure your ServiceAuthorizationManager before calling ConfigureServiceHost, your configuration changes will be lost. Instead, you must configure it after calling ConfigureServiceHost. If you have a custom ServiceAuthorizationManager implementation, you must change it to inherit from IdentityModelServiceAuthorizationManager. If you override GetAuthorizationPolicies in your implementation, you must call base.GetAuthorizationPolicies.

  3. Many WCF authentication settings in ServiceHost.Credentials are deprecated in WIF. The following are some of the settings that are not supported:

    • ServiceHost.Credentials.IssuedTokenAuthentication

    • ServiceHost.Credentials.ClientCertificate.Authentication

    • ServiceHost.Credentials.UserNameAuthentication

Miscellaneous

  1. In WIF, you can specify a server certificate in the <system.ServiceModel>/<behaviors>/<serviceBehavior>/<behavior>/<serviceCredentials> section of your service’s configuration file, as in the following example.

    <serviceCertificate findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" x509FindType="FindByThumbprint" />

    If you specify a server certificate in both the WIF and WCF configurations, the service uses the certificate that is specified in the WIF configuration. If you only specify a certificate in the WCF configuration, the service uses that certificate.

  2. Token handlers are the WIF equivalent of the WCF token provider, serializer, factory, and authenticator. To modify how tokens are created, serialized, and validated, override a specific token handler and place your custom handler into the token handler collection on the ServiceConfiguration.

  3. In WCF, audience URIs are automatically populated form the endpoints on the ServiceHost. In WIF, you must manually populate the AllowedAudienceUris property.

  4. For Security Assertion Markup Language (SAML) and X.509 token authentication, you must implement an IssuerNameRegistry. See the Samples\End-to-end\Authentication Assurance\AuthAssuranceRP\App_Code\TrustedIssuerNameRegistry.cs file for a sample implementation of a custom IssuerNameRegistry. Also see How to: Create a Custom Issuer Name Registry.

  5. Many WCF service configuration settings are deprecated in WIF. You can find their equivalents in the ServiceConfiguration class. The following table lists the settings available in ServiceConfiguration, and their equivalents in WCF.

    ServiceConfiguration Setting WCF Equivalent

    ClaimsAuthenticationManager

    IAuthorizationPolicy

    ClaimsAuthorizationManager

    ServiceAuthorizationManager

    ClaimsPrincipalPermissionAttribute

    PrincipalPermissionAttribute

    IssuerNameRegistry

    None

    IssuerTokenResolver

    IssuedTokenAuthentication.KnownCertificates

    SecurityTokenHandlerCollectionManager

    None

    SecurityTokenHandlers

    SecurityTokenManager

    AudienceRestriction

    IssuedTokenAuthentication.AllowedAudienceUris, IssuedTokenAuthentication.AudienceUriMode

    CertificateValidationMode

    X509ClientCertificateAuthentication.CertificateValidationMode, IssuedTokenAuthentication.CertificateValidationMode

    CertificateValidator

    X509ClientCertificateAuthentication.CustomCertificateValidator, IssuedTokenAuthentication.CustomCertificateValidator

    RevocationMode

    X509ClientCertificateAuthentication.RevocationMode, IssuedTokenAuthentication.RevocationMode

    ServiceCertificate

    ServiceCredentials.ServiceCertificate

    ServiceTokenResolver

    None

    For more information, see Configuration.

  6. In WCF, the audience restriction of a SAML token was enforced only for bearer tokens. In WIF, audiences are checked regardless of the key type. This is mitigate certain classes of token forwarding attacks.

Windows Identity Foundation Features for WCF Service Developers

  • WIF adds several custom bindings. These are meant to be used by WCF clients to communicate with Active Directory® Federation Services (AD FS) 2.0 security token services. They can also be used as bindings on the endpoints of custom STSes. These bindings disable sessions and negotiation and do not correspond to any standard WCF bindings, as they can be configured to support endorsing RSA tokens to allow for asymmetric key scenarios. For more information, see Built-in Bindings Overview.

  • IClaimsPrinicpal allows access to the authenticating token. This token is known as a bootstrap token, and is a property on each IClaimsPrinicpal. This feature is disabled by default and can be enabled by toggling SaveBootstrapTokens.

    In ASP.NET or WCF, you can access the bootstrap tokens as in the following example.

    // Get the Bootstrap Token
SecurityToken bootstrapToken = null;

IClaimsPrincipal claimsPrincipal = Thread.CurrentPrincipal as IClaimsPrincipal;
if ( claimsPrincipal != null )
{
    IClaimsIdentity claimsIdentity = (IClaimsIdentity)claimsPrincipal.Identity;
    bootstrapToken = claimsIdentity.BootstrapToken;
}