Message Security Certificate

Article
09/12/2008

Cet exemple montre comment implémenter une application qui utilise WS-Security avec l'authentification de certificat X.509 v3 pour le client et requiert l'authentification de serveur à l'aide du certificat X.509 v3 du serveur. Il utilise des paramètres par défaut de sorte que tous les messages d'application entre le client et le serveur soient signés et chiffrés. Cet exemple est basé sur WSHttpBinding et se compose d'un programme de console client et d'une bibliothèque de service hébergée par les services IIS (Internet Information Services). Le service implémente un contrat qui définit un modèle de communication demande-réponse.

Remarque :
La procédure d'installation ainsi que les instructions de génération relatives à cet exemple figurent à la fin de cette rubrique.

L'exemple montre comment contrôler l'authentification à l'aide de la configuration et comment obtenir l'identité de l'appelant à partir du contexte de sécurité, tel qu'indiqué dans l'exemple de code suivant.

public class CalculatorService : ICalculator
{
    public string GetCallerIdentity()
    {
        // The client certificate is not mapped to a Windows identity by default.
        // ServiceSecurityContext.PrimaryIdentity is populated based on the information
        // in the certificate that the client used to authenticate itself to the service.
        return ServiceSecurityContext.Current.PrimaryIdentity.Name;
    }
    ...
}

Le service expose un point de terminaison permettant de communiquer avec le service et un point de terminaison permettant d'exposer le document WSDL du service à l'aide du protocole WS-MetadataExchange, défini à l'aide du fichier de configuration (Web.config). Le point de terminaison se compose d'une adresse, d'une liaison et d'un contrat. La liaison est configurée à l'aide d'un élément wsHttpBinding standard, qui utilise par défaut le mode de sécurité du message. Cet exemple affecte Certificat à l'attribut clientCredentialType pour requérir l'authentification du client.

<system.serviceModel>
  <services>
    <service name="Microsoft.ServiceModel.Samples.CalculatorService"
             behaviorConfiguration="CalculatorServiceBehavior">
      <!-- Use the base address provided by host. -->
      <endpoint address=""
        binding="wsHttpBinding"
        bindingConfiguration="Binding1" 
        contract="Microsoft.ServiceModel.Samples.ICalculator" />
      <!-- The mex endpoint is exposed at https://localhost/servicemodelsamples/service.svc/mex. -->
      <endpoint address="mex"
                binding="mexHttpBinding"
                contract="IMetadataExchange" />
    </service>
  </services>

  <bindings>
    <wsHttpBinding>
      <!-- 
      This configuration defines the security mode as Message and 
      the clientCredentialType as Certificate.
      -->
      <binding name="Binding1">
        <security mode ="Message">
          <message clientCredentialType="Certificate" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>
</system.serviceModel>

Le comportement spécifie les informations d'identification du service utilisées lorsque le client authentifie le service. Le nom du sujet du certificat de serveur est spécifié dans l'attribut findValue de l'élément serviceCredentials.

<!--For debugging purposes, set the includeExceptionDetailInFaults attribute to true.-->
<behaviors>
  <serviceBehaviors>
    <behavior name="CalculatorServiceBehavior">
      <serviceMetadata httpGetEnabled="True"/>
      <serviceDebug includeExceptionDetailInFaults="False" />
      <!-- 
    The serviceCredentials behavior allows you to define a service certificate.
    A service certificate is used by the service to authenticate itself to its clients and to provide message protection.
    This configuration references the "localhost" certificate installed during the set up instructions.
    -->
      <serviceCredentials>
        <serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName" />
        <clientCertificate>
          <!-- 
        Setting the certificateValidationMode to PeerOrChainTrust means that if the certificate 
        is in the user's Trusted People store, then it is 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 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 certificateValidationMode="PeerOrChainTrust" />
        </clientCertificate>
      </serviceCredentials>
    </behavior>
  </serviceBehaviors>
</behaviors>

La configuration de point de terminaison de client se compose d'une adresse absolue pour le point de terminaison de service, de la liaison et du contrat. La liaison cliente est configurée avec les modes de sécurité et d'authentification appropriés. Lors de l'exécution sur plusieurs ordinateurs, assurez-vous que l'adresse de point de terminaison de service est modifiée en conséquence.

