共用方式為

作法：建立同盟用戶端

  • 發行項

在 Windows Communication Foundation (WCF) 中建立同盟服務用戶端時，主要包含下列三個步驟：

  1. 設定 <wsFederationHttpBinding> 或類似的自訂繫結。 如需建立適當繫結的詳細資訊，請參閱如何：建立 WSFederationHttpBinding。 或者，針對同盟服務的中繼資料端點執行 ServiceModel 中繼資料公用程式工具 (Svcutil.exe)，並產生設定檔以便與同盟服務和一或多個安全性權杖服務通訊。

  2. 針對可控制用戶端與安全性權杖服務之間各種互動方式的 IssuedTokenClientCredential 設定其屬性。

  3. 設定 X509CertificateRecipientClientCredential 的屬性，以提供與特定端點 (例如，安全性權杖服務) 安全通訊所需的憑證。

注意

當用戶端使用模擬認證、CryptographicException 繫結或自訂發行權杖，以及非對稱金鑰時，可能會擲回 WSFederationHttpBinding。 當 WSFederationHttpBinding 和 IssuedKeyType 屬性分別設為 KeyType 時，非對稱金鑰便能與 AsymmetricKey 繫結或自訂發行權杖一起使用。 當用戶端嘗試傳送訊息，而用戶端想要模擬的身分識別並沒有使用者設定檔時，就會擲回 CryptographicException。 若要減少發生這個問題，請在傳送訊息之前登入用戶端電腦，或是呼叫 LoadUserProfile。

本主題提供這些程序的詳細資訊。 如需建立適當繫結的詳細資訊，請參閱如何：建立 WSFederationHttpBinding。 如需同盟服務運作方式的詳細資訊，請參閱同盟。

若要產生並檢查聯合服務的組態

  1. 將服務的中繼資料 URL 位址當成命令列參數來執行 ServiceModel 中繼資料公用程式工具 (Svcutil.exe)。

  2. 透過適當的編輯器開啟產生的組態檔。

  3. 針對任何產生的 <簽發者> 和 <issuerMetadata> 元素檢查其屬性與內容。 這些位於 <wsFederationHttpBinding> 或自訂繫結項目的 <安全性>元素中。 請確定位址包含預期的網域名稱或其他位址資訊。 請務必檢查這項資訊，因為用戶端會對這些位址進行驗證，而且可能揭露使用者名稱/密碼組這類的資訊。 如果位址不是預期的位址，可能會導致向不適當的收件者揭露資訊。

  4. 請在標記為註解的 <alternativeIssuedTokenParameters> 元素中檢查任何額外的 <issuedTokenParameters> 元素。 使用 Svcutil.exe 工具來產生聯合服務的組態時，如果聯合服務或任何中繼安全性權杖服務未指定發行者位址，而是指定了會公開多個端點之安全性權杖服務的中繼資料位址，則結果組態檔會參照到第一個端點。 其他端點則是設定檔中標記為註解的 <alternativeIssuedTokenParameters> 元素。

    判斷這些 <issuedTokenParameters> 之中是否有比目前設定中更適合的。 例如，用戶端可能會偏好使用 Windows CardSpace 權杖 (而不是使用者名稱/密碼組) 向安全性權杖服務進行驗證。

    注意

    如果與服務進行通訊之前，必須周遊多個安全性權杖服務時，中繼安全性權杖服務可能會將用戶端導向不正確的安全性權杖服務。 因此，請確定 <issuedTokenParameters> 中的安全性權杖服務端點是預期的安全性權杖服務，而非未知的安全性權杖服務。

