Vorgehensweise: Erstellen eines Verbundclients

Artikel
02/27/2011

In Windows Communication Foundation (WCF) umfasst die Erstellung eines Clients für einen Verbunddienst drei Hauptschritte:

Konfigurieren Sie ein wsFederationHttpBinding element oder eine ähnliche benutzerdefinierte Bindung. Weitere Informationen über zum Erstellen einer entsprechenden Bindung finden Sie unter Vorgehensweise: Erstellen einer WSFederationHttpBinding. Stattdessen können Sie auch das ServiceModel Metadata Utility-Tool (Svcutil.exe) für den Metadatenendpunkt des Verbunddiensts ausführen, um eine Konfigurationsdatei für die Kommunikation mit dem Verbunddienst und einem oder mehreren Sicherheitstokendiensten zu generieren.
Legen Sie die Eigenschaften der IssuedTokenClientCredential-Instanz fest, die verschiedene Aspekte der Interaktion des Clients mit einem Sicherheitstokendienst steuert.
Legen Sie die Eigenschaften der X509CertificateRecipientClientCredential-Instanz fest, die Zertifikate zulässt, welche für die sichere Kommunikation mit gegebenen Endpunkten, z. B. Sicherheitstokendienste, erforderlich sind.

Hinweis:
Es kann eine CryptographicException ausgelöst werden, wenn ein Client die Anmeldeinformationen eines anderen Benutzers, dessen Identität er angenommen hat, die WSFederationHttpBinding-Bindung oder ein benutzerdefiniert ausgestelltes Token und asymmetrische Schlüssel verwendet. Asymmetrische Schlüssel werden in Verbindung mit der WSFederationHttpBinding-Bindung und benutzerdefiniert ausgestellten Token verwendet, wenn die IssuedKeyType-Eigenschaft bzw. die KeyType-Eigenschaft auf AsymmetricKey festgelegt ist. Die CryptographicException-Ausnahme wird ausgelöst, wenn der Client versucht, eine Nachricht zu senden, und kein Benutzerprofil für die Identität vorhanden ist, die der Client angenommen hat. Um dieses Problem zu minimieren, melden Sie sich am Clientcomputer an, oder rufen Sie LoadUserProfile vor dem Senden der Nachricht auf.

Es kann eine CryptographicException ausgelöst werden, wenn ein Client die Anmeldeinformationen eines anderen Benutzers, dessen Identität er angenommen hat, die WSFederationHttpBinding-Bindung oder ein benutzerdefiniert ausgestelltes Token und asymmetrische Schlüssel verwendet. Asymmetrische Schlüssel werden in Verbindung mit der WSFederationHttpBinding-Bindung und benutzerdefiniert ausgestellten Token verwendet, wenn die IssuedKeyType-Eigenschaft bzw. die KeyType-Eigenschaft auf AsymmetricKey festgelegt ist. Die CryptographicException-Ausnahme wird ausgelöst, wenn der Client versucht, eine Nachricht zu senden, und kein Benutzerprofil für die Identität vorhanden ist, die der Client angenommen hat. Um dieses Problem zu minimieren, melden Sie sich am Clientcomputer an, oder rufen Sie LoadUserProfile vor dem Senden der Nachricht auf.

Dieses Thema enthält detaillierte Informationen zu diesen Verfahren. Weitere Informationen über zur Erstellung einer geeigneten Bindung finden Sie unter Vorgehensweise: Erstellen einer WSFederationHttpBinding. Weitere Informationen über zur Funktionsweise von Verbunddiensten finden Sie unter Verbund.

So generieren und untersuchen Sie die Konfiguration für einen Verbunddienst

Führen Sie das ServiceModel Metadata Utility-Tool (Svcutil.exe) mit der Adresse der Metadaten-URL des Diensts als Befehlszeilenparameter aus.
Öffnen Sie die generierte Konfigurationsdatei in einem geeigneten Editor.
Untersuchen Sie die Attribute und den Inhalt der generierten <issuer><issuerMetadata>-Elemente und-Elemente. Diese befinden sich in den <security><wsFederationHttpBinding>-Elementen für die oder den benutzerdefinierten Bindungselementen. Stellen Sie sicher, dass die Adressen die erwarteten Domänenamen oder andere Adressinformationen enthalten. Sie müssen diese Informationen unbedingt überprüfen, weil sich der Client gegenüber diesen Adressen authentifiziert und Informationen wie Benutzername-/Kennwort-Paare offen legt. Wenn es sich bei der Adresse nicht um die erwartete Adresse handelt, könnten Informationen für einen anderen als den vorgesehenen Empfänger zugänglich werden.

