Certificat de sécurité des messages

Article
01/29/2025

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

Remarque

La procédure d’installation et les instructions de génération de cet exemple se trouvent à 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é, comme illustré 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 pour communiquer avec le service et un point de terminaison pour 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 avec un élément standard <wsHttpBinding>, qui utilise par défaut la sécurité des messages. Cet exemple définit l’attribut clientCredentialType sur Certificate pour exiger l’authentification du client.

<system.serviceModel>
    <protocolMapping>
      <add scheme="http" binding="wsHttpBinding"/>
    </protocolMapping>
    <bindings>
      <wsHttpBinding>
        <!--
        This configuration defines the security mode as Message and
        the clientCredentialType as Certificate.
        -->
        <binding>
          <security mode ="Message">
            <message clientCredentialType="Certificate" />
          </security>
        </binding>
      </wsHttpBinding>
    </bindings>
    <!--For debugging purposes set the includeExceptionDetailInFaults attribute to true-->
    <behaviors>
      <serviceBehaviors>
        <behavior>
          <serviceMetadata httpGetEnabled="True"/>
          <serviceDebug includeExceptionDetailInFaults="False" />
          <!--
        The serviceCredentials behavior allows one 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 setup 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 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 certification 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>
  </system.serviceModel>

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

<!--For debugging purposes, set the includeExceptionDetailInFaults attribute to true.-->
<behaviors>
      <serviceBehaviors>
        <behavior>
          <serviceMetadata httpGetEnabled="True"/>
          <serviceDebug includeExceptionDetailInFaults="False" />
          <!--
        The serviceCredentials behavior allows one 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 setup 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 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 certification 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 du point de terminaison client se compose d’une adresse absolue pour le point de terminaison de service, la liaison et le contrat. La liaison cliente est configurée avec le mode de sécurité et le mode d’authentification appropriés. Lors de l’exécution dans un scénario inter-ordinateur, vérifiez que l’adresse du 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="http://localhost/servicemodelsamples/service.svc" binding="wsHttpBinding" bindingConfiguration="Binding1" behaviorConfiguration="ClientCertificateBehavior" contract="Microsoft.Samples.Certificate.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 du client peut définir le certificat à utiliser, par le biais du fichier de configuration ou du 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 one 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 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 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 de l’opération s’affichent dans la fenêtre de la console cliente. Appuyez sur Entrée dans la fenêtre du client pour arrêter le client.

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 batch Setup.bat inclus dans les exemples De sécurité des messages vous permet de configurer le client et le serveur avec des certificats pertinents pour exécuter une application hébergée nécessitant une sécurité basée sur des certificats. Le fichier batch peut être exécuté en trois modes. Pour l’exécuter en mode ordinateur unique, tapez setup.bat à une Invite de commandes développeur pour Visual Studio ; pour l’exécuter en mode service, tapez setup.bat service ; et pour l’exécuter en mode client, tapez setup.bat client. Utilisez le mode client et serveur lors de l’exécution de l’exemple sur les ordinateurs. Pour plus d’informations, consultez la procédure de configuration à la fin de cette rubrique. Voici une brève vue d’ensemble des différentes sections des fichiers batch afin qu’ils puissent être modifiés pour s’exécuter dans une configuration appropriée :

Création du certificat client.

La ligne suivante dans le fichier batch crée le certificat client. Le nom du client spécifié est utilisé dans le nom de l’objet 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é du serveur.

La ligne suivante du fichier batch copie le certificat client dans le magasin TrustedPeople du serveur afin que le serveur puisse prendre les décisions d’approbation ou de non-confiance pertinentes. Pour qu’un certificat installé dans le magasin TrustedPeople soit approuvé par un service Windows Communication Foundation (WCF), le mode de validation de certificat client doit être défini sur PeerOrChainTrust ou PeerTrust. Consultez l’exemple de configuration de service précédent pour savoir comment procéder à l’aide d’un fichier de configuration.
```
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 batch 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 batch Setup.bat est exécuté avec un argument de service (tel que setup.bat service) le %SERVER_NAME% contient le nom de domaine complet de l’ordinateur. Sinon, il est défini par défaut sur localhost.
Installation du certificat de serveur dans le magasin de certificats approuvé 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 rooté dans un certificat racine approuvé par le client( par exemple, un certificat émis par Microsoft), cette étape de remplissage du magasin de certificats client avec le certificat de serveur n’est pas nécessaire.
```
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 de processus de travail 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 de Windows autre que celle des États-Unis, vous devez modifier le fichier Setup.bat et remplacer le nom du compte « NT AUTHORITY\NETWORK SERVICE » par votre équivalent régional.

