Berichtbeveiligingscertificaat

Artikel
03/02/2024

Het MessageSecurity-voorbeeld laat zien hoe u een toepassing implementeert die gebruikmaakt van WS-Security met X.509 v3-certificaatverificatie voor de client en serververificatie vereist met behulp van het X.509 v3-certificaat van de server. In dit voorbeeld worden standaardinstellingen gebruikt, zodat alle toepassingsberichten tussen de client en server zijn ondertekend en versleuteld. Dit voorbeeld is gebaseerd op WSHttpBinding en bestaat uit een clientconsoleprogramma en een servicebibliotheek die wordt gehost door Internet Information Services (IIS). De service implementeert een contract dat een communicatiepatroon aanvraagantwoord definieert.

Notitie

De installatieprocedure en build-instructies voor dit voorbeeld bevinden zich aan het einde van dit onderwerp.

Het voorbeeld demonstreert het beheren van verificatie met behulp van configuratie en het verkrijgen van de identiteit van de beller vanuit de beveiligingscontext, zoals wordt weergegeven in de volgende voorbeeldcode.

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

De service maakt één eindpunt beschikbaar voor communicatie met de service en één eindpunt voor het beschikbaar maken van het WSDL-document van de service met behulp van het WS-MetadataExchange-protocol, gedefinieerd met behulp van het configuratiebestand (Web.config). Het eindpunt bestaat uit een adres, een binding en een contract. De binding is geconfigureerd met een standaard <wsHttpBinding-element> , dat standaard gebruikmaakt van berichtbeveiliging. In dit voorbeeld wordt het clientCredentialType kenmerk ingesteld op Certificaat om clientverificatie te vereisen.

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

Het gedrag geeft de referenties van de service op die worden gebruikt wanneer de client de service verifieert. De onderwerpnaam van het servercertificaat wordt opgegeven in het findValue kenmerk in het <element 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>

De configuratie van het clienteindpunt bestaat uit een absoluut adres voor het service-eindpunt, de binding en het contract. De clientbinding wordt geconfigureerd met de juiste beveiligingsmodus en verificatiemodus. Zorg er bij het uitvoeren van een scenario voor meerdere computers voor dat het adres van het service-eindpunt dienovereenkomstig wordt gewijzigd.

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

De client-implementatie kan instellen dat het certificaat moet worden gebruikt, via het configuratiebestand of via code. In het volgende voorbeeld ziet u hoe u het certificaat instelt voor gebruik in het configuratiebestand.

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

In het volgende voorbeeld ziet u hoe u de service aanroept in uw programma.

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

Wanneer u het voorbeeld uitvoert, worden de bewerkingsaanvragen en -antwoorden weergegeven in het clientconsolevenster. Druk op Enter in het clientvenster om de client af te sluiten.

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.

Met het Setup.bat batchbestand dat is opgenomen in de message security-voorbeelden, kunt u de client en server met relevante certificaten configureren om een gehoste toepassing uit te voeren waarvoor beveiliging op basis van certificaten is vereist. Het batchbestand kan in drie modi worden uitgevoerd. Als u wilt uitvoeren in modustype met één computer setup.bat in een opdrachtprompt voor Ontwikkelaars voor Visual Studio; voor servicemodustype setup.bat service; en voor clientmodustype setup.bat client. Gebruik de client- en servermodus bij het uitvoeren van het voorbeeld op computers. Zie de installatieprocedure aan het einde van dit onderwerp voor meer informatie. Hieronder vindt u een kort overzicht van de verschillende secties van de batchbestanden, zodat ze kunnen worden gewijzigd om in de juiste configuratie te worden uitgevoerd:

Het clientcertificaat maken.

Met de volgende regel in het batchbestand wordt het clientcertificaat gemaakt. De opgegeven clientnaam wordt gebruikt in de onderwerpnaam van het certificaat dat is gemaakt. Het certificaat wordt opgeslagen in My het archief op de CurrentUser opslaglocatie.
```
echo ************
echo making client cert
echo ************
makecert.exe -sr CurrentUser -ss MY -a sha1 -n CN=%CLIENT_NAME% -sky exchange -pe
```
Installeer het clientcertificaat in het vertrouwde certificaatarchief van de server.

