Udostępnij za pośrednictwem

Instrukcje: Tworzenie klienta federacyjnego

  • Artykuł

W programie Windows Communication Foundation (WCF) tworzenie klienta dla usługi federacyjnej składa się z trzech głównych kroków:

  1. Skonfiguruj powiązanie <niestandardowe wsFederationHttpBinding> lub podobne. Aby uzyskać więcej informacji na temat tworzenia odpowiedniego powiązania, zobacz How to: Create a WSFederationHttpBinding (Instrukcje: tworzenie federacji WSFederationHttpBinding). Alternatywnie uruchom narzędzie ServiceModel Metadata Tool (Svcutil.exe) względem punktu końcowego metadanych usługi federacyjnej, aby wygenerować plik konfiguracji do komunikacji z usługą federacyjną i co najmniej jedną usługą tokenu zabezpieczającego.

  2. Ustaw właściwości IssuedTokenClientCredential , które steruje różnymi aspektami interakcji klienta z usługą tokenu zabezpieczającego.

  3. Ustaw właściwości X509CertificateRecipientClientCredentialelementu , które umożliwiają certyfikatom wymaganym do bezpiecznego komunikowania się z określonymi punktami końcowymi, takimi jak usługi tokenów zabezpieczających.

Uwaga

Element CryptographicException może być zgłaszany, gdy klient używa personifikowanych poświadczeń, WSFederationHttpBinding powiązania lub tokenu wystawionego przez użytkownika niestandardowego oraz kluczy asymetrycznych. Klucze asymetryczne są używane z powiązaniami WSFederationHttpBinding i tokenami wystawionymi niestandardowymi, gdy IssuedKeyType właściwości i KeyType , odpowiednio, są ustawione na AsymmetricKeywartość . Element CryptographicException jest zgłaszany, gdy klient próbuje wysłać komunikat, a profil użytkownika nie istnieje dla tożsamości, którą klient personifikuje. Aby rozwiązać ten problem, zaloguj się na komputerze klienckim lub wywołaj połączenie LoadUserProfile przed wysłaniem komunikatu.

Ten temat zawiera szczegółowe informacje o tych procedurach. Aby uzyskać więcej informacji na temat tworzenia odpowiedniego powiązania, zobacz How to: Create a WSFederationHttpBinding (Instrukcje: tworzenie federacji WSFederationHttpBinding). Aby uzyskać więcej informacji na temat działania usługi federacyjnej, zobacz Federacja.

Aby wygenerować i zbadać konfigurację usługi federacyjnej

  1. Uruchom narzędzie ServiceModel Metadata Tool (Svcutil.exe) przy użyciu adresu URL metadanych usługi jako parametru wiersza polecenia.

  2. Otwórz wygenerowany plik konfiguracji w odpowiednim edytorze.

  3. Sprawdź atrybuty i zawartość wszystkich wygenerowanych elementów wystawcy> i <wystawcyMetadata>.< Znajdują się one w elementach <zabezpieczeń> dla <elementów wsFederationHttpBinding> lub niestandardowych powiązań. Upewnij się, że adresy zawierają oczekiwane nazwy domen lub inne informacje o adresach. Ważne jest, aby sprawdzić te informacje, ponieważ klient uwierzytelnia się na tych adresach i może ujawnić informacje, takie jak nazwy użytkownika/pary haseł. Jeśli adres nie jest oczekiwanym adresem, może to spowodować ujawnienie informacji niezamierzonemu odbiorcy.

  4. Sprawdź wszelkie dodatkowe <elementy issuedTokenParameters> wewnątrz skomentowanego <alternativeIssuedTokenParameters> elementu. W przypadku używania narzędzia Svcutil.exe do generowania konfiguracji dla usługi federacyjnej, jeśli usługa federacyjna lub usługi pośredniego tokenu zabezpieczającego nie określają adresu wystawcy, ale raczej określają adres metadanych dla usługi tokenu zabezpieczającego, która uwidacznia wiele punktów końcowych, wynikowy plik konfiguracji odnosi się do pierwszego punktu końcowego. Dodatkowe punkty końcowe znajdują się <alternativeIssuedTokenParameters> w pliku konfiguracji jako elementy komentarza.

    Ustal, czy jeden z tych <issuedTokenParameters> elementów jest preferowany do tej, która jest już obecna w konfiguracji. Na przykład klient może preferować uwierzytelnianie w usłudze tokenu zabezpieczającego przy użyciu tokenu Usługi KartSpace systemu Windows, a nie pary nazw użytkowników/haseł.

    Uwaga

    Jeśli przed komunikacją z usługą należy przejść przez wiele usług tokenów zabezpieczających, usługa pośredniego tokenu zabezpieczającego może skierować klienta do nieprawidłowej usługi tokenu zabezpieczającego. W związku z tym upewnij się, że punkt końcowy usługi tokenu zabezpieczającego w wystawionej <aplikacjiTokenParameters> jest oczekiwaną usługą tokenu zabezpieczającego, a nie nieznaną usługą tokenu zabezpieczającego.