Überprüfen Sie eventuell vorhandene <issuedTokenParameters><-Elemente innerhalb des auskommentierten alternativeIssuedTokenParameters>-Elements. Wenn mit dem Tool Svcutil.exe eine Konfiguration für einen Verbunddienst generiert wird und der Verbunddienst oder einer der zwischengeschalteten Sicherheitstokendienste keine Ausstelleradresse, sondern eine Metadatenadresse für einen Sicherheitstokendienst angeben, der mehrere Endpunkte verfügbar macht, dann verweist die resultierende Konfigurationsdatei auf den ersten Endpunkt. Zusätzliche Endpunkte sind in der Konfigurationsdatei auskommentierte <alternativeIssuedTokenParameters>-Elemente.

Bestimmen Sie, ob einer dieser <issuedTokenParameters> einem bereits in der Konfiguration vorhandenen vorzuziehen ist. Beispielsweise kann es der Client vorziehen, sich mit einem Windows CardSpace-Token statt einem Benutzer-/Kennwort-Paar gegenüber einem Sicherheitstokendienst zu authentifizieren.

Hinweis:
Wenn mehrere Sicherheitstokendienste durchlaufen werden müssen, bevor mit dem Dienst kommuniziert wird, ist es möglich, dass ein zwischengelagerter Sicherheitstokendienst den Client an einen falschen Sicherheitstokendienst weiterleitet. Daher müssen Sie sicherstellen, dass der im <issuedTokenParameters> angegebene Endpunkt für den Sicherheitstokendienst den erwarteten Sicherheitstokendienst bezeichnet und keinen unbekannten Sicherheitstokendienst.

Wenn mehrere Sicherheitstokendienste durchlaufen werden müssen, bevor mit dem Dienst kommuniziert wird, ist es möglich, dass ein zwischengelagerter Sicherheitstokendienst den Client an einen falschen Sicherheitstokendienst weiterleitet. Daher müssen Sie sicherstellen, dass der im <issuedTokenParameters> angegebene Endpunkt für den Sicherheitstokendienst den erwarteten Sicherheitstokendienst bezeichnet und keinen unbekannten Sicherheitstokendienst.

So konfigurieren Sie IssuedTokenClientCredential im Code

Greifen Sie auf die IssuedTokenClientCredential zu und zwar über die IssuedToken-Eigenschaft der ClientCredentials-Klasse (die von der ClientCredentials-Eigenschaft der ClientBase-Klasse oder über die ChannelFactory-Klasse zurückgegeben wird), wie im folgenden Beispielcode gezeigt.
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
Falls die Token nicht zwischengespeichert werden müssen, legen Sie die CacheIssuedTokens-Eigenschaft auf false fest. Die CacheIssuedTokens-Eigenschaft steuert, ob solche Token von einem Sicherheitstokendienst zwischengespeichert werden. Wenn diese Eigenschaft auf false festgelegt wird, fordert der Client, sobald er sich gegenüber dem Verbunddienst authentifizieren muss, auch dann ein neues Token vom Sicherheitstokendienst an, wenn ein vorheriges Token noch gültig ist. Wenn diese Eigenschaft auf true festgelegt wird, verwendet der Client ein vorhandenes Token erneut, sobald er sich gegenüber dem Verbunddienst authentifizieren muss (solange das Token nicht ungültig geworden ist). Die Standardeinstellung lautet true.
Wenn ein Zeitlimit für zwischengespeicherte Token erforderlich ist, legen Sie die MaxIssuedTokenCachingTime-Eigenschaft auf einen TimeSpan-Wert fest. Die Eigenschaft gibt an, wie lange ein Token zwischengespeichert werden kann. Nachdem die angegebene Zeitspanne verstrichen ist, wird das Token aus dem Clientcache entfernt. Standardmäßig werden Token unendlich lange zwischengespeichert. Im folgenden Beispiel wird die Zeitspanne auf 10 Minuten eingestellt.
```
itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
```
```
itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
```
Optional. Legen Sie die IssuedTokenRenewalThresholdPercentage-Eigenschaft auf einen Prozentwert fest. Der Standardwert lautet 60 (Prozent). Die Eigenschaft gibt einen Prozentwert der Gültigkeitsdauer des Tokens an. Wenn das ausgestellte Token beispielsweise 10 Stunden lang gültig ist und IssuedTokenRenewalThresholdPercentage auf 80 festgelegt wird, dann wird das Token nach acht Stunden erneuert. Im folgenden Beispiel wird als Wert 80 Prozent festgelegt.
```
itcc.IssuedTokenRenewalThresholdPercentage = 80
```
```
itcc.IssuedTokenRenewalThresholdPercentage = 80;
```
Das Erneuerungsintervall, das durch die Gültigkeitsdauer des Tokens und den IssuedTokenRenewalThresholdPercentage-Wert bestimmt wird, wird durch den MaxIssuedTokenCachingTime-Wert außer Kraft gesetzt, wenn die Zwischenspeicherungsdauer kürzer als die durch den Erneuerungsschwellenwert festgelegte Zeitspanne ist. Wenn beispielsweise das Produkt aus IssuedTokenRenewalThresholdPercentage und der Gültigkeitsdauer des Tokens acht Stunden beträgt und der MaxIssuedTokenCachingTime-Wert gleich 10 Minuten ist, dann fordert der Client alle 10 Minuten vom Sicherheitstokendienst ein aktualisiertes Token an.