Met de volgende regel in het batchbestand wordt het clientcertificaat gekopieerd naar het vertrouwde archief van de server Mensen zodat de server de relevante vertrouwens- of no-trust-beslissingen kan nemen. Als u wilt dat een certificaat dat is geïnstalleerd in het vertrouwde Mensen archief wordt vertrouwd door een WCF-service (Windows Communication Foundation), moet de validatiemodus voor clientcertificaten worden ingesteld PeerOrChainTrust op of PeerTrust. Zie het vorige voorbeeld van de serviceconfiguratie voor meer informatie over hoe u dit kunt doen met behulp van een configuratiebestand.
```
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
```
Het servercertificaat maken.

De volgende regels uit het Setup.bat batchbestand maken het servercertificaat dat moet worden gebruikt.
```
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
```
De variabele %SERVER_NAME% geeft de servernaam op. Het certificaat wordt opgeslagen in het LocalMachine-archief. Als het Setup.bat batchbestand wordt uitgevoerd met een argument van de service (zoals setup.bat service), bevat het %SERVER_NAME% de volledig gekwalificeerde domeinnaam van de computer. Anders wordt standaard localhost gebruikt.
Het servercertificaat installeren in het vertrouwde certificaatarchief van de client.

Met de volgende regel wordt het servercertificaat gekopieerd naar het archief vertrouwde personen van de client. Deze stap is vereist omdat certificaten die worden gegenereerd door Makecert.exe niet impliciet worden vertrouwd door het clientsysteem. Als u al een certificaat hebt dat is geroot in een vertrouwd basiscertificaat van een client, bijvoorbeeld een door Microsoft uitgegeven certificaat, is deze stap voor het invullen van het clientcertificaatarchief met het servercertificaat niet vereist.
```
certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople
```
Machtigingen verlenen voor de persoonlijke sleutel van het certificaat.

De volgende regels in het bestand Setup.bat maken het servercertificaat dat is opgeslagen in het LocalMachine-archief, toegankelijk voor het ASP.NET werkprocesaccount.
```
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
```
Notitie

Als u een niet-Amerikaanse gebruiker gebruikt In de Engelse versie van Windows moet u het Setup.bat-bestand bewerken en de accountnaam NT AUTHORITY\NETWORK SERVICE vervangen door uw regionale equivalent.

Notitie

De hulpprogramma's die in dit batchbestand worden gebruikt, bevinden zich in C:\Program Files\Microsoft Visual Studio 8\Common7\tools of C:\Program Files\Microsoft SDK's\Windows\v6.0\bin. Een van deze mappen moet zich in uw systeempad bevinden. Als u Visual Studio hebt geïnstalleerd, is de eenvoudigste manier om deze map in uw pad op te halen door de opdrachtprompt voor Ontwikkelaars voor Visual Studio te openen. Klik op Start en selecteer vervolgens Alle programma's, Visual Studio 2012, Extra. Deze opdrachtprompt heeft de juiste paden al geconfigureerd. Anders moet u de juiste map handmatig aan uw pad toevoegen.

Het voorbeeld instellen, compileren en uitvoeren

Zorg ervoor dat u de eenmalige installatieprocedure voor de Windows Communication Foundation-voorbeelden hebt uitgevoerd.
Als u de C# of Visual Basic .NET-editie van de oplossing wilt bouwen, volgt u de instructies in het bouwen van de Windows Communication Foundation-voorbeelden.

Het voorbeeld uitvoeren op dezelfde computer

Open een opdrachtprompt voor Ontwikkelaars voor Visual Studio met beheerdersbevoegdheden en voer Setup.bat uit vanuit de voorbeeldinstallatiemap. Hiermee worden alle certificaten geïnstalleerd die vereist zijn voor het uitvoeren van het voorbeeld.

Notitie

Het Setup.bat batchbestand is ontworpen om te worden uitgevoerd vanaf een opdrachtprompt voor ontwikkelaars voor Visual Studio. Hiervoor moet de omgevingsvariabele van het pad verwijzen naar de map waarin de SDK is geïnstalleerd. Deze omgevingsvariabele wordt automatisch ingesteld in een opdrachtprompt voor Ontwikkelaars voor Visual Studio (2010).
Controleer de toegang tot de service met behulp van een browser door het adres http://localhost/servicemodelsamples/service.svcin te voeren.
Start Client.exe vanuit \client\bin. Clientactiviteit wordt weergegeven in de clientconsoletoepassing.
Als de client en service niet kunnen communiceren, raadpleegt u Tips voor probleemoplossing voor WCF-voorbeelden.