Aby skonfigurować element IssuedTokenClientCredential w kodzie

  1. IssuedTokenClientCredential Uzyskaj dostęp do właściwości IssuedToken ClientCredentials klasy (zwracanej przez ClientCredentials właściwość ClientBase<TChannel> klasy lub za pośrednictwem klasy), jak pokazano w poniższym przykładowym ChannelFactory kodzie.

    IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;

    Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken

  2. Jeśli buforowanie tokenów nie jest wymagane, ustaw CacheIssuedTokens właściwość na false. Właściwość CacheIssuedTokens określa, czy takie tokeny z usługi tokenu zabezpieczającego są buforowane. Jeśli ta właściwość jest ustawiona na false, klient żąda nowego tokenu z usługi tokenu zabezpieczającego zawsze, gdy musi ponownie uwierzytelnić się w usłudze federacyjnej, niezależnie od tego, czy poprzedni token jest nadal prawidłowy. Jeśli ta właściwość jest ustawiona na true, klient ponownie używa istniejącego tokenu zawsze, gdy musi ponownie uwierzytelnić się w usłudze federacyjnej (o ile token nie wygasł). Wartość domyślna to true.

  3. Jeśli dla tokenów buforowanych jest wymagany limit czasu, ustaw MaxIssuedTokenCachingTime właściwość na TimeSpan wartość. Właściwość określa, jak długo można buforować token. Po upływie określonego przedziału czasu token zostanie usunięty z pamięci podręcznej klienta. Domyślnie tokeny są buforowane na czas nieokreślony. W poniższym przykładzie ustawiono przedział czasu na 10 minut.

    itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);

    itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)

  4. Opcjonalny. IssuedTokenRenewalThresholdPercentage Ustaw wartość procentową. Wartość domyślna to 60 (procent). Właściwość określa procent okresu ważności tokenu. Jeśli na przykład wystawiony token jest ważny przez 10 godzin i IssuedTokenRenewalThresholdPercentage jest ustawiony na 80, token zostanie odnowiony po ośmiu godzinach. Poniższy przykład ustawia wartość na 80 procent.

    itcc.IssuedTokenRenewalThresholdPercentage = 80;

    itcc.IssuedTokenRenewalThresholdPercentage = 80

    Interwał odnawiania określony przez okres ważności tokenu i IssuedTokenRenewalThresholdPercentage wartość jest zastępowana przez MaxIssuedTokenCachingTime wartość w przypadkach, gdy czas buforowania jest krótszy niż czas progu odnowienia. Jeśli na przykład produkt IssuedTokenRenewalThresholdPercentage i czas trwania tokenu wynosi osiem godzin, a MaxIssuedTokenCachingTime wartość to 10 minut, klient kontaktuje się z usługą tokenu zabezpieczającego dla zaktualizowanego tokenu co 10 minut.

  5. Jeśli tryb entropii klucza inny niż CombinedEntropy jest wymagany w powiązaniu, które nie używa zabezpieczeń komunikatów ani zabezpieczeń transportu z poświadczeniami komunikatu (na przykład powiązanie nie ma SecurityBindingElement), ustaw DefaultKeyEntropyMode właściwość na odpowiednią wartość. Tryb entropii określa, czy klucze symetryczne mogą być kontrolowane za pomocą DefaultKeyEntropyMode właściwości . Ta wartość domyślna to CombinedEntropy, gdzie zarówno klient, jak i wystawca tokenu dostarczają dane połączone w celu wygenerowania rzeczywistego klucza. Inne wartości to ClientEntropy i ServerEntropy, co oznacza, że cały klucz jest określany odpowiednio przez klienta lub serwer. Poniższy przykład ustawia właściwość tak, aby używała tylko danych serwera dla klucza.

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

    Uwaga

    Jeśli element SecurityBindingElement znajduje się w usłudze tokenu zabezpieczającego lub powiązaniu usługi, DefaultKeyEntropyMode ustawienie włączone IssuedTokenClientCredential jest zastępowane przez KeyEntropyMode właściwość SecurityBindingElement.

  6. Skonfiguruj wszelkie zachowania punktów końcowych specyficznych dla wystawcy, dodając je do kolekcji zwróconej IssuerChannelBehaviors przez właściwość .

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)