Wenn ein anderer Schlüsselentropiemodus als CombinedEntropy für eine Bindung erforderlich ist, bei der nicht Nachrichtensicherheit oder Transportsicherheit mit Nachrichtenanmeldeinformationen verwendet wird (beispielsweise eine Bindung, die über kein SecurityBindingElement verfügt), dann legen Sie die DefaultKeyEntropyMode-Eigenschaft auf einen geeigneten Wert fest. Der Entropiemodus bestimmt, ob symmetrische Schlüssel mit der DefaultKeyEntropyMode-Eigenschaft gesteuert werden können. Diese Standardeinstellung lautet CombinedEntropy, wobei sowohl der Client als auch der Tokenaussteller Daten bereitstellen, durch deren Kombination der tatsächliche Schlüssel erzeugt wird. Andere Werte lauten ClientEntropy und ServerEntropy, womit festgelegt wird, dass der gesamte Schlüssel vom Client bzw. vom Server angegeben wird. Im folgenden Beispiel wird die Eigenschaft so festgelegt, dass nur die Serverdaten für den Schlüssel verwendet werden.

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

Hinweis:
Wenn in einem Sicherheitstokendienst oder einer Dienstbindung ein SecurityBindingElement vorhanden ist, wird der auf IssuedTokenClientCredential festgelegte DefaultKeyEntropyMode durch die KeyEntropyMode-Eigenschaft von SecurityBindingElement überschrieben.

Konfigurieren Sie ausstellerspezifische Endpunktverhalten, indem Sie diese Verhalten der Auflistung hinzufügen, die von der IssuerChannelBehaviors-Eigenschaft zurückgegeben wird.
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
```
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
```

So konfigurieren Sie IssuedTokenClientCredential in der Konfiguration

Erstellen Sie ein <issuedToken><clientCredentials>-Element als untergeordnetes Element des-Elements in einem Endpunktverhalten.
Wenn die Token nicht zwischengespeichert werden müssen, legen Sie das cacheIssuedTokens-Attribut (des <issuedToken>-Elements) auf false fest.
Wenn ein Zeitlimit für zwischengespeicherte Token erforderlich ist, legen Sie das maxIssuedTokenCachingTime-Attribut für das <issuedToken>-Element auf einen geeigneten Wert fest. Beispiel:
<issuedToken maxIssuedTokenCachingTime='00:10:00' />
Wenn ein anderer Wert als die Standardeinstellung bevorzugt wird, legen Sie das issuedTokenRenewalThresholdPercentage-Attribut für das <issuedToken>-Element auf einen geeigneten Wert fest. Beispiel:
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />
```
Wenn ein anderer Schlüsselentropiemodus als CombinedEntropy für eine Bindung erforderlich ist, bei der nicht Nachrichtensicherheit oder Transportsicherheit mit Nachrichtenanmeldeinformationen verwendet wird (beispielsweise eine Bindung, die über kein SecurityBindingElement verfügt), dann legen Sie das defaultKeyEntropyMode-Attribut für das <issuedToken>ServerEntropy-Element je nach Bedarf auf ClientEntropy oder fest.
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />
```
Optional. Konfigurieren Sie ausstellerspezifisches, benutzerdefiniertes Endpunktverhalten, indem Sie ein <issuerChannelBehaviors>-Element als untergeordnetes Element des <issuedToken>-Elements erstellen. Erstellen Sie für jedes Verhalten ein <add>-Element als untergeordnetes Element des <issuerChannelBehaviors>-Elements. Geben Sie die Ausstelleradresse des Verhaltens an, indem Sie das issuerAddress-Attribut für das <add>-Element festlegen. Geben Sie das Verhalten an, indem Sie das behaviorConfiguration-Attribut für das <add>-Element festlegen.
```
<issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>
```