<system.serviceModel>
  <client>
    <!-- Use a behavior to configure the client certificate to present to the service. -->
    <endpoint address="https://localhost/servicemodelsamples/service.svc" 
              binding="wsHttpBinding" 
              bindingConfiguration="Binding1" 
              behaviorConfiguration="ClientCertificateBehavior"
              contract="Microsoft.ServiceModel.Samples.ICalculator" />
  </client>

  <bindings>
    <wsHttpBinding>
      <!-- 
        This configuration defines the security mode as Message and 
        the clientCredentialType as Certificate.
        -->
      <binding name="Binding1">
        <security mode ="Message">
          <message clientCredentialType="Certificate" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>

  ...
</system.serviceModel>

L'implémentation cliente peut définir le certificat à utiliser, soit via le fichier de configuration, soit via le code. L'exemple suivant montre comment définir le certificat à utiliser dans le fichier de configuration.

<system.serviceModel>
  ...
  <behaviors>
    <endpointBehaviors>
      <behavior name="ClientCertificateBehavior">
        <!-- 
      The clientCredentials behavior allows you to define a certificate to present to a service.
      A certificate is used by a client to authenticate itself to the service and provide message integrity.
      This configuration references the "client.com" certificate installed during the setup instructions.
      -->
        <clientCredentials>
          <clientCertificate findValue="client.com" storeLocation="CurrentUser" storeName="My" x509FindType="FindBySubjectName" />
          <serviceCertificate>
            <!-- 
          Setting the certificateValidationMode to PeerOrChainTrust means that if the certificate 
          is in the user's Trusted People store, then it is 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 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 certificateValidationMode="PeerOrChainTrust" />
          </serviceCertificate>
        </clientCredentials>
      </behavior>
    </endpointBehaviors>
  </behaviors>
</system.serviceModel>

L'exemple suivant montre comment appeler le service dans votre programme.

// Create a client.
CalculatorClient client = new CalculatorClient();

// Call the GetCallerIdentity service operation.
Console.WriteLine(client.GetCallerIdentity());
...
//Closing the client gracefully closes the connection and cleans up resources.
client.Close();

Lorsque vous exécutez l'exemple, les demandes et réponses d'opération s'affichent dans la fenêtre de console cliente. Appuyez sur ENTER dans la fenêtre du client pour l'arrêter.

CN=client.com
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.

Le fichier de commandes Setup.bat inclus avec les exemples Message Security vous permet de configurer le client et le serveur avec les certificats appropriés pour exécuter une application hébergée qui requiert la sécurité basée sur le certificat. Ce fichier peut être exécuté en trois modes. Pour l'exécuter en mode ordinateur unique, tapez setup.bat dans la ligne de commande, pour l'exécuter en mode service, tapez setup.bat service, et pour l'exécuter en mode client, tapez setup.bat client. Lorsque vous exécutez l'exemple sur plusieurs ordinateurs, utilisez le mode client et serveur. Consultez la procédure d'installation figurant en fin de rubrique. Les éléments suivants fournissent une brève vue d'ensemble des différentes sections des fichiers de commandes afin qu'ils puissent être modifiés pour s'exécuter dans la configuration appropriée :

Création du certificat client
La ligne suivante du fichier de commandes crée le certificat client. Le nom client spécifié est utilisé dans le nom du sujet du certificat créé. Le certificat est stocké dans le magasin My situé au niveau de l'emplacement de magasin CurrentUser.
```
echo ************
echo making client cert
echo ************
makecert.exe -sr CurrentUser -ss MY -a sha1 -n CN=%CLIENT_NAME% -sky exchange -pe
```
Installation du certificat client dans le magasin de certificats approuvés du serveur.
La ligne suivante du fichier de commandes copie le certificat client dans le magasin TrustedPeople du serveur afin que le serveur puisse prendre les décisions d'approbation ou de non-approbation appropriées. Pour qu'un certificat installé dans le magasin TrustedPeople soit approuvé par un service Windows Communication Foundation (WCF), le mode de la validation du certificat client doit avoir la valeur PeerOrChainTrust ou PeerTrust. Pour connaître la procédure à suivre à l'aide d'un fichier de configuration, consultez l'exemple de configuration de service précédent.
```
echo ************
echo copying client cert to server's LocalMachine store
echo ************
certmgr.exe -add -r CurrentUser -s My -c -n %CLIENT_NAME% -r LocalMachine -s TrustedPeople 
```
Création du certificat de serveur
Les lignes suivantes du fichier de commandes Setup.bat créent le certificat de serveur à utiliser.
```
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
```
La variable %SERVER_NAME% spécifie le nom du serveur. Le certificat est stocké dans le magasin LocalMachine. Si le fichier de commandes Setup.bat est exécuté à l'aide d'un argument de service (tel que setup.bat), la variable %SERVER_NAME% contient le nom de domaine complet de l'ordinateur. Dans le cas contraire, elle contient la valeur par défaut to localhost..
Installation du certificat de serveur dans le magasin de certificats approuvés du client.
La ligne suivante copie le certificat de serveur dans le magasin de personnes de confiance du client. Cette étape est requise car les certificats générés par Makecert.exe ne sont pas implicitement approuvés par le système client. Si vous disposez déjà d'un certificat associé à un certificat racine approuvé du client, par exemple d'un certificat émis par Microsoft, il n'est pas nécessaire d'ajouter le certificat du serveur au magasin de certificats du client.
```
certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople
```

