SAML Token Provider

Article
09/15/2021

This sample demonstrates how to implement a custom client SAML token provider. A token provider in Windows Communication Foundation (WCF) is used for supplying credentials to the security infrastructure. The token provider in general examines the target and issues appropriate credentials so that the security infrastructure can secure the message. WCF ships with the default Credential Manager Token Provider. WCF also ships with a CardSpace token provider. Custom token providers are useful in the following cases:

If you have a credential store that these token providers cannot operate with.
If you want to provide your own custom mechanism for transforming the credentials from the point when the user provides the details to when the WCF client framework uses the credentials.
If you are building a custom token.

This sample shows how to build a custom token provider that allows a SAML token obtained from outside of the WCF client framework to be used.

To summarize, this sample demonstrates the following:

How a client can be configured with a custom token provider.
How a SAML token can be passed to the custom client credentials.
How the SAML token is provided to the WCF client framework.
How the server is authenticated by the client using the server's X.509 certificate.

The service exposes two endpoints for communicating with the service, defined using the configuration file App.config. Each endpoint consists of an address, a binding, and a contract. The binding is configured with a standard wsFederationHttpBinding, which uses Message security. One endpoint expects the client to authenticate with a SAML token that uses a symmetric proof key while the other expects the client to authenticate with a SAML token that uses an asymmetric proof key. The service also configures the service certificate using serviceCredentials behavior. The serviceCredentials behavior allows you to configure a service certificate. A service certificate is used by a client to authenticate the service and provide message protection. The following configuration references the "localhost" certificate installed during the sample setup as described in the setup instructions at the end of this topic. The serviceCredentials behavior also allows you to configure certificates that are trusted to sign SAML tokens. The following configuration references the 'Alice' certificate installed during the sample.

<system.serviceModel>
 <services>
  <service
          name="Microsoft.ServiceModel.Samples.CalculatorService"
          behaviorConfiguration="CalculatorServiceBehavior">
   <host>
    <baseAddresses>
     <!-- configure base address provided by host -->
     <add
  baseAddress="http://localhost:8000/servicemodelsamples/service/" />
    </baseAddresses>
   </host>
   <!-- use base address provided by host -->
   <!-- Endpoint that expect SAML tokens with Symmetric proof keys -->
   <endpoint address="calc/symm"
             binding="wsFederationHttpBinding"
             bindingConfiguration="Binding1"
             contract="Microsoft.ServiceModel.Samples.ICalculator" />
   <!-- Endpoint that expect SAML tokens with Asymmetric proof keys -->
   <endpoint address="calc/asymm"
             binding="wsFederationHttpBinding"
             bindingConfiguration="Binding2"
             contract="Microsoft.ServiceModel.Samples.ICalculator" />
  </service>
 </services>

 <bindings>
  <wsFederationHttpBinding>
   <!-- Binding that expect SAML tokens with Symmetric proof keys -->
   <binding name="Binding1">
    <security mode="Message">
     <message negotiateServiceCredential ="false"
              issuedKeyType="SymmetricKey"
              issuedTokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"  />
    </security>
   </binding>
   <!-- Binding that expect SAML tokens with Asymmetric proof keys -->
   <binding name="Binding2">
    <security mode="Message">
     <message negotiateServiceCredential ="false"
              issuedKeyType="AsymmetricKey"
              issuedTokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"  />
    </security>
   </binding>
  </wsFederationHttpBinding>
 </bindings>

 <behaviors>
  <serviceBehaviors>
   <behavior name="CalculatorServiceBehavior">
    <!--
    The serviceCredentials behavior allows one to define a service certificate.
    A service certificate is used by a client to authenticate the service and provide message protection.
    This configuration references the "localhost" certificate installed during the setup instructions.
    -->
    <serviceCredentials>
     <!-- Set allowUntrustedRsaIssuers to true to allow self-signed, asymmetric key based SAML tokens -->
     <issuedTokenAuthentication allowUntrustedRsaIssuers ="true" >
      <!-- Add Alice to the list of certs trusted to issue SAML tokens -->
      <knownCertificates>
       <add storeLocation="LocalMachine"
            storeName="TrustedPeople"
            x509FindType="FindBySubjectName"
            findValue="Alice"/>
      </knownCertificates>
     </issuedTokenAuthentication>
     <serviceCertificate storeLocation="LocalMachine"
                         storeName="My"
                         x509FindType="FindBySubjectName"
                         findValue="localhost"  />
    </serviceCredentials>
   </behavior>
  </serviceBehaviors>
 </behaviors>