So konfigurieren Sie X509CertificateRecipientClientCredential im Code

Greifen Sie über die ServiceCertificate-Eigenschaft der ClientCredentials-Eigenschaft der ClientBase-Klasse oder die ChannelFactory-Eigenschaft auf X509CertificateRecipientClientCredential zu.

Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

Wenn eine X509Certificate2-Instanz für das Zertifikat eines gegebenen Endpunkts verfügbar ist, verwenden Sie die Add-Methode der Auflistung, die von der ScopedCertificates-Eigenschaft zurückgegeben wird.
```
rcc.ScopedCertificates.Add(New Uri("https://fabrikam.com/sts"), cert)
```
```
rcc.ScopedCertificates.Add(new Uri("https://fabrikam.com/sts"), cert);
```

Wenn keine X509Certificate2-Instanz verfügbar ist, verwenden Sie die SetScopedCertificate-Methode der X509CertificateRecipientClientCredential-Klasse, wie im folgenden Beispiel gezeigt.

rcc.SetScopedCertificate(StoreLocation.CurrentUser, _
            StoreName.TrustedPeople, _
            X509FindType.FindBySubjectName, _
            "FabrikamSTS", _
            New Uri("https://fabrikam.com/sts"))

public void snippet20(CalculatorClient client)
{
    X509CertificateRecipientClientCredential rcc = client.ClientCredentials.ServiceCertificate;
    rcc.SetScopedCertificate(StoreLocation.CurrentUser,
                             StoreName.TrustedPeople,
                             X509FindType.FindBySubjectName,
                             "FabrikamSTS",
                             new Uri("https://fabrikam.com/sts"));
}

So konfigurieren Sie X509CertificateRecipientClientCredential in der Konfiguration

Erstellen Sie ein <scopedCertificates><serviceCertifcate>-Element als untergeordnetes Element des <clientCredentials>-Elements, das wiederum ein untergeordnetes Element des -Elements in einem Endpunktverhalten darstellt.
Erstellen Sie ein <add><scopedCertificates>-Element als untergeordnetes Element des -Elements. Geben Sie Werte für die Attribute storeLocation, storeName, x509FindType und findValue an, um auf das geeignete Zertifikat zu verweisen. Legen Sie das targetUri-Attribut auf einen Wert fest, der die Adresse des Endpunkts angibt, für den das Zertifikat verwendet werden soll. Dies wird im folgenden Beispiel gezeigt.
```
<scopedCertificates>
 <add targetUri="https://fabrikam.com/sts" 
      storeLocation="CurrentUser"
      storeName="TrustedPeople"
      x509FindType="FindBySubjectName"
      findValue="FabrikamSTS" />
</scopedCertificates>
```

Beispiel

Im nächsten Codebeispiel wird eine Instanz der IssuedTokenClientCredential-Klasse im Code konfiguriert.