Octroi d'autorisations sur la clé privée du certificat.
Les lignes suivantes du fichier Setup.bat rendent le certificat de serveur stocké dans le magasin LocalMachine accessible au compte du processus de traitement ASP.NET.

echo ************
echo setting privileges on server certificates
echo ************
for /F "delims=" %%i in ('"%ProgramFiles%\ServiceModelSampleTools\FindPrivateKey.exe" My LocalMachine -n CN^=%SERVER_NAME% -a') do set PRIVATE_KEY_FILE=%%i
set WP_ACCOUNT=NT AUTHORITY\NETWORK SERVICE
(ver | findstr /C:"5.1") && set WP_ACCOUNT=%COMPUTERNAME%\ASPNET
echo Y|cacls.exe "%PRIVATE_KEY_FILE%" /E /G "%WP_ACCOUNT%":R
iisreset

Remarque :
Si vous utilisez une édition anglaise non américaine de Microsoft Windows, vous devez modifier le fichier Setup.bat et remplacer le nom de compte « NT AUTHORITY\NETWORK SERVICE » par votre équivalent régional.

Remarque :
Les outils utilisés dans ce fichier de commandes se trouvent dans C:\Program Files\Microsoft Visual Studio 8\Common7\tools ou C:\Program Files\Microsoft SDKs\Windows\v6.0\bin. L'un de ces répertoires doit se trouver dans votre chemin d'accès système. Si Visual Studio est installé, la manière la plus simple de placer ce répertoire dans votre chemin d'accès est d'ouvrir l'invite de commandes Visual Studio. Cliquez sur le bouton de démarrage, Sélectionnez All Programs, Visual Studio 2005, Tools. Les chemins d'accès appropriés sont déjà configurés dans cette invite de commandes. Sinon, vous devez ajouter manuellement le répertoire approprié à votre chemin d'accès.

Les outils utilisés dans ce fichier de commandes se trouvent dans C:\Program Files\Microsoft Visual Studio 8\Common7\tools ou C:\Program Files\Microsoft SDKs\Windows\v6.0\bin. L'un de ces répertoires doit se trouver dans votre chemin d'accès système. Si Visual Studio est installé, la manière la plus simple de placer ce répertoire dans votre chemin d'accès est d'ouvrir l'invite de commandes Visual Studio. Cliquez sur le bouton de démarrage, Sélectionnez All Programs, Visual Studio 2005, Tools. Les chemins d'accès appropriés sont déjà configurés dans cette invite de commandes. Sinon, vous devez ajouter manuellement le répertoire approprié à votre chemin d'accès.

Pour configurer, générer et exécuter l'exemple

Assurez-vous d'avoir effectué la procédure indiquée dans la section Procédure d'installation unique pour les exemples Windows Communication Foundation.
Pour générer l'édition C# ou Visual Basic .NET de la solution, suivez les instructions indiquées dans Génération des exemples Windows Communication Foundation.

Pour exécuter l'exemple sur le même ordinateur

Assurez-vous que le chemin d'accès inclut le dossier dans lequel Makecert.exe et FindPrivateKey.exe se trouvent.

Exécutez Setup.bat à partir du dossier d'installation de l'exemple. Tous les certificats requis pour l'exécution de l'exemple sont ainsi installés.

