Vorgehensweise: Erstellen eines Verbundclients

  • Artikel

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

  1. Konfigurieren Sie eine <wsFederationHttpBinding>- oder eine ähnliche benutzerdefinierte Bindung. Weitere Informationen zum Erstellen einer entsprechenden Bindung finden Sie unter Gewusst wie: 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.

  2. Legen Sie die Eigenschaften der IssuedTokenClientCredential-Instanz fest, die verschiedene Aspekte der Interaktion des Clients mit einem Sicherheitstokendienst steuert.

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

Dieses Thema enthält detaillierte Informationen zu diesen Verfahren. Weitere Informationen zum Erstellen einer entsprechenden Bindung finden Sie unter Gewusst wie: Erstellen einer WSFederationHttpBinding. Weitere Informationen zur Funktionsweise eines Verbunddiensts finden Sie unter Verbund.

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

  1. Führen Sie das ServiceModel Metadata Utility-Tool (Svcutil.exe) mit der Adresse der Metadaten-URL des Diensts als Befehlszeilenparameter aus.

  2. Öffnen Sie die generierte Konfigurationsdatei in einem geeigneten Editor.

  3. Untersuchen Sie die Attribute und den Inhalt aller generierten <Issuer>- und <issuerMetadata>-Elemente. Diese befinden sich innerhalb der <securiy>-Elemente für die <wsFederationHttpBinding>-Elemente oder die Elemente benutzerdefinierter Bindungen. 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.

  4. Überprüfen Sie eventuell vorhandene zusätzliche <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 als auskommentierte <alternativeIssuedTokenParameters>-Elemente enthalten.

    Ermitteln Sie, ob einer dieser <issuedTokenParameters> dem bereits in der Konfiguration vorhandenen Parameter vorzuziehen ist. Beispielsweise kann es der Client vorziehen, sich mit einem Windows CardSpace-Token statt mit einer Kombination aus Benutzername und Kennwort bei 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. Stellen Sie daher sicher, dass der in <issuedTokenParameters> angegebene Endpunkt für den Sicherheitstokendienst den erwarteten Sicherheitstokendienst und keinen unbekannten Sicherheitstokendienst bezeichnet.

So konfigurieren Sie IssuedTokenClientCredential im Code

  1. Greifen Sie auf die IssuedTokenClientCredential zu und zwar über die IssuedToken-Eigenschaft der ClientCredentials-Klasse (die von der ClientCredentials-Eigenschaft der ClientBase<TChannel>-Klasse oder über die ChannelFactory-Klasse zurückgegeben wird), wie im folgenden Beispielcode gezeigt.

    IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;

    Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken

  2. 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). Der Standardwert lautet true.

  3. 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)

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

  5. Wenn ein anderer Schlüsselentropiemodus als CombinedEntropy für eine Bindung erforderlich ist, bei der keine Nachrichtensicherheit oder Transportsicherheit mit Nachrichtenanmeldeinformationen verwendet wird (beispielsweise eine Bindung, die über kein SecurityBindingElement verfügt), 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 DefaultKeyEntropyMode festgelegte IssuedTokenClientCredential durch die KeyEntropyMode-Eigenschaft von SecurityBindingElement überschrieben.

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

  1. Erstellen Sie ein <issuedToken>-Element als untergeordnetes Element des <issuedToken>-Elements in einem Endpunktverhalten.

  2. Wenn die Token nicht zwischengespeichert werden müssen, legen Sie das cacheIssuedTokens-Attribut (des <issuedToken>-Elements) auf false fest.

  3. 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' />

  4. 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" />

  5. 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 fest.

    <issuedToken defaultKeyEntropyMode = "ServerEntropy" />

  6. 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 selbst 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

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

    X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

    Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

  2. 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("http://fabrikam.com/sts"), cert);

    rcc.ScopedCertificates.Add(New Uri("http://fabrikam.com/sts"), cert)

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

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

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

So konfigurieren Sie X509CertificateRecipientClientCredential in der Konfiguration

  1. Erstellen Sie ein <scopedCertificates>-Element als untergeordnetes Element des <serviceCertificate>-Elements, das wiederum ein untergeordnetes Element des <clientCredentials>-Elements in einem Endpunktverhalten ist.

  2. Erstellen Sie ein <add>-Element als untergeordnetes Element des <scopedCertificates>-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="http://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("cf");
    }
    // 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 DefaultKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}


' This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
Public Shared Sub ConfigureIssuedTokenClientCredentials(ByVal cf As ChannelFactory, _
                                                        ByVal cacheTokens As Boolean, _
                                                        ByVal tokenCacheTime As TimeSpan, _
                                                        ByVal renewalPercentage As Integer, _
                                                        ByVal entropyMode As SecurityKeyEntropyMode)
    If cf Is Nothing Then
        Throw New ArgumentNullException("ChannelFactory")
    End If
    ' Set the CacheIssuedTokens property
    With cf.Credentials.IssuedToken
        .CacheIssuedTokens = cacheTokens

        ' Set the MaxIssuedTokenCachingTime property
        .MaxIssuedTokenCachingTime = tokenCacheTime

        ' Set the IssuedTokenRenewalThresholdPercentage property
        .IssuedTokenRenewalThresholdPercentage = renewalPercentage

        ' Set the DefaultKeyEntropyMode property
        .DefaultKeyEntropyMode = entropyMode
    End With
End Sub

.NET Framework-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 zum Festlegen der Eigenschaften LocalIssuerAddress, LocalIssuerBinding und LocalIssuerChannelBehaviors der IssuedTokenClientCredential-Klasse finden Sie unter Gewusst wie: 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 Gewusst wie: Konfigurieren von Anmeldeinformationen für einen Verbunddienst.

Siehe auch