// This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
public static void ConfigureIssuedTokenClientCredentials(ChannelFactory cf, bool cacheTokens,
                                                          TimeSpan tokenCacheTime, int renewalPercentage,
                                                          SecurityKeyEntropyMode entropyMode
                                                          )
{
    if (cf == null)
    {
        throw new ArgumentNullException("ChannelFactory");
    }
    // Set the CacheIssuedTokens property
    cf.Credentials.IssuedToken.CacheIssuedTokens = cacheTokens;

    // Set the MaxIssuedTokenCachingTime property
    cf.Credentials.IssuedToken.MaxIssuedTokenCachingTime = tokenCacheTime;

    // Set the IssuedTokenRenewalThresholdPercentage property
    cf.Credentials.IssuedToken.IssuedTokenRenewalThresholdPercentage = renewalPercentage;

    // Set the DefaulyKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}

Sicherheit

Um einer möglichen Enthüllung von Informationen vorzubeugen, sollten Clients, die mit dem Tool Svcutil.exe Metadaten von Verbundendpunkten verarbeiten, sicherstellen, dass es sich bei den resultierenden Sicherheitstokendienst-Adressen auch tatsächlich um die erwarteten Adressen handelt. Dies ist insbesondere wichtig, wenn ein Sicherheitstokendienst mehrere Endpunkte verfügbar macht, weil das Tool Svcutil.exe die Konfigurationsdatei generiert, die mit einem solchen Endpunkt verwendet werden soll. Sie müssen überprüfen, ob die Konfigurationsdatei für den richtigen Endpunkt erzeugt wurde.

LocalIssuer erforderlich

Wenn erwartet wird, dass Clients immer einen lokalen Aussteller verwenden, ist Folgendes zu beachten: Die Standardausgabe von Svcutil.exe resultiert darin, dass der lokale Aussteller nicht verwendet wird, wenn der vorletzte Sicherheitstokendienst in der Kette eine Ausstelleradresse oder eine Ausstellermetaadresse angibt.

Weitere Informationen über zum Festlegen der Eigenschaften LocalIssuerAddress, LocalIssuerBinding und LocalIssuerChannelBehaviors der IssuedTokenClientCredential-Klasse finden Sie unter Vorgehensweise: Konfigurieren eines lokalen Ausstellers.

Zertifikate mit Gültigkeitsbereich

Wenn zur Kommunikation mit einem Sicherheitstokendienst Dienstzertifikate angegeben werden müssen, weil keine Zertifikatsaushandlung verwendet wird, können diese mit der ScopedCertificates-Eigenschaft der X509CertificateRecipientClientCredential-Klasse angegeben werden. Die SetDefaultCertificate-Methode akzeptiert die beiden Parameter Uri und X509Certificate2. Das angegebene Zertifikat wird zur Kommunikation mit Endpunkten beim angegebenen URI verwendet. Stattdessen können Sie auch mit der SetScopedCertificate-Methode ein Zertifikat der Auflistung hinzufügen, die von der ScopedCertificates-Eigenschaft zurückgegeben wird.

Hinweis:
Das Clientkonzept von Zertifikaten, deren Bereich durch einen gegebenen URI festgelegt wird, gilt nur für Anwendungen, die ausgehende Aufrufe an Dienste durchführen, die bei diesen URIs Endpunkte verfügbar machen. Es gilt nicht für Zertifikate, die zum Signieren ausgestellter Token verwendet werden, wie jene Zertifikate, die auf dem Server in der Auflistung konfiguriert werden, die von der KnownCertificates-Eigenschaft der IssuedTokenServiceCredential-Klasse zurückgegeben werden. Weitere Informationen finden Sie unter Vorgehensweise: Konfigurieren von Anmeldeinformationen auf einem Verbunddienst.

Das Clientkonzept von Zertifikaten, deren Bereich durch einen gegebenen URI festgelegt wird, gilt nur für Anwendungen, die ausgehende Aufrufe an Dienste durchführen, die bei diesen URIs Endpunkte verfügbar machen. Es gilt nicht für Zertifikate, die zum Signieren ausgestellter Token verwendet werden, wie jene Zertifikate, die auf dem Server in der Auflistung konfiguriert werden, die von der KnownCertificates-Eigenschaft der IssuedTokenServiceCredential-Klasse zurückgegeben werden. Weitere Informationen finden Sie unter Vorgehensweise: Konfigurieren von Anmeldeinformationen auf einem Verbunddienst.

Siehe auch

Aufgaben

Verbundbeispiel
Vorgehensweise: Deaktivieren sicherer Sitzungen auf einer WSFederationHttpBinding
Vorgehensweise: Erstellen einer WSFederationHttpBinding
Vorgehensweise: Konfigurieren von Anmeldeinformationen auf einem Verbunddienst
Vorgehensweise: Konfigurieren eines lokalen Ausstellers
How to: Secure Metadata Endpoints

Konzepte

Security Considerations with Metadata

Freigeben über