Remarque :
Le fichier de commandes Setup.bat est conçu pour s'exécuter à partir d'une invite de commandes du Kit de développement Windows SDK. La variable d'environnement du Kit de développement MS SDK doit pointer sur le répertoire d'installation du Kit de développement SDK. Cette variable est définie automatiquement dans une invite de commandes du Kit de développement Windows SDK.

Vérifiez l'accès au service à l'aide d'un navigateur en tapant l'adresse https://localhost/servicemodelsamples/service.svc.
Lancez Client.exe à partir de \client\bin. L'activité du client s'affiche sur son application de console.
Si le client et le service ne parviennent pas à communiquer, consultez Conseils de dépannage.

Pour exécuter l'exemple sur plusieurs ordinateurs

Créez un répertoire sur l'ordinateur de service. Créez une application virtuelle appelée servicemodelsamples pour ce répertoire à l'aide de l'outil de gestion IIS (Internet Information Services).
Copiez les fichiers programme du service de \inetpub\wwwroot\servicemodelsamples dans le répertoire virtuel sur l'ordinateur de service. Assurez-vous de copier les fichiers dans le sous-répertoire \bin. Copiez également les fichiers Setup.bat, Cleanup.bat et ImportClientCert.bat sur l'ordinateur de service.
Créez un répertoire sur l'ordinateur client pour les fichiers binaires du client.
Copiez les fichiers programme du client dans le répertoire client sur l'ordinateur client. Copiez également les fichiers Setup.bat, Cleanup.bat et ImportServiceCert.bat sur le client.
Sur le serveur, exécutez setup.bat service. L'exécution de setup.bat avec l'argument service crée un certificat de service portant le nom de domaine complet de l'ordinateur et exporte le certificat de service vers un fichier nommé Service.cer.
Modifiez Web.config afin de prendre en compte le nouveau nom de certificat (dans l'attribut findValue de serviceCertificate element of serviceCredentials) qui est identique au nom de domaine complet de l'ordinateur.
Copiez le fichier Service.cer du répertoire de service dans le répertoire client sur l'ordinateur client.
Sur le client, exécutez setup.bat client. L'exécution de setup.bat avec l'argument client crée un certificat client appelé client.com et exporte le certificat client vers un fichier nommé Client.cer.
Dans le fichier Client.exe.config sur l'ordinateur client, modifiez la valeur d'adresse du point de terminaison afin qu'elle corresponde à la nouvelle adresse de votre service. Pour ce faire, remplacez localhost par le nom de domaine complet du serveur.
Copiez le fichier Client.cer du répertoire client vers le répertoire de service sur le serveur.
Sur le client, exécutez ImportServiceCert.bat. Cette opération importe le certificat de service du fichier Service.cer dans le magasin CurrentUser - TrustedPeople.
Sur le serveur, exécutez ImportClientCert.bat. Cette opération importe le certificat client du fichier Client.cer dans le magasin LocalMachine - TrustedPeople.
Sur l'ordinateur client, lancez Client.exe à partir d'une fenêtre d'invite de commandes. Si le client et le service ne parviennent pas à communiquer, consultez Conseils de dépannage.

Pour procéder au nettoyage après exécution de l'exemple

Exécutez Cleanup.bat dans le dossier d'exemples après avoir exécuté l'exemple.

Remarque :
Ce script ne supprime pas de certificat de service sur un client lors de l'exécution de cet exemple sur plusieurs ordinateurs. Si vous avez exécuté des exemples Windows Communication Foundation (WCF) qui utilisent des certificats sur plusieurs ordinateurs, assurez-vous d'effacer les certificats de service installés dans le magasin CurrentUser - TrustedPeople. Pour ce faire, utilisez la commande suivante : `certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name>`, par exemple : `certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com`.

Remarque :

Ce script ne supprime pas de certificat de service sur un client lors de l'exécution de cet exemple sur plusieurs ordinateurs. Si vous avez exécuté des exemples Windows Communication Foundation (WCF) qui utilisent des certificats sur plusieurs ordinateurs, assurez-vous d'effacer les certificats de service installés dans le magasin CurrentUser - TrustedPeople. Pour ce faire, utilisez la commande suivante : certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name>, par exemple : certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com.

Partager via

Message Security Certificate

Pour configurer, générer et exécuter l'exemple

Pour exécuter l'exemple sur le même ordinateur

Pour exécuter l'exemple sur plusieurs ordinateurs

Pour procéder au nettoyage après exécution de l'exemple

Ressources supplémentaires