Using CardSpace With wsHttpBinding
This sample demonstrates how to configure a wsHttpBinding to use an CardSpace in a Web service.
.gif) Note: |
|---|
The setup procedure and build instructions for this sample are located at the end of this topic. |
The sample defines an ISecureCalculator contract to illustrate the use of personal identity claims represented by an CardSpace. The CalculatorService defines and implements a service contract named ISecureCalculator as shown in the following sample code:
[ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]
public interface ISecureCalculator
{
[OperationContract]
double Add(double n1, double n2);
[OperationContract]
double Subtract(double n1, double n2);
[OperationContract]
double Multiply(double n1, double n2);
[OperationContract]
double Divide(double n1, double n2);
[OperationContract]
string GetIdentity();
}
The service is configured to require a SAML token provided by CardSpace.
The service implementation of the GetIdentity operation extracts the Private-Personal-Identifier (PPID) claim and returns it in the response. PrivatePersonalIdentifier is a unique constant with a built-in privacy feature generated by the issuer of the token. The service can use this identifier for account lookup and authentication, along with other information such as issuer's signature, and other claims. The PPID varies from one service to another, even if the same card is selected.
const string ppidClaimType =
"https://schemas.xmlsoap.org/ws/2005/05/identity/claims/ privatepersonalidentifier";
public string GetIdentity()
{
string identity=String.Empty;
AuthorizationContext ctx = OperationContext.Current.ServiceSecurityContext.AuthorizationContext;
foreach (ClaimSet claimSet in ctx.ClaimSets)
{
foreach (Claim claim in claimSet.FindClaims(ppidClaimType, null))
{
identity += claim.Resource as string;
}
}
return identity;
}
The service exposes a single endpoint, defined in the configuration file (Web.config), which requires an CardSpace from requestors, as shown in the following sample configuration:
<services>
<service
name="Microsoft.ServiceModel.Samples.CalculatorService"
behaviorConfiguration="ServiceCredentials">
<!-- This endpoint is exposed at the base address provided by host: https://localhost/servicemodelsamples/service.svc -->
<endpoint address=""
binding="wsHttpBinding"
bindingConfiguration="requireInfoCard"
contract="Microsoft.ServiceModel.Samples.ISecureCalculator" >
<identity>
<certificateReference
findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="LocalMachine"
storeName="My" />
</identity>
</endpoint>
<!-- The mex endpoint is exposed at https://localhost/servicemodelsamples/service.svc/mex. -->
<endpoint address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange" />
</service>
</services>
<bindings>
<wsHttpBinding>
<binding name="requireInfoCard">
<security mode="Message">
<message clientCredentialType="IssuedToken" />
</security>
</binding>
</wsHttpBinding>
</bindings>
The service also configures a behavior to specify the service certificate, which is used by the client to authenticate the service and secure messages sent to the service.
<behaviors>
<serviceBehaviors>
<behavior name="ServiceCredentials">
<serviceMetadata httpGetEnabled="True"/>
<serviceCredentials>
<serviceCertificate
findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="LocalMachine"
storeName="My" />
<issuedTokenAuthentication allowUntrustedRsaIssuers="true" />
</serviceCredentials>
<serviceDebug includeExceptionDetailInFaults="False" />
</behavior>
</serviceBehaviors>
</behaviors>
The client is also configured to require a SAML token provided by CardSpace, which causes the CardSpace user interface to be launched when making the first request to the service. The user can select an appropriate information card to present to the service. After selecting an information card, the request is secured using a SAML token that represents the identity. The GetIdentity operation on the ISecureCalculator contract extracts the PrivatePersonalIdentifer claim that was provided in the SAML token and returns it to the caller.
The client communicates with the service using a typed WCF client class that is generated by the Service Metadata Utility Tool (Svcutil.exe). The typed Windows Communication Foundation (WCF) client class is contained in the file GeneratedProxy.cs.
The configuration for the client can also be generated using the Service Metadata Utility Tool (Svcutil.exe). The Service Metadata Utility Tool (Svcutil.exe) creates the client endpoint configuration based on metadata published by the service. In this sample, the client configuration is manually created, by starting with the service configuration.
The client is required to set the clientCredentialType to IssuedToken and configure the certificateReference to allow CardSpace to authenticate the service, as shown in the following sample configuration:
<client>
<endpoint
address="https://localhost/ServiceModelSamples/service.svc/"
bindingConfiguration="requireInfoCard"
binding="wsHttpBinding"
contract="Microsoft.ServiceModel.Samples.ISecureCalculator"
behaviorConfiguration="ClientCredentials">
<identity>
<certificateReference
findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="CurrentUser"
storeName="TrustedPeople" />
</identity>
</endpoint>
</client>
<bindings>
<wsHttpBinding>
<binding name="requireInfoCard">
<security mode="Message">
<message clientCredentialType="IssuedToken" />
</security>
</binding>
</wsHttpBinding>
</bindings>
In addition to providing the service certificate in the endpoint, the client must specify the certificates of the services it trusts. This is accomplished by defining a behavior to reference the certificates in the certificate store that the client trusts.
<behaviors>
<endpointBehaviors>
<behavior name="ClientCredentials"
includeExceptionDetailInFaults="true">
<clientCredentials>
<serviceCertificate>
<defaultCertificate
findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="CurrentUser"
storeName="TrustedPeople" />
<!--
Setting the certificateValidationMode to PeerOrChainTrust means that if the certificate
is in the user's Trusted People store, then it will be trusted without performing a
validation of the certificate's issuer chain. This setting is used here for convenience so that the
sample can be run without having to have certificates issued by a certificate authority (CA).
This setting is less secure than the default, ChainTrust. The security implications of this
setting should be carefully considered before using PeerOrChainTrust in production code.
-->
<authentication
revocationMode="NoCheck"
certificateValidationMode="PeerOrChainTrust" />
</serviceCertificate>
</clientCredentials>
</behavior>
</endpointBehaviors>
</behaviors>
When you run that client and press ENTER, the client calls the GetIdentity operation and the CardSpace user interface launches:
Select an already existing card from CardSpace or create a new card.
Submit the card by clicking Send.
The claim or claims in your CardSpace are sent to the service as a SAML token serialization of your CardSpace. The service GetIdentity operation responds with the claim that was extracted from the SAML token. The client then calls the calculator operations of the service and the responses are displayed in the console window.
Identity - (Private Personal ID) = LGGjXshcVQE1kFMnxccopDBGvYu6gVs2Aexx+4bMlbk=
Add(100,15.99) = 115.99
Subtract(145,76.54) = 68.46
Multiply(9,81.25) = 731.25
Divide(22,7) = 3.14285714285714
Press <ENTER> to terminate client.
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 run the sample in a single- or cross-machine configuration, Use the following instructions. In particular, run Setup.bat from the language specific directory under the sample installation directory.
Note:The Setup.bat batch file is designed to be run from a Windows SDK Command Prompt. It requires that the MSSDK environment variable point to the directory where the SDK is installed. This environment variable is automatically set within a Windows SDK Command Prompt. For Windows Vista, ensure that the IIS 6.0 compatibility support is installed with IIS 7.0.
To build the C# or Visual Basic edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.
When you are finished with the sample, from the language specific directory under the sample installation directory, run Cleanup.bat.
To run the sample on the same machine
Import the Simple\SampleResources\Fabrikam-Contoso.pfx certificate into the LocalMachine/My (Personal) certificate store. The password for this certificate is xyz.
Note:Do not import the Fabrikam-Contoso-Public.cer file instead of the Fabrikam-Contoso.pfx file.
Run Setup.bat from the language specific directory under the Simple directory. This installs the Fabrikam-Contoso-Public.cer certificate into the CurrentUser/TrustedPeople certificate store, for use by the client. It also gives the IIS-hosted Web service permission to read the private key of the Fabrikam certificate installed in the previous step.
Note:On Windows Vista, manually import the certificate, and then run Setup.bat. Failure to do so may result in a “keyset does not exist” error.
Note:Be sure to remove the certificates by running Cleanup.bat when finished with the CardSpace samples. Other CardSpace samples use the same certificates. The Setup.bat batch file is designed to be run from a Windows SDK Command Prompt. It requires that the MSSDK environment variable point to the directory where the SDK is installed. This environment variable is automatically set within a Windows SDK Command Prompt.
Build the sample Visual Studio solution file CardSpace.sln located in the language-specific folder in the Simple folder.
To verify that the service is running, open in the following address in a Web browser: https://localhost/servicemodelsamples/service.svc, which shows a summary of the service.
Launch client.exe from Simple\<CS,VB>\client\bin.
If the client and service are not able to communicate, see Troubleshooting Tips.
To run the sample across machines
On the server hosting the Web service:
If the sample source directory does not already exist on the server, copy the TechnologySamples\Basic\Binding\WS\CardSpace\Simple directory to the server.
Import the Simple\SampleResources\Fabrikam-Contoso.pfx certificate into the LocalMachine/My (Personal) certificate store. The password for this certificate is xyz.
Note:Do not import the Fabrikam-Contoso-Public.cer file instead of the Fabrikam-Contoso.pfx file.
From the language specific directory under the Simple directory, run Setup.bat.
Note:Setup.bat installs the certificate required by the client into CurrentUser/TrustedPeople and copies the logo images to the ServiceModelSamples virtual directory. To avoid this, install the service's certificate, instead of running Setup.bat.
Build the Simple\<CS,VB>\service\service.csproj project.
To verify that the service is running, open in the following address in a Web browser: https://localhost/servicemodelsamples/service.svc, which shows a summary of the service.
Note:Once you have finished running the sample on the server, run Cleanup.bat from the language specific directory under the Simple folder.
On the computer hosting the client:
If the sample source directory does not already exist on the computer, copy the TechnologySamples\Basic\Binding\WS\CardSpace\Simple directory to the computer.
From the language specific directory under the Simple directory, run Setup.bat. You do not need to install the service certificate contained in Fabrikam-Contoso.pfx.
Build the Simple\<CS,VB>\client\client.csproj project.
In the file client\bin\client.exe.config, change the address in
<endpoint address="https://localhost/ServiceModelSamples/service.svc" .../>to match the new address of the Web service.
Run client\bin\client.exe.
Note:Once you have finished running the sample, run Cleanup.bat.
If the client and service are not able to communicate, see Troubleshooting Tips.
To clean up after the sample
- From the language specific directory under the sample installation directory, run Cleanup.bat.
.gif)
Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.