HOW TO：建立自訂用戶端與服務認證

  • 發行項

此主題顯示如何實作自訂用戶端和服務認證，以及如何使用來自應用程式碼的自訂認證。

認證擴充性類別

ClientCredentials 和 ServiceCredentials 類別是 Windows Communication Foundation (WCF) 安全性擴充性的主要進入點。這些認證類別提供能夠讓應用程式碼設定認證資訊，以及將認證類型轉換為安全性權杖的 API ((「安全性權杖」(Security Token) 是用來在 SOAP 訊息內部傳輸認證資訊的型式)。這些認證類別的責任可以分為兩部分：

  • 提供 API 讓應用程式設定認證資訊。
  • 執行當做 SecurityTokenManager 實作的處理站。

ClientCredentials 和 ServiceCredentials 類別都繼承自定義傳回 SecurityTokenManager 之合約的抽象 SecurityCredentialsManager 類別。

如需有關認證類別以及其在 WCF 安全性架構中所扮演角色的詳細資訊，請參閱安全性架構。

WCF 中提供的預設實作會支援系統提供的認證類型，並且建立能夠處理那些認證類型的安全性權杖管理員。

自訂原因

有幾項自訂用戶端或服務認證類別的原因。首先是需要變更關於處理系統提供之認證類型的預設 WCF 安全性行為，特別是基於下列原因：

  • 需要變更無法使用其他擴充點的情況。
  • 需要新增新的認證類型。
  • 需要新增新的自訂安全性權杖類型。

此主題描述如何實作自訂用戶端和服務認證，以及如何在應用程式碼使用它們。

第一步

建立自訂認證類別只是第一步，因為自訂認證的原因是要變更關於認證佈建、安全性權杖序列化或驗證的 WCF 行為。本章節中的其他主題描述如何建立自訂序列化程式和驗證器。就這一點而言，建立自訂認證類別是所有步驟的第一個主題。只有在建立自訂認證後才能完成後續動作 (建立自訂序列化程式和驗證器)。建構在此主題上的其他主題包含：

程序

實作自訂用戶端認證

  1. 定義衍生自 ClientCredentials 類別的新類別。

  2. 選擇項，新增新的屬性以提供新認證類型的方法或屬性。如果您不需要新增新的認證類型，請略過這個步驟。下列範例會新增 CreditCardNumber 屬性。

  3. 覆寫 CreateSecurityTokenManager 方法。當使用自訂用戶端認證時，WCF 安全性基礎結構會自動呼叫這個方法。這個方法是負責建立和傳回 SecurityTokenManager 類別實作的執行個體。下列程序描述如何建立這類實作。

  4. 覆寫 CloneCore 方法。

實作自訂用戶端安全性權杖管理員。

  1. 定義衍生自 ClientCredentialsSecurityTokenManager 的新類別。

  2. 選擇項，如果需要建立自訂 SecurityTokenProvider 實作，請覆寫 CreateSecurityTokenProvider 方法。如需有關自訂安全性權杖提供者的詳細資訊，請參閱 HOW TO：建立自訂安全性權杖提供者。

  3. 選擇項，如果需要建立自訂 SecurityTokenAuthenticator 實作，請覆寫 CreateSecurityTokenAuthenticator 方法。如需有關自訂安全性權杖驗證器的詳細資訊，請參閱 HOW TO：建立自訂安全性權杖驗證器。

  4. 選擇項，如果需要建立自訂 SecurityTokenSerializer，請覆寫 CreateSecurityTokenSerializer 方法。如需有關自訂安全性權杖和自訂安全性權杖序列化程式的詳細資訊，請參閱 HOW TO：建立自訂權杖。

使用來自應用程式碼的自訂用戶端認證

  1. 建立已產生之用戶端的執行個體以代表服務介面，或建立 ChannelFactory 的執行個體指向想要通訊的服務。

  2. 從 Behaviors 集合中移除系統提供的用戶端認證行為，您可以透過 Endpoint 屬性存取這個集合。

  3. 建立自訂用戶端認證類別的新執行個體，並將其新增至 Behaviors 集合中，您可以透過 Endpoint 屬性存取這個集合。

前面的程序顯示如何使用來自應用程式碼的用戶端認證。您也可以使用應用程式組態檔設定 WCF 認證。在硬式編碼方面通常偏好使用應用程式組態，因為能夠在不修改原始程式碼、重新編譯和重新部署的情況下修改應用程式參數。

下一個程序描述如何提供自訂認證組態的支援。

建立自訂用戶端認證的組態處理常式

  1. 定義衍生自 ClientCredentialsElement 的新類別。

  2. 選擇項，針對想要透過應用程式組態公開的所有其他組態參數新增屬性。下列範例會新增一個名為 CreditCardNumber 的屬性。

  3. 覆寫 BehaviorType 屬性以傳回使用組態項目建立之自訂用戶端認證類別的型別。

  4. 覆寫 CreateBehavior 方法。這個方法會根據從組態檔載入的設定，負責建立和傳回自訂認證類別的執行個體。請呼叫這個方法的基底 ApplyConfiguration 方法，擷取已載入自訂用戶端認證執行個體之系統提供的認證設定。

  5. 選擇項，如果您在步驟 2 新增其他屬性，就需要覆寫 Properties 屬性以登錄組態架構的其他組態設定，才能加以辨認。結合屬性與基底類別屬性，以便透過這個自訂用戶端認證組態項目設定系統提供的設定。

在擁有組態處理常式類別後，就能夠整合至 WCF 組態架構。就能夠在用戶端端點行為項目中使用自訂用戶端認證，如同下一個程序中所示。

在應用程式組態中登錄和使用自訂用戶端認證組態處理常式

  1. 將 <extensions> 項目和 <behaviorExtensions> 項目新增至組態檔。

  2. 將 <add> 項目新增至 <behaviorExtensions> 項目，然後將 name 屬性設定為適當的值。

  3. 將 type 屬性設定為完整型別名稱。同時包含組件名稱和其他組件屬性。

    <system.serviceModel>
  <extensions>
    <behaviorExtensions>
      <add name="myClientCredentials" type="Microsoft.ServiceModel.Samples.MyClientCredentialsConfigHandler, CustomCredentials, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    </behaviorExtensions>
  </extensions>
<system.serviceModel>

  4. 在登錄組態處理常式後，在相同的組態檔中就能夠使用自訂認證項目，而不是系統提供的 <clientCredentials> 項目。您可以同時使用系統提供的屬性，以及新增至組態處理常式實作的任何新屬性。下列程式碼範例會使用 creditCardNumber 屬性 (Attribute) 設定自訂屬性 (Property) 的值。

    <behaviors>
  <endpointBehaviors>
    <behavior name="myClientCredentialsBehavior">
      <myClientCredentials creditCardNumber="123-123-123"/>
    </behavior>
  </endpointBehaviors>
</behaviors>

實作自訂服務認證

  1. 定義衍生自 ServiceCredentials 的新類別。

  2. 選擇項，新增新的屬性以提供已新增之新認證值的 API。如果您不需要新增新的認證值，請略過這個步驟。下列程式碼範例會新增 AdditionalCertificate 屬性。

  3. 覆寫 CreateSecurityTokenManager 方法。當使用自訂用戶端認證時，WCF 基礎結構會自動呼叫這個方法。這個方法是負責建立和傳回 SecurityTokenManager 類別實作的執行個體 (在下一個程序中會描述)。

  4. 選擇項，覆寫 CloneCore 方法。只有在將新屬性或內部欄位新增至自訂用戶端認證實作時才會需要這麼做。

實作自訂服務安全性權杖管理員

  1. 定義衍生自 ServiceCredentialsSecurityTokenManager 類別的新類別。

  2. 選擇項，如果需要建立自訂 SecurityTokenProvider 實作，請覆寫 CreateSecurityTokenProvider 方法。如需有關自訂安全性權杖提供者的詳細資訊，請參閱 HOW TO：建立自訂安全性權杖提供者。

  3. 選擇項，如果需要建立自訂 SecurityTokenAuthenticator 實作，請覆寫 CreateSecurityTokenAuthenticator 方法。如需有關自訂安全性權杖驗證器的詳細資訊，請參閱 HOW TO：建立自訂安全性權杖驗證器 主題。

  4. 選擇項，如果需要建立自訂 SecurityTokenSerializer，請覆寫 CreateSecurityTokenSerializer 方法。如需有關自訂安全性權杖和自訂安全性權杖序列化程式的詳細資訊，請參閱 HOW TO：建立自訂權杖。

使用來自應用程式碼的自訂服務認證

  1. 建立 ServiceHost 的執行個體。

  2. 從 Behaviors 集合移除系統提供的服務認證行為。

  3. 建立自訂服務認證類別的新執行個體，並將其新增至 Behaviors 集合。

使用上面程序「Creating a configuration handler for custom client credentials」和「Registering and using a custom client credentials configuration handler in the application configuration」中描述的步驟新增組態支援。唯一的差別是使用 ServiceCredentialsElement 類別而不是 ClientCredentialsElement 類別，當做組態處理常式的基底類別。然後可以在使用系統提供 <serviceCredentials> 項目的地方使用自訂服務認證項目。

請參閱

工作

HOW TO：建立自訂安全性權杖提供者

參考

ClientCredentials
ServiceCredentials
SecurityCredentialsManager
SecurityTokenManager
ClientCredentialsElement
ServiceCredentialsElement

概念

HOW TO：建立自訂安全性權杖驗證器
HOW TO：建立自訂權杖