Certyfikat zabezpieczeń komunikatów

Artykuł
03/02/2024

W przykładzie MessageSecurity pokazano, jak zaimplementować aplikację korzystającą z usługi WS-Security z uwierzytelnianiem certyfikatu X.509 w wersji 3 dla klienta i wymaga uwierzytelniania serwera przy użyciu certyfikatu X.509 v3 serwera. W tym przykładzie są używane ustawienia domyślne, takie jak, że wszystkie komunikaty aplikacji między klientem a serwerem są podpisane i szyfrowane. Ten przykład jest oparty na usłudze WSHttpBinding i składa się z programu konsolowego klienta i biblioteki usług hostowanej przez usługi Internet Information Services (IIS). Usługa implementuje kontrakt, który definiuje wzorzec komunikacji typu żądanie-odpowiedź.

Uwaga

Procedura instalacji i instrukcje kompilacji dla tego przykładu znajdują się na końcu tego tematu.

W przykładzie pokazano kontrolowanie uwierzytelniania przy użyciu konfiguracji i sposobu uzyskiwania tożsamości obiektu wywołującego z kontekstu zabezpieczeń, jak pokazano w poniższym przykładowym kodzie.

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;
    }
    ...
}

Usługa uwidacznia jeden punkt końcowy do komunikowania się z usługą i jeden punkt końcowy do uwidaczniania dokumentu WSDL usługi przy użyciu protokołu WS-MetadataExchange zdefiniowanego przy użyciu pliku konfiguracji (Web.config). Punkt końcowy składa się z adresu, powiązania i kontraktu. Powiązanie jest konfigurowane przy użyciu standardowego <elementu wsHttpBinding> , który domyślnie używa zabezpieczeń komunikatów. Ten przykład ustawia clientCredentialType atrybut na Certyfikat, aby wymagać uwierzytelniania klienta.

<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>

Zachowanie określa poświadczenia usługi, które są używane podczas uwierzytelniania usługi przez klienta. Nazwa podmiotu certyfikatu serwera jest określona w atrybucie findValue w <elemecie 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>

Konfiguracja punktu końcowego klienta składa się z bezwzględnego adresu punktu końcowego usługi, powiązania i kontraktu. Powiązanie klienta jest konfigurowane z odpowiednim trybem zabezpieczeń i trybem uwierzytelniania. W przypadku uruchamiania w scenariuszu między komputerami upewnij się, że adres punktu końcowego usługi został odpowiednio zmieniony.

<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>

Implementacja klienta może ustawić certyfikat do użycia za pośrednictwem pliku konfiguracji lub kodu. W poniższym przykładzie pokazano, jak ustawić certyfikat do użycia w pliku konfiguracji.

<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>

W poniższym przykładzie pokazano, jak wywołać usługę w programie.

// 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();

Po uruchomieniu przykładu żądania operacji i odpowiedzi są wyświetlane w oknie konsoli klienta. Naciśnij klawisz ENTER w oknie klienta, aby zamknąć klienta.

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.

Plik wsadowy Setup.bat dołączony do przykładów zabezpieczeń komunikatów umożliwia skonfigurowanie klienta i serwera z odpowiednimi certyfikatami w celu uruchomienia hostowanej aplikacji wymagającej zabezpieczeń opartych na certyfikatach. Plik wsadowy można uruchomić w trzech trybach. Aby uruchomić w trybie pojedynczego komputera, wpisz setup.bat w wierszu polecenia dewelopera dla programu Visual Studio; dla trybu usługi typ setup.bat usługi, a dla trybu klienta typ setup.bat klienta. Podczas uruchamiania przykładu na komputerach użyj trybu klienta i serwera. Aby uzyskać szczegółowe informacje, zobacz procedurę konfiguracji na końcu tego tematu. Poniżej przedstawiono krótkie omówienie różnych sekcji plików wsadowych, dzięki czemu można je zmodyfikować w celu uruchomienia w odpowiedniej konfiguracji:

Tworzenie certyfikatu klienta.

Poniższy wiersz w pliku wsadowym tworzy certyfikat klienta. Określona nazwa klienta jest używana w nazwie podmiotu utworzonego certyfikatu. Certyfikat jest przechowywany w My magazynie w CurrentUser lokalizacji magazynu.
```
echo ************
echo making client cert
echo ************
makecert.exe -sr CurrentUser -ss MY -a sha1 -n CN=%CLIENT_NAME% -sky exchange -pe
```
Instalowanie certyfikatu klienta w magazynie zaufanych certyfikatów serwera.

