How to: Configure Credentials on a Federation Service

Article
08/07/2009

In Windows Communication Foundation (WCF), creating a federated service consists of the following main procedures:

Configuring a WSFederationHttpBinding or similar custom binding. For more information about creating an appropriate binding, see How to: Create a WSFederationHttpBinding.
Configuring the IssuedTokenServiceCredential that controls how issued tokens presented to the service are authenticated.

This topic provides details about the second step. For more information about how a federated service works, see Federation.

To set the properties of IssuedTokenServiceCredential in code

Use the IssuedTokenAuthentication property of the ServiceCredentials class to return a reference to an IssuedTokenServiceCredential instance. The property is accessed from the Credentials property of the ServiceHostBase class.
Set the AllowUntrustedRsaIssuers property to true if self-issued tokens such as CardSpace cards are to be authenticated. The default is false.

Populate the collection returned by the KnownCertificates property with instances of the X509Certificate2 class. Each instance represents an issuer from which the service will authenticate tokens.

Note:
Unlike the client-side collection returned by the ScopedCertificates property, the known certificates collection is not a keyed collection. The service accepts the tokens that the specified certificates issue regardless of the address of the client that sent the message containing the issued token (subject to the further constraints, which are described later in this topic).

Set the CertificateValidationMode property to one of the X509CertificateValidationMode enumeration values. This can be done only in code. The default is ChainTrust.
If the CertificateValidationMode property is set to Custom, then assign an instance of the custom X509CertificateValidator class to the CustomCertificateValidator property.
If the CertificateValidationMode is set to ChainTrust or PeerOrChainTrust, set the RevocationMode property to an appropriate value from the X509RevocationMode enumeration. Note that the revocation mode is not used in PeerTrust or Custom validation modes.
If needed, assign an instance of a custom SamlSerializer class to the SamlSerializer property. A custom Security Assertions Markup Language (SAML) serializer is needed, for example, for parsing custom SAML assertions.

To set the properties of IssuedTokenServiceCredential in configuration

Create an <issuedTokenAuthentication> element as a child of a <serviceCredentials> element.
Set the allowUntrustedRsaIssuers attribute of the <issuedTokenAuthentication> element to true if authenticating a self-issued token, such as an CardSpace card.
Create a <knownCertificates> element as a child of the <issuedTokenAuthentication> element.
Create zero or more <add> elements as children of the <knownCertificates> element, and specify how to locate the certificate using the storeLocation, storeName, x509FindType, and findValue attributes.
If necessary, set the samlSerializer attribute of the <issuedTokenAuthentication> element to the type name of the custom SamlSerializer class.

Example

The following example sets the properties of an IssuedTokenServiceCredential in code.

' This method configures the IssuedTokenAuthentication property of a ServiceHost.
Public Shared Sub ConfigureIssuedTokenServiceCredentials( _
    ByVal sh As ServiceHost, _
    ByVal allowCardspaceTokens As Boolean, _
    ByVal knownissuers As IList(Of X509Certificate2), _
    ByVal certMode As X509CertificateValidationMode, _
    ByVal revocationMode As X509RevocationMode, _
    ByVal ser As SamlSerializer _
    )
    ' Allow CardSpace tokens.
    sh.Credentials.IssuedTokenAuthentication.AllowUntrustedRsaIssuers = _
    allowCardspaceTokens

    ' Set up known issuer certificates.
    Dim cert As X509Certificate2
    For Each cert In knownissuers
        sh.Credentials.IssuedTokenAuthentication.KnownCertificates.Add(cert)
    Next cert
    ' Set issuer certificate validation and revocation checking modes.
    sh.Credentials.IssuedTokenAuthentication.CertificateValidationMode = _
        X509CertificateValidationMode.PeerOrChainTrust
    sh.Credentials.IssuedTokenAuthentication.RevocationMode = _
    X509RevocationMode.Online

    ' Set the SamlSerializer, if one is specified.
    If Not (ser Is Nothing) Then
        sh.Credentials.IssuedTokenAuthentication.SamlSerializer = ser
    End If
End Sub

// This method configures the IssuedTokenAuthentication property of a ServiceHost.
public static void ConfigureIssuedTokenServiceCredentials( 
    ServiceHost sh, bool allowCardspaceTokens, IList<X509Certificate2> knownissuers, 
    X509CertificateValidationMode certMode, X509RevocationMode revocationMode, SamlSerializer ser )
{
  // Allow CardSpace tokens.
  sh.Credentials.IssuedTokenAuthentication.AllowUntrustedRsaIssuers = allowCardspaceTokens;
  
  // Set up known issuer certificates.
  foreach(X509Certificate2 cert in knownissuers)
    sh.Credentials.IssuedTokenAuthentication.KnownCertificates.Add ( cert );

  // Set issuer certificate validation and revocation checking modes.
  sh.Credentials.IssuedTokenAuthentication.CertificateValidationMode = 
      X509CertificateValidationMode.PeerOrChainTrust;
  sh.Credentials.IssuedTokenAuthentication.RevocationMode = X509RevocationMode.Online;
  sh.Credentials.IssuedTokenAuthentication.TrustedStoreLocation = StoreLocation.LocalMachine;

  // Set the SamlSerializer, if one is specified.
  if ( ser != null )
    sh.Credentials.IssuedTokenAuthentication.SamlSerializer = ser;
}

In order for a federated service to authenticate a client, the following must be true about the issued token:

When the issued token’s digital signature uses an RSA security key identifier, the AllowUntrustedRsaIssuers property must be true.
When the issued token’s signature uses an X.509 issuer serial number, X.509 subject key identifier, or X.509 thumbprint security identifier, the issued token must be signed by a certificate in the collection returned by the KnownCertificates property of the IssuedTokenServiceCredential class.
When the issued token is signed using an X.509 certificate, the certificate must validate per the semantics specified by the value of the CertificateValidationMode property, regardless of whether the certificate was sent to the relying party as a X509RawDataKeyIdentifierClause or was obtained from the KnownCertificates property. For more information about X.509 certificate validation, see Working with Certificates.

For example, setting the CertificateValidationMode to PeerTrust would authenticate any issued token whose signing certificate is in the TrustedPeople certificate store. In that case, set the TrustedStoreLocation property to either CurrentUser or LocalMachine. You can select other modes, including Custom. When Custom is selected, you must assign an instance of the X509CertificateValidator class to the CustomCertificateValidator property. The custom validator can validate certificates using any criteria it likes. For more information, see How to: Create a Service that Employs a Custom Certificate Validator.

Share via

How to: Configure Credentials on a Federation Service

To set the properties of IssuedTokenServiceCredential in code

To set the properties of IssuedTokenServiceCredential in configuration

Example

See Also

Tasks

Concepts

Other Resources

Additional resources