若要透過程式碼設定 IssuedTokenClientCredential

  1. 如下列範例程式碼所示，透過 IssuedTokenClientCredential 類別的 IssuedToken 屬性，存取 ClientCredentials (由 ClientCredentials 類別的 ClientBase<TChannel> 屬性傳回，或是透過 ChannelFactory 類別)。

    IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;

    Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken

  2. 如果不需要權杖快取，請將 CacheIssuedTokens 屬性設為 false。 CacheIssuedTokens 屬性控制是否快取來自安全性權杖服務的這類權杖。 如果此屬性設為 false，每當用戶端必須向聯合服務重新驗證自己時，不管前一個權杖是否仍舊有效，都會向安全性權杖服務要求新的權杖。 如果此屬性設為 true，每當用戶端必須向聯合服務重新驗證自己時，只要權杖尚未到期，用戶端都會重複使用現有的權杖。 預設值為 true。

  3. 如果必須在快取的權杖上設定時間限制，請將 MaxIssuedTokenCachingTime 屬性設為 TimeSpan 值。 此屬性會指定多久快取權杖一次。 一旦經過了指定的時間範圍，就會從用戶端快取中移除權杖。 根據預設，權杖無快取時間限制。 下列範例會將時間範圍設為 10 分鐘。

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

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

  4. 選擇性。 將 IssuedTokenRenewalThresholdPercentage 設為百分比。 預設為 60%。 此屬性會指定權杖的有效期間百分比。 例如，如果發行權杖有效時間是 10 小時，而 IssuedTokenRenewalThresholdPercentage 設為 80，則權杖會在 8 小時後更新。 下例範例會將值設為 80%。

    itcc.IssuedTokenRenewalThresholdPercentage = 80;

    itcc.IssuedTokenRenewalThresholdPercentage = 80

    當快取時間比更新閾值時間還短時，由權杖有效期間與 IssuedTokenRenewalThresholdPercentage 值決定的更新間隔會被 MaxIssuedTokenCachingTime 值覆寫。 例如，如果 IssuedTokenRenewalThresholdPercentage 和權杖有效期間的乘積是 8 小時，而 MaxIssuedTokenCachingTime 值為 10 分鐘，則用戶端會每 10 分鐘連絡一次安全性權杖服務以取得更新的權杖。

  5. 如果不使用訊息安全性或傳輸安全性來搭配訊息認證的繫結需要的是 CombinedEntropy 以外的金鑰熵模式 (例如，繫結不包含 SecurityBindingElement)，請將 DefaultKeyEntropyMode 屬性設為適當值。 熵模式會決定是否可透過 DefaultKeyEntropyMode 屬性來控制對稱式金鑰。 預設是 CombinedEntropy，其中用戶端與權杖發行者所提供的資料將合併用來產生真正的金鑰。 其他值則是 ClientEntropy 和 ServerEntropy，這兩個值表示整個金鑰將分別由用戶端或伺服器全權決定。 下列範例設定的屬性將會只使用伺服器資料來產生金鑰。

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

    注意

    如果安全性權杖服務或服務繫結中存在 SecurityBindingElement，則 DefaultKeyEntropyMode 上所設定的 IssuedTokenClientCredential 會被 KeyEntropyMode 的 SecurityBindingElement 屬性覆寫。

  6. 設定任何特定發行者的端點行為時，請將它們新增至 IssuerChannelBehaviors 屬性所傳回的集合中。

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)

若要透過組態設定 IssuedTokenClientCredential

  1. 在端點行為中，建立 <issuedToken> 元素做為 <issuedToken> 元素的子項目。

  2. 如果不需要權杖快取，請將 <issuedToken> 元素的 cacheIssuedTokens 屬性設為 false。

  3. 如果必須在快取權杖上設定時間限制，請將 <issuedToken> 元素上的 maxIssuedTokenCachingTime 屬性設為適當值。 例如：
    <issuedToken maxIssuedTokenCachingTime='00:10:00' />

  4. 如果不是採用預設值，請將 <issuedToken> 元素上的 issuedTokenRenewalThresholdPercentage 屬性設為適當值，例如：

    <issuedToken issuedTokenRenewalThresholdPercentage = "80" />

  5. 如果不使用訊息安全性或傳輸安全性來搭配訊息認證的繫結程序需要的是 CombinedEntropy 以外的金鑰 Entropy 模式 (例如，繫結程序不包含 SecurityBindingElement)，請視需要將 defaultKeyEntropyMode 項目上的 <issuedToken> 屬性設為 ServerEntropy 或 ClientEntropy。

    <issuedToken defaultKeyEntropyMode = "ServerEntropy" />

  6. 選擇性。 建立 <issuerChannelBehaviors> 元素做為 <issuedToken> 元素的子項目，以設定任何特定簽發者的自訂端點行為。 針對每個行為，建立 <add> 元素以做為 <issuerChannelBehaviors> 元素的子項目。 設定 <add> 元素上的 issuerAddress 屬性，以指定行為的簽發者位址。 設定 <add> 項目上的 behaviorConfiguration 屬性，以指定行為本身。

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

