HOW TO：建立聯合用戶端

發行項
02/28/2011

在 Windows Communication Foundation (WCF) 中，建立「聯合服務」(Federated Service) 用戶端時主要包含下列三個步驟：

設定 wsFederationHttpBinding element或相似的自訂繫結。如需詳細資訊建立適當繫結的詳細資訊，請參閱 HOW TO：建立 WSFederationHttpBinding。或者，針對聯合服務的中繼資料端點執行 ServiceModel 中繼資料公用程式工具 (Svcutil.exe)，並產生組態檔以便與聯合服務和一或多個安全性權杖服務通訊。
針對可控制用戶端與安全性權杖服務之間各種互動方式的 IssuedTokenClientCredential 設定其屬性。
設定 X509CertificateRecipientClientCredential 的屬性，以提供與特定端點 (例如，安全性權杖服務) 安全通訊所需的憑證。

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

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

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

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

將服務的中繼資料 URL 位址當成命令列參數來執行 ServiceModel 中繼資料公用程式工具 (Svcutil.exe)。
透過適當的編輯器開啟產生的組態檔。
針對任何產生的 <issuer> 和 <issuerMetadata> 項目檢查其屬性與內容。這些都是位於 <wsFederationHttpBinding> 或自訂繫結項目的 <security> 項目中。請確定位址包含預期的網域名稱或其他位址資訊。請務必檢查這項資訊，因為用戶端會對這些位址進行驗證，而且可能揭露使用者名稱/密碼組這類的資訊。如果位址不是預期的位址，可能會導致向不適當的收件者揭露資訊。

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

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

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

若要透過程式碼設定 IssuedTokenClientCredential

如下列範例程式碼所示，透過 ClientCredentials 類別的 IssuedToken 屬性，存取 IssuedTokenClientCredential (由 ClientBase 類別的 ClientCredentials 屬性傳回，或是透過 ChannelFactory 類別)。
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
如果不需要權杖快取，請將 CacheIssuedTokens 屬性設為 false。CacheIssuedTokens 屬性控制是否快取來自安全性權杖服務的這類權杖。如果此屬性設為 false，每當用戶端必須向聯合服務重新驗證自己時，不管前一個權杖是否仍舊有效，都會向安全性權杖服務要求新的權杖。如果此屬性設為 true，每當用戶端必須向聯合服務重新驗證自己時，只要權杖尚未到期，用戶端都會重複使用現有的權杖。預設為 true。
如果必須在快取的權杖上設定時間限制，請將 MaxIssuedTokenCachingTime 屬性設為 TimeSpan 值。此屬性會指定多久快取權杖一次。一旦經過了指定的時間範圍，就會從用戶端快取中移除權杖。根據預設，權杖無快取時間限制。下列範例會將時間範圍設為 10 分鐘。
```
itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
```
```
itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
```
選擇項，將 IssuedTokenRenewalThresholdPercentage 設為百分比。預設為 60%。此屬性會指定權杖的有效期間百分比。例如，如果發行權杖有效時間是 10 小時，而 IssuedTokenRenewalThresholdPercentage 設為 80，則權杖會在 8 小時後更新。下例範例會將值設為 80%。
```
itcc.IssuedTokenRenewalThresholdPercentage = 80
```
```
itcc.IssuedTokenRenewalThresholdPercentage = 80;
```
當快取時間比更新閾值時間還短時，由權杖有效期間與 IssuedTokenRenewalThresholdPercentage 值決定的更新間隔會被 MaxIssuedTokenCachingTime 值覆寫。例如，如果 IssuedTokenRenewalThresholdPercentage 和權杖有效期間的乘積是 8 小時，而 MaxIssuedTokenCachingTime 值為 10 分鐘，則用戶端會每 10 分鐘連絡一次安全性權杖服務以取得更新的權杖。

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

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

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

設定任何特定發行者的端點行為時，請將它們新增至 IssuerChannelBehaviors 屬性所傳回的集合中。
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
```
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
```

若要透過組態設定 IssuedTokenClientCredential

在端點行為中建立 <issuedToken> 項目，以做為 <clientCredentials> 項目的子系。
如果不需要權杖快取，請將 <issuedToken> 項目的 cacheIssuedTokens 屬性設為 false。
如果必須在快取的權杖上設定時間限制，請將 <issuedToken> 項目上的 maxIssuedTokenCachingTime 屬性設為適當值。例如：
<issuedToken maxIssuedTokenCachingTime='00:10:00' />
如果不是採用預設值，請將 <issuedToken> 項目上的 issuedTokenRenewalThresholdPercentage 屬性設為適當值，例如：
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />
```
如果不使用訊息安全性或傳輸安全性來搭配訊息認證的繫結需要的是 CombinedEntropy 以外的金鑰 Entropy 模式 (例如，繫結不包含 SecurityBindingElement)，請視需要將 <issuedToken> 項目上的 defaultKeyEntropyMode 屬性設為 ServerEntropy 或 ClientEntropy。
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />
```
選擇項，建立 <issuerChannelBehaviors> 項目做為 <issuedToken> 項目的子系，以設定任何特定發行者的自訂端點行為。對於每項行為，建立 <add> 項目以做為 <issuerChannelBehaviors> 項目的子系。設定 <add> 項目上的 issuerAddress 屬性，以指定行為的發行者位址。設定 <add> 項目上的 behaviorConfiguration 屬性，以指定行為本身。
```
<issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>
```

若要透過程式碼設定 X509CertificateRecipientClientCredential

透過屬於 ClientBase 類別或 ChannelFactory 屬性的 ClientCredentials 屬性之 ServiceCertificate 屬性，存取 X509CertificateRecipientClientCredential。

Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

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

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

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

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

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

若要透過組態設定 X509CertificateRecipientClientCredential

建立 <scopedCertificates> 項目做為 <serviceCertifcate> 項目的子系，該項目本身則是端點行為中 <clientCredentials> 項目的子系。
建立 <add> 項目以做為 <scopedCertificates> 項目的子項。指定 storeLocation、storeName、x509FindType 和 findValue 的屬性值以參照到適當的憑證。將 targetUri 的屬性值設為將使用該憑證之端點的位址，如下列範例所示。
```
<scopedCertificates>
 <add targetUri="https://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("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;
}

安全性

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

需要 LocalIssuer

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

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

範圍憑證

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

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

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

另請參閱

工作

聯合範例
 HOW TO：在 WSFederationHttpBinding 上停用安全工作階段
 HOW TO：建立 WSFederationHttpBinding
HOW TO：設定聯合服務的認證
 HOW TO：設定本機簽發者
 How to: Secure Metadata Endpoints

概念

Security Considerations with Metadata

共用方式為