Service Identity Sample

Article
07/03/2007

This service identity sample demonstrates how to set the identity for a service. At design time, a client can retrieve the identity using the service's metadata and then at runtime the client can authenticate the service's identity. The concept of service identity is to allow a client to authenticate a service before calling any of its operations, thereby protecting the client from unauthenticated calls. On a secure connection the service also authenticates a client's credentials before allowing it access, but this is not the focus of this sample. See the samples in Client Samples that show server authentication.

Note:
The setup procedure and build instructions for this sample are located at the end of this topic.

This sample illustrates the following features:

How to set the different types of identity on different endpoints for a service. Each type of identity has different capabilities. The type of identity to use is dependent on the type of security credentials used on the endpoint's binding.
Identity can either be set declaratively in configuration or imperatively in code. Typically for both the client and the service you should use configuration to set the identity.

How to set a custom identity on the client. A custom identity is typically a customization of an existing type of identity that enables the client to examine other claim information provided in the service's credentials to make authorization decisions before calling the service.

Note:
This sample checks the identity of a specific certificate called identity.com and the RSA key contained within this certificate. When using the Certificate and RSA identity types in configuration on the client, inspect the WSDL for the service where these values are serialized out.

The following sample code shows how to configure the identity of a service endpoint with the Domain Name Server (DNS) of a certificate using a WSHttpBinding:

//Create a service endpoint and set its identity to the certificate's DNS               
WSHttpBinding wsAnonbinding = new WSHttpBinding (SecurityMode.Message);
// Client are Anonymous to the service
wsAnonbinding.Security.Message.ClientCredentialType = MessageCredentialType.None;
WServiceEndpoint ep = serviceHost.AddServiceEndpoint(typeof(ICalculator),wsAnonbinding, String.Empty);
EndpointAddress epa = new EndpointAddress(dnsrelativeAddress,EndpointIdentity.CreateDnsIdentity("identity.com"));
ep.Address = epa;

The identity can also be specified in configuration in the App.config file. The following example shows how to set the UPN (User Principal Name) identity for a service endpoint:

<endpoint address="upnidentity"
        behaviorConfiguration=""
        binding="wsHttpBinding"
        bindingConfiguration="WSHttpBinding_Windows"
        name="WSHttpBinding_ICalculator_Windows"
        contract="Microsoft.ServiceModel.Samples.ICalculator">
  <!-- Set the UPN identity for this endpoint -->
  <identity>
      <userPrincipalName value="host\myservice.com" />
  </identity >
</endpoint>

A custom identity can be set on the client by deriving from the EndpointIdentity and the IdentityVerifier classes. Conceptually the IdentityVerifier class can be considered to be the client equivalent of the service's AuthorizationManager class. The following code example shows an implementation of OrgEndpointIdentity, which stores an organization name to match in the subject name of the server's certificate. The authorization check for the organization name occurs in the CheckAccess method on the CustomIdentityVerifier class:

// This custom EndpointIdentity stores an organization name 
public class OrgEndpointIdentity : EndpointIdentity
{
    private string orgClaim;
    public OrgEndpointIdentity(string orgName)
    {
        orgClaim = orgName;
    }
    public string OrganizationClaim
    {
        get { return orgClaim; }
        set { orgClaim = value; }
    }
}

//This custom IdentityVerifier uses the supplied OrgEndpointIdentity to
//check that that X509 certificate's distinguished name claim contains
//the organization name e.g. the string value "O=Contoso" 
class CustomIdentityVerifier : IdentityVerifier
{
    public override bool CheckAccess(EndpointIdentity identity, AuthorizationContext authContext)
    {
        bool returnvalue = false;
        foreach (ClaimSet claimset in authContext.ClaimSets)
        {
            foreach (Claim claim in claimset)
            {
                if (claim.ClaimType == "https://schemas.microsoft.com/ws/2005/05/identity/claims/x500distinguishedname")
                {
                    X500DistinguishedName name = (X500DistinguishedName)claim.Resource;
                    if (name.Name.Contains(((OrgEndpointIdentity)identity).OrganizationClaim))
                    {
                        Console.WriteLine("Claim Type: {0}",claim.ClaimType);
                        Console.WriteLine("Right: {0}", claim.Right);
                        Console.WriteLine("Resource: {0}",claim.Resource);
                        Console.WriteLine();
                        returnvalue = true;
                    }
                }
            }
        }
        return returnvalue;
    }
}

This sample uses a certificate called identity.com which is in the language specific Identity solution folder.

To set up, build, and run the sample

Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.
To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.
To run the sample in a single- or cross-machine configuration, follow the instructions in Running the Windows Communication Foundation Samples.

To run the sample on the same machine

Ensure that the path includes the folder where Makecert.exe and FindPrivateKey.exe are located.
On Windows XP or Windows Vista, import the Identity.pfx certificate file in the Identity solution folder into the LocalMachine/My (Personal) certificate store using the MMC snap-in tool. This file is password protected. During the import you are asked for a password. Type xyz into the password box. For more information, see the How to: View Certificates with the MMC Snap-in topic. Once this is done then run Setup.bat, which copies this certificate to the CurrentUser/Trusted People store for use on the client.
On Windows Server 2003, run Setup.bat from the sample install folder. This installs all the certificates required for running the sample.

Note Ensure that you remove the certificates by running Cleanup.bat when you have finished with the sample. Other security samples use the same certificates.
Launch Service.exe from the \service\bin directory. Ensure that the service indicates that it is ready and displays a prompt to Press <Enter> to terminate the service.
Launch Client.exe from \client\bin directory or by pressing F5 in Visual Studio to build and run. Client activity is displayed on the client console application.
If the client and service are not able to communicate, see Troubleshooting Tips.

To run the sample across machines

Before building the client part of the sample, be sure to change the value for the service's endpoint address in the Client.cs file in the CallServiceCustomClientIdentity method. Then build the sample.
Create a directory on the service machine.
Copy the service program files from service\bin to the directory on the service machine. Also copy the Setup.bat and Cleanup.bat files to the service machine.
Create a directory on the client machine for the client binaries.
Copy the client program files to the client directory on the client machine. Also copy the Setup.bat, Cleanup.bat, and ImportServiceCert.bat files to the client.
On the service, run setup.bat service. Running setup.bat with the service argument creates a service certificate with the fully-qualified domain name of the machine and exports the service certificate to a file named Service.cer.
Copy the Service.cer file from the service directory to the client directory on the client machine.
In the Client.exe.config file on the client machine, change the address value of the endpoint to match the new address of your service. There are multiple instances that must be changed.
On the client, run ImportServiceCert.bat. This imports the service certificate from the Service.cer file into the CurrentUser - TrustedPeople store.
On the service machine, launch the Service.exe from the command prompt.
On the client machine, launch Client.exe from a command prompt. If the client and service are not able to communicate, see Troubleshooting Tips.

To clean up after the sample

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

Note:
This script does not remove service certificates on a client when running this sample across machines. If you have run Windows Communication Foundation (WCF) samples that use certificates across machines, be sure to clear the service certificates that have been installed in the CurrentUser - TrustedPeople store. To do this, use the following command: `certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name>` For example: `certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com`.

Note:

This script does not remove service certificates on a client when running this sample across machines. If you have run Windows Communication Foundation (WCF) samples that use certificates across machines, be sure to clear the service certificates that have been installed in the CurrentUser - TrustedPeople store. To do this, use the following command: certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name> For example: certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com.

Footer image

Share via

Service Identity Sample

To set up, build, and run the sample

To run the sample on the same machine

To run the sample across machines

To clean up after the sample

Additional resources