</system.serviceModel>

The following steps show how to develop a custom SAML token provider and integrate it with WCF: security framework:

Write a custom SAML token provider.

The sample implements a custom SAML token provider that returns a security token based on a SAML assertion that is provided at construction time.

To perform this task, the custom token provider is derived from the SecurityTokenProvider class and overrides the GetTokenCore method. This method creates and returns a new SecurityToken.

protected override SecurityToken GetTokenCore(TimeSpan timeout)
{
 // Create a SamlSecurityToken from the provided assertion
 SamlSecurityToken samlToken = new SamlSecurityToken(assertion);

 // Create a SecurityTokenSerializer that will be used to
 // serialize the SamlSecurityToken
 WSSecurityTokenSerializer ser = new WSSecurityTokenSerializer();
 // Create a memory stream to write the serialized token into
 // Use an initial size of 64Kb
 MemoryStream s = new MemoryStream(UInt16.MaxValue);

 // Create an XmlWriter over the stream
 XmlWriter xw = XmlWriter.Create(s);

 // Write the SamlSecurityToken into the stream
 ser.WriteToken(xw, samlToken);

 // Seek back to the beginning of the stream
 s.Seek(0, SeekOrigin.Begin);

 // Load the serialized token into a DOM
 XmlDocument dom = new XmlDocument();
 dom.Load(s);

 // Create a KeyIdentifierClause for the SamlSecurityToken
 SamlAssertionKeyIdentifierClause samlKeyIdentifierClause = samlToken.CreateKeyIdentifierClause<SamlAssertionKeyIdentifierClause>();

// Return a GenericXmlToken from the XML for the
// SamlSecurityToken, the proof token, the valid from and valid
// until times from the assertion and the key identifier clause
// created above
return new GenericXmlSecurityToken(dom.DocumentElement, proofToken, assertion.Conditions.NotBefore, assertion.Conditions.NotOnOrAfter, samlKeyIdentifierClause, samlKeyIdentifierClause, null);
}

Write custom security token manager.

The SecurityTokenManager class is used to create SecurityTokenProvider for specific SecurityTokenRequirement that is passed to it in CreateSecurityTokenProvider method. A security token manager is also used to create token authenticators and token serializer, but those are not covered by this sample. In this sample the custom security token manager inherits from the ClientCredentialsSecurityTokenManager class and overrides the CreateSecurityTokenProvider method to return the custom SAML token provider when the passed token requirements indicate that the SAML token is requested. If the client credentials class (see step 3) has not specified an assertion, the security token manager creates an appropriate instance.

public class SamlSecurityTokenManager : ClientCredentialsSecurityTokenManager
{
 SamlClientCredentials samlClientCredentials;

 public SamlSecurityTokenManager ( SamlClientCredentials samlClientCredentials)
  : base(samlClientCredentials)
 {
  // Store the creating client credentials
  this.samlClientCredentials = samlClientCredentials;
 }

