CardSpace Federation
This sample demonstrates how to configure a custom binding 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 information card. 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 an CardSpace.
The service implementation of the GetIdentity operation extracts the all the claims that were originally requested by the service.
public string GetIdentity()
{
string identity = String.Empty;
AuthorizationContext ctx = OperationContext.Current.ServiceSecurityContext.AuthorizationContext;
foreach (ClaimSet claimSet in ctx.ClaimSets)
{
foreach (Claim claim in claimSet)
{
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="wsFederationHttpBinding"
bindingConfiguration="requireInfoCard"
contract="Microsoft.ServiceModel.Samples.ISecureCalculator" >
<identity>
<certificateReference findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="LocalMachine"
storeName="My" />
</identity>
</endpoint>
<!-- the mex endpoint is explosed at https://localhost/servicemodelsamples/service.svc/mex -->
<endpoint address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange" />
</service>
</services>
<bindings>
<wsFederationHttpBinding>
<binding name="requireInfoCard">
<security mode="Message">
<message issuedTokenType="urn:oasis:names:tc:SAML:1.0:assertion">
<claimTypeRequirements>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifer"/>
</claimTypeRequirements>
<issuer address="https://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self"/>
</message>
</security>
</binding>
</wsFederationHttpBinding>
</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 an 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 E-Mail-Address claim that was provided in the SAML token and returns it to the caller.
The client communicates with the service using a typed Windows Communication Foundation (WCF) client class that is generated by the Service Metadata Utility Tool (Svcutil.exe). The typed WCF client class is contained in the file GeneratedClient.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 configure the certificateReference to allow the CardSpace to authenticate the service, as shown in the following sample configuration:
<client>
<endpoint address="https://localhost/ServiceModelSamples/service.svc/"
bindingConfiguration="requireInfoCard"
binding="wsFederationHttpBinding"
contract="Microsoft.ServiceModel.Samples.ISecureCalculator"
behaviorConfiguration="ClientCredentials">
<identity>
<certificateReference
findValue="545c3b8e97d99fd75c75eb52c6908320088b4f50"
x509FindType="FindByThumbprint"
storeLocation="CurrentUser"
storeName="TrustedPeople" />
</identity>
</endpoint>
</client>
<bindings>
<wsFederationHttpBinding>
<binding name="requireInfoCard">
<security mode="Message">
<message issuedTokenType="urn:oasis:names:tc:SAML:1.0:assertion">
<claimTypeRequirements>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
<add claimType ="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier"/>
</claimTypeRequirements>
<issuer address="https://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self"/>
</message>
</security>
</binding>
</wsFederationHttpBinding>
</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" >
<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 starts.
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.
claims requested by the service = [System.Byte[]] [alice@woodward.com] [Alice] [Woodward] [IdjUW0O7xWVaga5AODCOuM070Ll9SfsPtYYfo8pKi7s=]
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, follow the instructions below. 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 <CS,VB>\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 sample 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.
Build the sample Visual Studio solution file CardSpace.sln located in the language-specific sample 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 <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 service:
If the sample source directory does not already exist on the server, copy the TechnologySamples\Basic\Binding\ws\CardSpace\UsingWsFederation directory to the server.
Import the <CS,VB>\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 sample 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. 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 <CS,VB>\Service\Service.csproj project.
To verify that the service is running, open 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 sample 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\UsingWsFederation directory to the computer.
From the language-specific directory under the sample directory, run Setup.bat. You do not need to install the service certificate contained in Fabrikam-Contoso.pfx.
Build the <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 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.