Poniższy wiersz w pliku wsadowym kopiuje certyfikat klienta do magazynu Zaufane Osoby serwera, aby serwer mógł podejmować odpowiednie decyzje zaufania lub braku zaufania. Aby certyfikat zainstalowany w magazynie Trusted Osoby był zaufany przez usługę Windows Communication Foundation (WCF), należy ustawić tryb weryfikacji certyfikatu klienta na PeerOrChainTrust wartość lub PeerTrust. Zapoznaj się z poprzednim przykładem konfiguracji usługi, aby dowiedzieć się, jak można to zrobić przy użyciu pliku konfiguracji.
```
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
```
Tworzenie certyfikatu serwera.

Następujące wiersze z pliku wsadowego Setup.bat tworzą certyfikat serwera do użycia.
```
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
```
Zmienna %SERVER_NAME% określa nazwę serwera. Certyfikat jest przechowywany w magazynie LocalMachine. Jeśli plik wsadowy Setup.bat jest uruchamiany z argumentem usługi (takiej jak usługa setup.bat), %SERVER_NAME% zawiera w pełni kwalifikowaną nazwę domeny komputera. W przeciwnym razie wartość domyślna to localhost.
Instalowanie certyfikatu serwera w zaufanym magazynie certyfikatów klienta.

Poniższy wiersz kopiuje certyfikat serwera do magazynu zaufanych osób klienta. Ten krok jest wymagany, ponieważ certyfikaty generowane przez Makecert.exe nie są niejawnie zaufane przez system kliencki. Jeśli masz już certyfikat, który jest zakorzeniony w zaufanym certyfikacie głównym klienta — na przykład certyfikat wystawiony przez firmę Microsoft — ten krok wypełniania magazynu certyfikatów klienta przy użyciu certyfikatu serwera nie jest wymagany.
```
certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople
```

Udzielanie uprawnień do klucza prywatnego certyfikatu.

Następujące wiersze w pliku Setup.bat sprawiają, że certyfikat serwera przechowywany w magazynie LocalMachine jest dostępny dla konta procesu roboczego 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

Uwaga

Jeśli używasz spoza USA Angielska wersja systemu Windows, należy edytować plik Setup.bat i zastąpić nazwę konta "NT AUTHORITY\NETWORK SERVICE" odpowiednikiem regionalnym.

Uwaga

Narzędzia używane w tym pliku wsadowym znajdują się w folderze C:\Program Files\Microsoft Visual Studio 8\Common7\tools lub C:\Program Files\Microsoft SDKs\Windows\v6.0\bin. Jeden z tych katalogów musi znajdować się w ścieżce systemowej. Jeśli masz zainstalowany program Visual Studio, najprostszym sposobem uzyskania tego katalogu w ścieżce jest otwarcie wiersza polecenia dewelopera dla programu Visual Studio. Kliknij przycisk Start, a następnie wybierz pozycję Wszystkie programy, Visual Studio 2012, Narzędzia. Ten wiersz polecenia ma już skonfigurowane odpowiednie ścieżki. W przeciwnym razie należy ręcznie dodać odpowiedni katalog do ścieżki.

Aby skonfigurować, skompilować i uruchomić przykład

Upewnij się, że wykonano procedurę instalacji jednorazowej dla przykładów programu Windows Communication Foundation.
Aby skompilować wersję rozwiązania w języku C# lub Visual Basic .NET, postępuj zgodnie z instrukcjami w temacie Building the Windows Communication Foundation Samples (Tworzenie przykładów programu Windows Communication Foundation).

Aby uruchomić przykład na tym samym komputerze

Otwórz wiersz polecenia dewelopera dla programu Visual Studio z uprawnieniami administratora i uruchom Setup.bat z folderu przykładowej instalacji. Spowoduje to zainstalowanie wszystkich certyfikatów wymaganych do uruchomienia przykładu.

Uwaga