Remarque

Les outils utilisés dans ce fichier batch 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 consiste à ouvrir l’Invite de commandes développeur pour Visual Studio. Cliquez sur Démarrer, puis sélectionnez Tous les programmes, Visual Studio 2012, Outils. Cette invite de commandes contient les chemins d’accès appropriés déjà configurés. 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 d’installation unique pour les exemples Windows Communication Foundation.
Pour générer l’édition C# ou Visual Basic .NET de la solution, conformez-vous aux instructions figurant dans Building the Windows Communication Foundation Samples.

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

Ouvrez une Invite de commandes développeur pour Visual Studio avec des privilèges d’administrateur, puis exécutez Setup.bat à partir du dossier d’installation de l’exemple. Cela installe tous les certificats requis pour l’exécution de l’exemple.

Remarque

Le fichier de commandes Setup.bat est conçu pour être exécuté à partir d’une Invite de commandes développeur pour Visual Studio. La variable d’environnement de chemin d’accès doit pointer vers le répertoire où le Kit de développement logiciel (SDK) est installé. Cette variable d’environnement est automatiquement définie dans une invite de commandes pour développeur pour Visual Studio (2010).
Vérifiez l’accès au service à l’aide d’un navigateur en entrant l’adresse http://localhost/servicemodelsamples/service.svc.
Lancez Client.exe à partir de \client\bin. L’activité du client s’affiche sur l’application console cliente.
Si le client et le service ne sont pas en mesure de communiquer, consultez Conseils de résolution des problèmes pour les exemples WCF.

Pour exécuter l’exemple sur plusieurs ordinateurs

Créez un répertoire sur l’ordinateur de service. Créez une application virtuelle nommée servicemodelsamples pour ce répertoire à l’aide de l’outil de gestion iis (Internet Information Services).
Copiez les fichiers de programme de service de \inetpub\wwwroot\servicemodelsamples dans le répertoire virtuel sur l’ordinateur de service. Vérifiez que vous copiez les fichiers dans le sous-répertoire \bin. Copiez également les fichiers Setup.bat, Cleanup.batet ImportClientCert.bat sur l’ordinateur de service.
Créez un répertoire sur l’ordinateur client pour les fichiers binaires clients.
Copiez les fichiers de programme client dans le répertoire client sur l’ordinateur client. Copiez également les fichiers Setup.bat, Cleanup.batet ImportServiceCert.bat sur le client.
Sur le serveur, exécutez setup.bat service dans une invite de commandes de développement pour Visual Studio avec des privilèges d’administrateur. L’exécution de setup.bat avec l’argument de service crée un certificat de service avec le nom de domaine complet de l’ordinateur et exporte le certificat de service vers un fichier nommé Service.cer.
Modifiez Web.config pour refléter le nouveau nom de certificat (dans l’attribut findValue dans le <serviceCertificate>) qui est le même que le nom de domaine complet de l’ordinateur.
Copiez le fichier Service.cer du répertoire de service vers le répertoire client sur l’ordinateur client.
Sur le client, exécutez setup.bat client à une Invite de commandes développeur pour Visual Studio avec des privilèges d’administrateur. L’exécution de setup.bat avec l’argument client crée un certificat client nommé client.com et exporte le certificat client dans un fichier nommé Client.cer.
Dans le fichier Client.exe.config sur l’ordinateur client, modifiez la valeur d’adresse du point de terminaison pour qu’il 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 à une Invite de commandes développeur pour Visual Studio avec des privilèges d’administrateur. Cela importe le certificat de service à partir du fichier Service.cer dans le magasin CurrentUser - TrustedPeople.
Sur le serveur, exécutez ImportClientCert.bat à une Invite de commandes développeur pour Visual Studio avec des privilèges d’administrateur. Cela importe le certificat client à partir 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 sont pas en mesure de communiquer, consultez Conseils de résolution des problèmes pour les exemples WCF.

Pour nettoyer après le test

Exécutez Cleanup.bat dans le dossier d’exemples une fois que vous avez terminé d’exécuter l’exemple.

Remarque

Ce script ne supprime pas les certificats de service sur un client lors de l’exécution de cet exemple sur les ordinateurs. Si vous avez exécuté des exemples Windows Communication Foundation (WCF) qui utilisent des certificats sur des ordinateurs, veillez à 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

Certificat de sécurité des messages

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 nettoyer après le test

Ressources supplémentaires