Het voorbeeld uitvoeren op computers

Maak een map op de servicecomputer. Maak een virtuele toepassing met de naam servicemodelsamples voor deze map met behulp van het iis-beheerprogramma (Internet Information Services).
Kopieer de serviceprogrammabestanden van \inetpub\wwwroot\servicemodelsamples naar de virtuele map op de servicecomputer. Zorg ervoor dat u de bestanden in de submap \bin kopieert. Kopieer ook de bestanden Setup.bat, Cleanup.bat en ImportClientCert.bat naar de servicecomputer.
Maak een map op de clientcomputer voor de binaire clientbestanden.
Kopieer de clientprogrammabestanden naar de clientmap op de clientcomputer. Kopieer ook de bestanden Setup.bat, Cleanup.bat en ImportServiceCert.bat naar de client.
Voer op de server setup.bat service uit in een opdrachtprompt voor Ontwikkelaars voor Visual Studio met beheerdersbevoegdheden. Als u setup.bat uitvoert met het serviceargument , wordt een servicecertificaat gemaakt met de volledig gekwalificeerde domeinnaam van de computer en wordt het servicecertificaat geëxporteerd naar een bestand met de naam Service.cer.
Bewerk Web.config om de nieuwe certificaatnaam (in het findValue kenmerk in serviceCertificate <) weer te> geven. Dit is hetzelfde als de volledig gekwalificeerde domeinnaam van de computer.
Kopieer het Service.cer-bestand van de servicemap naar de clientmap op de clientcomputer.
Voer op de client setup.bat client uit in een opdrachtprompt voor Ontwikkelaars voor Visual Studio met beheerdersbevoegdheden. Als u setup.bat uitvoert met het clientargument, maakt u een clientcertificaat met de naam client.com en exporteert u het clientcertificaat naar een bestand met de naam Client.cer.
Wijzig in het bestand Client.exe.config op de clientcomputer de adreswaarde van het eindpunt zodat deze overeenkomt met het nieuwe adres van uw service. Doe dit door localhost te vervangen door de volledig gekwalificeerde domeinnaam van de server.
Kopieer het Client.cer-bestand van de clientmap naar de servicemap op de server.
Voer op de client ImportServiceCert.bat uit in een opdrachtprompt voor Ontwikkelaars voor Visual Studio met beheerdersbevoegdheden. Hiermee importeert u het servicecertificaat uit het Service.cer-bestand in het CurrentUser - Trusted Mensen-archief.
Voer op de server ImportClientCert.bat uit in een opdrachtprompt voor Ontwikkelaars voor Visual Studio met beheerdersbevoegdheden. Hiermee importeert u het clientcertificaat uit het Client.cer-bestand in het LocalMachine - Trusted Mensen-archief.
Start Client.exe vanaf een opdrachtpromptvenster op de clientcomputer. Als de client en service niet kunnen communiceren, raadpleegt u Tips voor probleemoplossing voor WCF-voorbeelden.

Opschonen na het voorbeeld

Voer Cleanup.bat uit in de map met voorbeelden nadat u het voorbeeld hebt uitgevoerd.

Notitie

Dit script verwijdert geen servicecertificaten op een client bij het uitvoeren van dit voorbeeld op computers. Als u WCF-voorbeelden (Windows Communication Foundation) hebt uitgevoerd die gebruikmaken van certificaten op computers, moet u de servicecertificaten wissen die zijn geïnstalleerd in het CurrentUser - Trusted Mensen-archief. Gebruik hiervoor de volgende opdracht: bijvoorbeeld: certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name>certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com.

Delen via

Berichtbeveiligingscertificaat

Het voorbeeld instellen, compileren en uitvoeren

Het voorbeeld uitvoeren op dezelfde computer

Het voorbeeld uitvoeren op computers

Opschonen na het voorbeeld

Aanvullende resources