Plik wsadowy Setup.bat jest przeznaczony do uruchamiania z poziomu wiersza polecenia dla deweloperów dla programu Visual Studio. Wymaga to, aby zmienna środowiskowa ścieżki wskazywała katalog, w którym zainstalowano zestaw SDK. Ta zmienna środowiskowa jest automatycznie ustawiana w wierszu polecenia dla deweloperów dla programu Visual Studio (2010).
Sprawdź dostęp do usługi przy użyciu przeglądarki, wprowadzając adres http://localhost/servicemodelsamples/service.svc.
Uruchom Client.exe z \client\bin. Działanie klienta jest wyświetlane w aplikacji konsolowej klienta.
Jeśli klient i usługa nie mogą się komunikować, zobacz Rozwiązywanie problemów Wskazówki dla przykładów programu WCF.

Aby uruchomić przykład na komputerach

Utwórz katalog na komputerze usługi. Utwórz aplikację wirtualną o nazwie servicemodelsamples dla tego katalogu przy użyciu narzędzia do zarządzania usługami Internet Information Services (IIS).
Skopiuj pliki programu usługi z folderu \inetpub\wwwroot\servicemodelsamples do katalogu wirtualnego na komputerze usługi. Upewnij się, że skopiujesz pliki w podkatalogu \bin. Skopiuj również pliki Setup.bat, Cleanup.bat i ImportClientCert.bat na komputer usługi.
Utwórz katalog na komputerze klienckim dla plików binarnych klienta.
Skopiuj pliki programu klienckiego do katalogu klienta na komputerze klienckim. Skopiuj również pliki Setup.bat, Cleanup.bat i ImportServiceCert.bat do klienta.
Na serwerze uruchom usługę setup.bat w wierszu polecenia dewelopera dla programu Visual Studio z uprawnieniami administratora. Uruchomienie setup.bat z argumentem usługi tworzy certyfikat usługi z w pełni kwalifikowaną nazwą domeny komputera i eksportuje certyfikat usługi do pliku o nazwie Service.cer.
Edytuj plik Web.config, aby odzwierciedlić nową nazwę certyfikatu (w atrybucie findValue serviceCertificate>), która jest taka sama jak w <pełni kwalifikowana nazwa domeny komputera.
Skopiuj plik Service.cer z katalogu usługi do katalogu klienta na komputerze klienckim.
Na kliencie uruchom setup.bat klienta w wierszu polecenia dewelopera dla programu Visual Studio z uprawnieniami administratora. Uruchomienie setup.bat z argumentem klienta tworzy certyfikat klienta o nazwie client.com i eksportuje certyfikat klienta do pliku o nazwie Client.cer.
W pliku Client.exe.config na komputerze klienckim zmień wartość adresu punktu końcowego, aby był zgodny z nowym adresem usługi. W tym celu należy zastąpić hosta lokalnego w pełni kwalifikowaną nazwą domeny serwera.
Skopiuj plik Client.cer z katalogu klienta do katalogu usługi na serwerze.
Na kliencie uruchom ImportServiceCert.bat w wierszu polecenia dewelopera dla programu Visual Studio z uprawnieniami administracyjnymi. Spowoduje to zaimportowanie certyfikatu usługi z pliku Service.cer do magazynu CurrentUser — Trusted Osoby.
Na serwerze uruchom ImportClientCert.bat w wierszu polecenia dla deweloperów programu Visual Studio z uprawnieniami administracyjnymi. Spowoduje to zaimportowanie certyfikatu klienta z pliku Client.cer do magazynu LocalMachine — Trusted Osoby.
Na komputerze klienckim uruchom Client.exe w oknie wiersza polecenia. Jeśli klient i usługa nie mogą się komunikować, zobacz Rozwiązywanie problemów Wskazówki dla przykładów programu WCF.

Aby wyczyścić po próbce

Uruchom Cleanup.bat w folderze samples po zakończeniu uruchamiania przykładu.

Uwaga

Ten skrypt nie usuwa certyfikatów usługi na kliencie podczas uruchamiania tego przykładu na komputerach. Jeśli uruchomiono przykłady programu Windows Communication Foundation (WCF) korzystające z certyfikatów na komputerach, pamiętaj, aby wyczyścić certyfikaty usługi zainstalowane w magazynie CurrentUser — Trusted Osoby. W tym celu użyj następującego polecenia: certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name> na przykład: certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com.

Udostępnij za pośrednictwem

Certyfikat zabezpieczeń komunikatów

Aby skonfigurować, skompilować i uruchomić przykład

Aby uruchomić przykład na tym samym komputerze

Aby uruchomić przykład na komputerach

Aby wyczyścić po próbce

Dodatkowe zasoby