Aby skonfigurować element IssuedTokenClientCredential w konfiguracji

  1. <Utwórz element issuedToken> jako element podrzędny <elementu issuedToken> w zachowaniu punktu końcowego.

  2. Jeśli buforowanie tokenów nie jest wymagane, ustaw cacheIssuedTokens atrybut (elementu <issuedToken> ) na falsewartość .

  3. Jeśli dla buforowanych tokenów jest wymagany limit czasu, ustaw maxIssuedTokenCachingTime atrybut elementu <issuedToken> na odpowiednią wartość. Na przykład: <issuedToken maxIssuedTokenCachingTime='00:10:00' />.

  4. Jeśli preferowana jest wartość inna niż domyślna, ustaw issuedTokenRenewalThresholdPercentage atrybut elementu <issuedToken> na odpowiednią wartość, na przykład:

    <issuedToken issuedTokenRenewalThresholdPercentage = "80" />

  5. Jeśli tryb entropii klucza inny niż CombinedEntropy w powiązaniu, które nie korzysta z zabezpieczeń komunikatów lub zabezpieczeń transportu z poświadczeniami komunikatu (na przykład powiązanie nie ma SecurityBindingElement), ustaw defaultKeyEntropyMode atrybut elementu na <issuedToken> ServerEntropy wartość lub ClientEntropy zgodnie z potrzebami.

    <issuedToken defaultKeyEntropyMode = "ServerEntropy" />

  6. Opcjonalny. Skonfiguruj zachowanie niestandardowego punktu końcowego specyficznego dla wystawcy, tworząc <issuerChannelBehaviors> element jako element podrzędny <issuedToken> elementu. Dla każdego zachowania utwórz <add> element jako element podrzędny <issuerChannelBehaviors> elementu. Określ adres wystawcy zachowania, ustawiając issuerAddress atrybut w elemencie <add> . Określ zachowanie, ustawiając behaviorConfiguration atrybut na elemecie <add> .

    <issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>

Aby skonfigurować element X509CertificateRecipientClientCredential w kodzie

  1. X509CertificateRecipientClientCredential Dostęp do właściwości ServiceCertificate ClientCredentials właściwości ClientBase<TChannel> klasy lub ChannelFactory właściwości.

    X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

    Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

  2. X509Certificate2 Jeśli wystąpienie jest dostępne dla certyfikatu dla danego punktu końcowego, użyj Add metody kolekcji zwróconej ScopedCertificates przez właściwość .

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

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

  3. X509Certificate2 Jeśli wystąpienie jest niedostępne, użyj SetScopedCertificate metody X509CertificateRecipientClientCredential klasy, jak pokazano w poniższym przykładzie.

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