 public override SecurityTokenProvider CreateSecurityTokenProvider ( SecurityTokenRequirement tokenRequirement )
 {
  // If token requirement matches SAML token return the
  // custom SAML token provider
  if (tokenRequirement.TokenType == SecurityTokenTypes.Saml ||
      tokenRequirement.TokenType == "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1")
  {
   // Retrieve the SAML assertion and proof token from the
   // client credentials
   SamlAssertion assertion = this.samlClientCredentials.Assertion;
   SecurityToken prooftoken = this.samlClientCredentials.ProofToken;

   // If either the assertion of proof token is null...
   if (assertion == null || prooftoken == null)
   {
    // ...get the SecurityBindingElement and then the
    // specified algorithm suite
    SecurityBindingElement sbe = null;
    SecurityAlgorithmSuite sas = null;

    if ( tokenRequirement.TryGetProperty<SecurityBindingElement> ( "http://schemas.microsoft.com/ws/2006/05/servicemodel/securitytokenrequirement/SecurityBindingElement", out sbe))
    {
     sas = sbe.DefaultAlgorithmSuite;
    }

    // If the token requirement is for a SymmetricKey based token..
    if (tokenRequirement.KeyType == SecurityKeyType.SymmetricKey)
    {
     // Create a symmetric proof token
     prooftoken = SamlUtilities.CreateSymmetricProofToken ( tokenRequirement.KeySize );
     // and a corresponding assertion based on the claims specified in the client credentials
     assertion = SamlUtilities.CreateSymmetricKeyBasedAssertion ( this.samlClientCredentials.Claims, new X509SecurityToken ( samlClientCredentials.ClientCertificate.Certificate ), new X509SecurityToken ( samlClientCredentials.ServiceCertificate.DefaultCertificate ), (BinarySecretSecurityToken)prooftoken, sas);
    }
    // otherwise...
    else
    {
     // Create an asymmetric proof token
     prooftoken = SamlUtilities.CreateAsymmetricProofToken();
     // and a corresponding assertion based on the claims
     // specified in the client credentials
     assertion = SamlUtilities.CreateAsymmetricKeyBasedAssertion ( this.samlClientCredentials.Claims, prooftoken, sas );
    }
   }

   // Create a SamlSecurityTokenProvider based on the assertion and proof token
   return new SamlSecurityTokenProvider(assertion, prooftoken);
  }
  // otherwise use base implementation
  else
  {
   return base.CreateSecurityTokenProvider(tokenRequirement);
  }
}

Write a custom client credential.

Client credentials class is used to represent the credentials that are configured for the client proxy and creates a security token manager that is used to obtain token authenticators, token providers and token serializer.

public class SamlClientCredentials : ClientCredentials
{
 ClaimSet claims;
 SamlAssertion assertion;
 SecurityToken proofToken;

 public SamlClientCredentials() : base()
 {
  // Set SupportInteractive to false to suppress Cardspace UI
  base.SupportInteractive = false;
 }

 protected SamlClientCredentials(SamlClientCredentials other) : base ( other )
 {
  // Just do reference copy given sample nature
  this.assertion = other.assertion;
  this.claims = other.claims;
  this.proofToken = other.proofToken;
 }

 public SamlAssertion Assertion { get { return assertion; } set { assertion = value; } }

 public SecurityToken ProofToken { get { return proofToken; } set { proofToken = value; } }
 public ClaimSet Claims { get { return claims; } set { claims = value; } }

 protected override ClientCredentials CloneCore()
 {
  return new SamlClientCredentials(this);
 }