若要透過程式碼設定 X509CertificateRecipientClientCredential

  1. 透過屬於 X509CertificateRecipientClientCredential 類別或 ServiceCertificate 屬性的 ClientCredentials 屬性之 ClientBase<TChannel> 屬性，存取 ChannelFactory。

    X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

    Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

  2. 如果特定端點憑證可使用 X509Certificate2 執行個體，請使用 Add 屬性所傳回之集合的 ScopedCertificates 方法。

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

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

  3. 如下列範例所示，如果無法使用 X509Certificate2 執行個體，請使用 SetScopedCertificate 類別的 X509CertificateRecipientClientCredential 方法。

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

若要透過組態設定 X509CertificateRecipientClientCredential

  1. 建立 <scopedCertificates> 元素做為 <serviceCertificate> 元素的子項目，該元素本身則是端點行為中 <clientCredentials> 元素的子項目。

  2. 建立 <add> 項目以做為 <scopedCertificates> 項目的子項。 指定 storeLocation、storeName、x509FindType 和 findValue 的屬性值以參照到適當的憑證。 將 targetUri 的屬性值設為將使用該憑證之端點的位址，如下列範例所示。

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

範例

下列程式碼範例會透過程式碼設定 IssuedTokenClientCredential 類別的執行個體。

// 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 安全性

為了避免發生資訊洩露，執行 Svcutil.exe 工具以處理來自聯合端點之中繼資料的用戶端需要確定結果的安全性權杖服務位址是所需要的。 當安全性權杖服務公開多個端點時，這點特別重要，因為 Svcutil.exe 工具會產生結果組態檔以運用第一個此類端點，但是這可能不是用戶端應該使用的端點。

需要 LocalIssuer

如果用戶端預期一律使用本機發行者，請注意下列事項：如果鏈結中倒數第二個安全性權杖服務指定了發行者位址或發行者中繼資料位址，則預設的 Svcutil.exe 輸出將會導致無法使用本機發行者。

如需設定 IssuedTokenClientCredential 類別 LocalIssuerAddress、LocalIssuerBinding 和 LocalIssuerChannelBehaviors 屬性的詳細資訊，請參閱 如何：設定本地簽發者。

範圍憑證

一般來說，如果因為沒有使用憑證交涉而必須指定服務憑證才能與任何一項安全性權杖服務通訊的話，您可以透過 ScopedCertificates 類別的 X509CertificateRecipientClientCredential 屬性來指定服務憑證。 SetDefaultCertificate 方法會採用 Uri 和 X509Certificate2 做為參數。 在指定的 URI 上與端點通訊時，會使用指定的憑證。 或者，您可以使用 SetScopedCertificate 方法，將憑證新增至 ScopedCertificates 屬性所傳回的集合中。

注意

用戶端對於規範到特定 URI 範圍的憑證概念，只會套用到對服務 (可在這些 URI 上公開端點) 執行傳出呼叫的應用程式上。 它無法套用到用來簽署已發行權杖的憑證上，例如在伺服器上由 IssuedTokenServiceCredential 類別的 KnownCertificates 所傳回集合中設定的憑證。 如需詳細資訊，請參閱如何：在同盟服務上設定認證。

另請參閱