Aby skonfigurować element X509CertificateRecipientClientCredential w konfiguracji

  1. Utwórz element scopedCertificates> jako element podrzędny <elementu serviceCertificate>, który jest samym elementem podrzędnym< elementu clientCredentials> w zachowaniu punktu końcowego.<

  2. <add> Utwórz element jako element podrzędny <scopedCertificates> elementu. Określ wartości atrybutów storeLocation, , x509FindTypestoreNameifindValue, aby odwoływać się do odpowiedniego certyfikatu. targetUri Ustaw atrybut na wartość, która udostępnia adres punktu końcowego, dla którego ma być używany certyfikat, jak pokazano w poniższym przykładzie.

    <scopedCertificates>
 <add targetUri="http://fabrikam.com/sts"
      storeLocation="CurrentUser"
      storeName="TrustedPeople"
      x509FindType="FindBySubjectName"
      findValue="FabrikamSTS" />
</scopedCertificates>

Przykład

Poniższy przykładowy kod konfiguruje wystąpienie IssuedTokenClientCredential klasy w kodzie.

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

Zabezpieczenia.NET Framework

Aby zapobiec możliwemu ujawnieniu informacji, klienci, którzy uruchamiają narzędzie Svcutil.exe do przetwarzania metadanych z federacyjnych punktów końcowych, powinni upewnić się, że wynikowe adresy usługi tokenu zabezpieczającego są oczekiwane. Jest to szczególnie ważne, gdy usługa tokenu zabezpieczającego uwidacznia wiele punktów końcowych, ponieważ narzędzie Svcutil.exe generuje wynikowy plik konfiguracji do użycia pierwszego takiego punktu końcowego, który może nie być tym, którego klient powinien używać.

Wymagane ustawienia lokalne

Jeśli klienci mają zawsze używać lokalnego wystawcy, należy pamiętać o następujących kwestiach: domyślne dane wyjściowe Svcutil.exe powodują, że lokalny wystawca nie jest używany, jeśli usługa tokenu zabezpieczającego drugiego do ostatniego w łańcuchu określa adres wystawcy lub adres metadanych wystawcy.

Aby uzyskać więcej informacji na temat ustawiania LocalIssuerAddresswłaściwości IssuedTokenClientCredential klasy , LocalIssuerBindingiLocalIssuerChannelBehaviors, zobacz How to: Configure a Local Issuer (Jak skonfigurować wystawcę lokalnego).

Certyfikaty o określonym zakresie

Jeśli certyfikaty usługi muszą być określone do komunikowania się z dowolną usługą tokenu zabezpieczającego, zazwyczaj dlatego, że nie są używane negocjacje certyfikatów, można je określić przy użyciu ScopedCertificates właściwości X509CertificateRecipientClientCredential klasy. Metoda SetDefaultCertificate przyjmuje Uri parametr i X509Certificate2 jako parametry. Określony certyfikat jest używany podczas komunikacji z punktami końcowymi w określonym identyfikatorze URI. Alternatywnie możesz użyć SetScopedCertificate metody , aby dodać certyfikat do kolekcji zwróconej ScopedCertificates przez właściwość .

Uwaga

Idea klienta certyfikatów, które są ograniczone do danego identyfikatora URI, ma zastosowanie tylko do aplikacji wykonujących wywołania wychodzące do usług, które uwidaczniają punkty końcowe w tych identyfikatorach URI. Nie dotyczy certyfikatów używanych do podpisywania wystawionych tokenów, takich jak te skonfigurowane na serwerze w kolekcji zwróconej przez KnownCertificates klasę IssuedTokenServiceCredential . Aby uzyskać więcej informacji, zobacz How to: Configure Credentials on a Federation Service (Instrukcje: konfigurowanie poświadczeń w usłudze federacyjnej).

Zobacz też