 public override SecurityTokenManager CreateSecurityTokenManager()
 {
  // return custom security token manager
  return new SamlSecurityTokenManager(this);
 }
}

Configure the client to use the custom client credential.

The sample deletes the default client credential class and supplies the new client credential class so the client can use the custom client credential.

// Create new credentials class
SamlClientCredentials samlCC = new SamlClientCredentials();

// Set the client certificate. This is the cert that will be used to sign the SAML token in the symmetric proof key case
samlCC.ClientCertificate.SetCertificate(StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "Alice");

// Set the service certificate. This is the cert that will be used to encrypt the proof key in the symmetric proof key case
samlCC.ServiceCertificate.SetDefaultCertificate(StoreLocation.CurrentUser, StoreName.TrustedPeople, X509FindType.FindBySubjectName, "localhost");

// Create some claims to put in the SAML assertion
IList<Claim> claims = new List<Claim>();
claims.Add(Claim.CreateNameClaim(samlCC.ClientCertificate.Certificate.Subject));
ClaimSet claimset = new DefaultClaimSet(claims);
samlCC.Claims = claimset;

// set new credentials
client.ChannelFactory.Endpoint.Behaviors.Remove(typeof(ClientCredentials));
client.ChannelFactory.Endpoint.Behaviors.Add(samlCC);

On the service, the claims associated with the caller are displayed. When you run the sample, the operation requests and responses are displayed in the client console window. Press ENTER in the client window to shut down the client.

Setup Batch File

The Setup.bat batch file included with this sample allows you to configure the server with the relevant certificate to run a self-hosted application that requires server certificate-based security. This batch file must be modified to work across computers or to work in a non-hosted case.

The following provides a brief overview of the different sections of the batch files so that they can be modified to run in the appropriate configuration.

Creating the server certificate:

The following lines from the Setup.bat batch file create the server certificate to be used. The %SERVER_NAME% variable specifies the server name. Change this variable to specify your own server name. The default value in this batch file is localhost.

The certificate is stored in My (Personal) store under the LocalMachine store location.
```
echo ************
echo Server cert setup starting
echo %SERVER_NAME%
echo ************
echo making server cert
echo ************
makecert.exe -sr LocalMachine -ss My -a sha1 -n CN=%SERVER_NAME% -sky exchange -pe
```
Installing the server certificate into the client's trusted certificate store:

The following lines in the Setup.bat batch file copy the server certificate into the client trusted people store. This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft-issued certificate—this step of populating the client certificate store with the server certificate is not required.
```
certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r LocalMachine -s TrustedPeople
```
Creating the issuer certificate.

The following lines from the Setup.bat batch file create the issuer certificate to be used. The %USER_NAME% variable specifies the issuer name. Change this variable to specify your own issuer name. The default value in this batch file is Alice.

The certificate is stored in My store under the CurrentUser store location.
```
echo ************
echo Server cert setup starting
echo %SERVER_NAME%
echo ************
echo making server cert
echo ************
makecert.exe -sr CurrentUser -ss My -a sha1 -n CN=%USER_NAME% -sky exchange -pe
```
Installing the issuer certificate into the server's trusted certificate store.

The following lines in the Setup.bat batch file copy the server certificate into the client trusted people store. This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft-issued certificate—this step of populating the server certificate store with the issuer certificate is not required.
```
certmgr.exe -add -r CurrentUser -s My -c -n %USER_NAME% -r LocalMachine -s TrustedPeople
```

To set up and build the sample

Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.
To build the solution, follow the instructions in Building the Windows Communication Foundation Samples.

Note

If you use Svcutil.exe to regenerate the configuration for this sample, be sure to modify the endpoint name in the client configuration to match the client code.

To run the sample on the same computer

Run Setup.bat from the sample installation folder inside a Visual Studio command prompt run with administrator privileges. This installs all the certificates required for running the sample.

Note

The Setup.bat batch file is designed to be run from a Visual Studio Command Prompt. The PATH environment variable set within the Visual Studio Command Prompt points to the directory that contains executables required by the Setup.bat script.
Launch Service.exe from service\bin.
Launch Client.exe from \client\bin. Client activity is displayed on the client console application.
If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

To run the sample across computers

Create a directory on the service computer for the service binaries.
Copy the service program files to the service directory on the service computer. Also copy the Setup.bat and Cleanup.bat files to the service computer.
You must have a server certificate with the subject name that contains the fully-qualified domain name of the computer. The Service.exe.config file must be updated to reflect this new certificate name. You can create server certificate by modifying the Setup.bat batch file. Note that the setup.bat file must be run in a Developer Command Prompt for Visual Studio window opened with administrator privileges. You must set the %SERVER_NAME% variable to the fully-qualified host name of the computer that is used to host the service.
Copy the server certificate into the CurrentUser-TrustedPeople store of the client. This step is not necessary when the server certificate is issued by a client trusted issuer.
In the Service.exe.config file on the service computer, change the value of the base address to specify a fully-qualified computer name instead of localhost.
On the service computer, run Service.exe from a command prompt.
Copy the client program files from the \client\bin\ folder, under the language-specific folder, to the client computer.
In the Client.exe.config file on the client computer, change the address value of the endpoint to match the new address of your service.
On the client computer, launch Client.exe from a command prompt window.
If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

To clean up after the sample

Run Cleanup.bat in the samples folder once you have finished running the sample.