トークン プロバイダーToken Provider

このサンプルでは、カスタム トークン プロバイダーを実装する方法を示します。This sample demonstrates how to implement a custom token provider. Windows Communication Foundation (WCF) のトークンプロバイダーは、セキュリティインフラストラクチャに資格情報を提供するために使用されます。A token provider in Windows Communication Foundation (WCF) is used for supplying credentials to the security infrastructure. 一般的に、トークン プロバイダーは、ターゲットをチェックし、適切な証明書を発行して、セキュリティ インフラストラクチャがメッセージのセキュリティを保護できるようにします。The token provider in general examines the target and issues appropriate credentials so that the security infrastructure can secure the message. WCF には、既定の資格情報マネージャートークンプロバイダーが付属しています。WCF ships with the default Credential Manager Token Provider. また、WCF には、CardSpace トークンプロバイダーも付属しています。WCF also ships with a CardSpace token provider. カスタム トークン プロバイダーは、次の場合に便利です。Custom token providers are useful in the following cases:

  • トークン プロバイダーが連携動作できない資格情報ストアがある場合。If you have a credential store that these token providers cannot operate with.

  • ユーザーが資格情報を使用するときに、ユーザーが詳細情報を提供した時点から資格情報を変換するための独自のカスタムメカニズムを提供する場合。If you want to provide your own custom mechanism for transforming the credentials from the point when the user provides the details to when the WCF client framework uses the credentials.

  • カスタム トークンを構築している場合。If you are building a custom token.

このサンプルでは、ユーザーの入力を別の形式に変換するカスタム トークン プロバイダーを構築する方法を示します。This sample shows how to build a custom token provider that transforms the input from the user into a different format.

このサンプルに示されている手順の概要は次のとおりです。To summarize, this sample demonstrates the following:

  • クライアントがユーザー名/パスワードの組み合わせを使用して認証する方法。How a client can authenticate using a username/password pair.

  • クライアントをカスタム トークン プロバイダーを使用して構成する手順。How a client can be configured with a custom token provider.

  • サーバーが、ユーザー名とパスワードが一致していることを検証するカスタム UserNamePasswordValidator とパスワードを使用して、クライアント資格情報を検証する手順。How the server can validate the client credentials using a password with a custom UserNamePasswordValidator that validates that the username and password match.

  • サーバーがクライアントによってサーバーの X.509 証明書を使用して認証される手順。How the server is authenticated by the client using the server's X.509 certificate.

さらにこのサンプルでは、カスタム トークン認証システムの処理後に、呼び出し元の ID にアクセスするための方法も示します。This sample also shows how the caller's identity is accessible after the custom token authentication process.

サービスは、そのサービスとの通信に使用する単一エンドポイントを公開します。エンドポイントは App.config 構成ファイルで定義します。The service exposes a single endpoint for communicating with the service, defined using the App.config configuration file. エンドポイントは、アドレス、バインディング、およびコントラクトがそれぞれ 1 つずつで構成されます。The endpoint consists of an address, a binding, and a contract. バインディングの構成には、標準の wsHttpBinding が使用されます。これは既定でメッセージ セキュリティを使用します。The binding is configured with a standard wsHttpBinding, which uses message security by default. このサンプルは、クライアント ユーザー名認証を使用するように標準の wsHttpBindingを設定します。This sample sets the standard wsHttpBinding to use client username authentication. また、サービスは serviceCredentials 動作を使用してサービス証明書の構成も行います。The service also configures the service certificate using the serviceCredentials behavior. serviceCredentials 動作を使用すると、サービス証明書を構成できます。The serviceCredentials behavior allows you to configure a service certificate. クライアントはサービス証明書を使用して、サービスを認証し、メッセージを保護します。A service certificate is used by a client to authenticate the service and provide message protection. 次の構成では、次のセットアップ手順で説明しているサンプル セットアップでインストールされる localhost 証明書を参照しています。The following configuration references the localhost certificate installed during the sample setup as described in the following setup instructions.

<system.serviceModel>
    <services>
      <service
          name="Microsoft.ServiceModel.Samples.CalculatorService"
          behaviorConfiguration="CalculatorServiceBehavior">
        <host>
          <baseAddresses>
            <!-- configure base address provided by host -->
            <add baseAddress ="http://localhost:8000/servicemodelsamples/service"/>
          </baseAddresses>
        </host>
        <!-- use base address provided by host -->
        <endpoint address=""
                  binding="wsHttpBinding"
                  bindingConfiguration="Binding1"
                  contract="Microsoft.ServiceModel.Samples.ICalculator" />
      </service>
    </services>

    <bindings>
      <wsHttpBinding>
        <binding name="Binding1">
          <security mode="Message">
            <message clientCredentialType="UserName" />
          </security>
        </binding>
      </wsHttpBinding>
    </bindings>

    <behaviors>
      <serviceBehaviors>
        <behavior name="CalculatorServiceBehavior">
          <serviceDebug includeExceptionDetailInFaults="False" />
          <!--
        The serviceCredentials behavior allows one to define a service certificate.
        A service certificate is used by a client to authenticate the service and provide message protection.
        This configuration references the "localhost" certificate installed during the setup instructions.
        -->
          <serviceCredentials>
            <serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName" />
          </serviceCredentials>
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>

クライアント エンドポイント構成は、構成名、サービス エンドポイントの絶対アドレス、バインディング、およびコントラクトで構成されます。The client endpoint configuration consists of a configuration name, an absolute address for the service endpoint, the binding, and the contract. クライアント バインディングは、適切な Mode およびメッセージ clientCredentialType で構成されます。The client binding is configured with the appropriate Mode and message clientCredentialType.

<system.serviceModel>
  <client>
    <endpoint name=""
              address="http://localhost:8000/servicemodelsamples/service"
              binding="wsHttpBinding"
              bindingConfiguration="Binding1"
              contract="Microsoft.ServiceModel.Samples.ICalculator">
    </endpoint>
  </client>

  <bindings>
    <wsHttpBinding>
      <binding name="Binding1">
        <security mode="Message">
          <message clientCredentialType="UserName" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>
</system.serviceModel>

次の手順は、カスタムトークンプロバイダーを開発し、それを WCF セキュリティフレームワークと統合する方法を示しています。The following steps show how to develop a custom token provider and integrate it with the WCF security framework:

  1. カスタム トークン プロバイダーを作成します。Write a custom token provider.

    サンプルでは、ユーザー名とパスワードを取得するカスタム トークン プロバイダーを実装します。The sample implements a custom token provider that obtains the username and password. パスワードは、このユーザー名と一致する必要があります。The password must match this username. このカスタム トークン プロバイダーは、デモンストレーション用にのみ作成されたものです。実環境に展開することは推奨されません。This custom token provider is for demonstration purposes only and is not recommended for real world deployment.

    このタスクを実行するため、カスタム トークン プロバイダーは SecurityTokenProvider クラスを派生し、GetTokenCore(TimeSpan) メソッドをオーバーライドします。To perform this task, the custom token provider derives the SecurityTokenProvider class and overrides the GetTokenCore(TimeSpan) method. このメソッドは、新しい UserNameSecurityToken を作成して返します。This method creates and returns a new UserNameSecurityToken.

    protected override SecurityToken GetTokenCore(TimeSpan timeout)
    {
        // obtain username and password from the user using console window
        string username = GetUserName();
        string password = GetPassword();
        Console.WriteLine("username: {0}", username);
    
        // return new UserNameSecurityToken containing information obtained from user
        return new UserNameSecurityToken(username, password);
    }
    
  2. カスタム セキュリティ トークン マネージャーを作成します。Write custom security token manager.

    SecurityTokenManager は、特定の SecurityTokenProvider (SecurityTokenRequirement メソッドで渡されます) に対する CreateSecurityTokenProvider を作成するために使用されます。The SecurityTokenManager is used to create SecurityTokenProvider for specific SecurityTokenRequirement that is passed to it in CreateSecurityTokenProvider method. セキュリティ トークン マネージャーは、トークン認証システムとトークン シリアライザーの作成にも使用されますが、このサンプルでは扱っていません。Security token manager is also used to create token authenticators and a token serializer, but those are not covered by this sample. このサンプルでは、カスタム セキュリティ トークン マネージャーは ClientCredentialsSecurityTokenManager クラスを継承し、渡されたトークンの要件でユーザー名プロバイダーが必要であることが示されている場合に、CreateSecurityTokenProvider メソッドをオーバーライドして、カスタムのユーザー名トークン プロバイダーを返します。In this sample, the custom security token manager inherits from ClientCredentialsSecurityTokenManager class and overrides the CreateSecurityTokenProvider method to return custom username token provider when the passed token requirements indicate that username provider is requested.

    public class MyUserNameSecurityTokenManager : ClientCredentialsSecurityTokenManager
    {
        MyUserNameClientCredentials myUserNameClientCredentials;
    
        public MyUserNameSecurityTokenManager(MyUserNameClientCredentials myUserNameClientCredentials)
            : base(myUserNameClientCredentials)
        {
            this.myUserNameClientCredentials = myUserNameClientCredentials;
        }
    
        public override SecurityTokenProvider CreateSecurityTokenProvider(SecurityTokenRequirement tokenRequirement)
        {
            // if token requirement matches username token return custom username token provider
            // otherwise use base implementation
            if (tokenRequirement.TokenType == SecurityTokenTypes.UserName)
            {
                return new MyUserNameTokenProvider();
            }
            else
            {
                return base.CreateSecurityTokenProvider(tokenRequirement);
            }
        }
    }
    
  3. カスタム クライアント資格情報を作成します。Write a custom client credential.

    クライアント資格情報クラスは、クライアント プロキシ用に構成された資格情報を表すために使用され、トークン認証システム、トークン プロバイダー、およびトークン シリアライザーの取得に使用されるセキュリティ トークン マネージャーを作成します。Client credentials class is used to represent the credentials that are configured for the client proxy and creates security token manager that is used to obtain token authenticators, token providers and a token serializer.

    public class MyUserNameClientCredentials : ClientCredentials
    {
        public MyUserNameClientCredentials()
            : base()
        {
        }
    
        protected override ClientCredentials CloneCore()
        {
            return new MyUserNameClientCredentials();
        }
    
        public override SecurityTokenManager CreateSecurityTokenManager()
        {
            // return custom security token manager
            return new MyUserNameSecurityTokenManager(this);
        }
    }
    
  4. カスタム クライアント資格情報を使用するようクライアントを構成します。Configure the client to use the custom client credential.

    クライアントがカスタム クライアント資格情報を使用するため、サンプルでは既定のクライアント資格情報を削除し、新しいクライアント資格情報クラスを提供しています。In order for the client to use the custom client credential, the sample deletes the default client credential class and supplies the new client credential class.

    static void Main()
    {
        // ...
           // Create a client with given client endpoint configuration
          CalculatorClient client = new CalculatorClient();
    
          // set new credentials
           client.ChannelFactory.Endpoint.Behaviors.Remove(typeof(ClientCredentials));
         client.ChannelFactory.Endpoint.Behaviors.Add(new MyUserNameClientCredentials());
       // ...
    }
    

サービス側で呼び出し元の情報を表示するには、次のコード例に示すように PrimaryIdentity を使用します。On the service, to display the caller's information, use the PrimaryIdentity as shown in the following code example. Current には、現在のユーザーに関する情報が保持されています。The Current contains claims information about the current caller.

static void DisplayIdentityInformation()
{
    Console.WriteLine("\t\tSecurity context identity  :  {0}",
        ServiceSecurityContext.Current.PrimaryIdentity.Name);
}

このサンプルを実行すると、操作要求および応答がクライアントのコンソール ウィンドウに表示されます。When you run the sample, the operation requests and responses are displayed in the client console window. クライアントをシャットダウンするには、クライアント ウィンドウで Enter キーを押します。Press ENTER in the client window to shut down the client.

セットアップ バッチ ファイルSetup Batch File

このサンプルに用意されている Setup.bat バッチ ファイルを使用すると、適切な証明書を使用してサーバーを構成し、サーバー証明書ベースのセキュリティを必要とする自己ホスト型アプリケーションを実行できるようになります。The Setup.bat batch file included with this sample allows you to configure the server with the relevant certificate to run a self-hosted application that requires server certificate-based security. このバッチ ファイルは、複数のコンピューターを使用する場合またはホストなしの場合に応じて変更する必要があります。This batch file must be modified to work across computers or to work in a non-hosted case.

次に、バッチ ファイルのセクションのうち、該当する構成で実行するために変更が必要となる部分を示します。The following provides a brief overview of the different sections of the batch files so that they can be modified to run in the appropriate configuration:

  • サーバー証明書の作成。Creating the server certificate.

    Setup.bat バッチ ファイルの次の行は、使用するサーバー証明書を作成します。The following lines from the Setup.bat batch file create the server certificate to be used. %SERVER_NAME% 変数はサーバー名です。The %SERVER_NAME% variable specifies the server name. この変数を変更して、使用するサーバー名を指定します。Change this variable to specify your own server name. このバッチ ファイルでの既定値は localhost です。The default value in this batch file is localhost.

    echo ************
    echo Server cert setup starting
    echo %SERVER_NAME%
    echo ************
    echo making server cert
    echo ************
    makecert.exe -sr LocalMachine -ss MY -a sha1 -n CN=%SERVER_NAME% -sky exchange -pe
    
  • クライアントの信頼された証明書ストアへのサーバー証明書のインストール。Installing the server certificate into the client's trusted certificate store:

    Setup.bat バッチ ファイルの次の行は、サーバー証明書をクライアントの信頼されたユーザーのストアにコピーします。The following lines in the Setup.bat batch file copy the server certificate into the client trusted people store. この手順が必要なのは、Makecert.exe によって生成される証明書がクライアント システムにより暗黙には信頼されないからです。This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. マイクロソフト発行の証明書など、クライアントの信頼されたルート証明書に基づいた証明書が既にある場合は、クライアント証明書ストアにサーバー証明書を配置するこの手順は不要です。If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft issued certificate—this step of populating the client certificate store with the server certificate is not required.

    certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople
    

注意

Setup.bat バッチ ファイルは、Windows SDK コマンド プロンプトから実行します。The Setup.bat batch file is designed to be run from a Windows SDK Command Prompt. MSSDK 環境変数が SDK のインストール ディレクトリを指している必要があります。It requires that the MSSDK environment variable point to the directory where the SDK is installed. この環境変数は、Windows SDK コマンド プロンプトで自動設定されます。This environment variable is automatically set within a Windows SDK Command Prompt.

サンプルをセットアップしてビルドするにはTo set up and build the sample

  1. Windows Communication Foundation サンプルの1回限りのセットアップ手順を実行したことを確認します。Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

  2. ソリューションをビルドするには、「 Windows Communication Foundation サンプルのビルド」の手順に従います。To build the solution, follow the instructions in Building the Windows Communication Foundation Samples.

サンプルを同じコンピューターで実行するにはTo run the sample on the same computer

  1. 管理者特権で Visual Studio 2012 コマンドプロンプトを開き、サンプルのインストールフォルダーから Setup.bat を実行します。Run Setup.bat from the sample installation folder inside a Visual Studio 2012 command prompt opened with administrator privileges. これにより、サンプルの実行に必要なすべての証明書がインストールされます。This installs all the certificates required for running the sample.

    注意

    Setup.bat バッチファイルは、Visual Studio 2012 のコマンドプロンプトから実行するように設計されています。The Setup.bat batch file is designed to be run from a Visual Studio 2012 Command Prompt. Visual Studio 2012 のコマンドプロンプト内で設定された PATH 環境変数は、Setup.bat スクリプトで必要な実行可能ファイルを含むディレクトリを指します。The PATH environment variable set within the Visual Studio 2012 Command Prompt points to the directory that contains executables required by the Setup.bat script.

  2. service.exe を \service\bin で起動します。Launch service.exe from service\bin.

  3. Client.exe を \client\bin で起動します。Launch Client.exe from \client\bin. クライアント アクティビティがクライアントのコンソール アプリケーションに表示されます。Client activity is displayed on the client console application.

  4. username プロンプトに対してユーザー名を入力します。At the username prompt, type a user name.

  5. password プロンプトに対して、username プロンプトで入力したものと同じ文字列を入力します。At the password prompt, use the same string that was typed for the username prompt.

  6. クライアントとサービスが通信できない場合は、「 WCF サンプルのトラブルシューティングのヒント」を参照してください。If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

サンプルを複数のコンピューターで実行するにはTo run the sample across computers

  1. サービス コンピューターにサービス バイナリ用のディレクトリを作成します。Create a directory on the service computer for the service binaries.

  2. サービス プログラム ファイルを、サービス コンピューターのサービス ディレクトリにコピーします。Copy the service program files to the service directory on the service computer. Setup.bat ファイルと Cleanup.bat ファイルもサービス コンピューターにコピーします。Also copy the Setup.bat and Cleanup.bat files to the service computer.

  3. コンピューターの完全修飾ドメイン名を含むサブジェクト名を持つサーバー証明書が必要です。You must have a server certificate with the subject name that contains the fully-qualified domain name of the computer. 新しい証明書名を反映するには、Service.exe.config ファイルを更新する必要があります。The Service.exe.config file must be updated to reflect this new certificate name. サーバー証明書を作成するには、Setup.bat バッチ ファイルを変更します。You can create server certificate by modifying the Setup.bat batch file. setup.bat ファイルは、管理者特権で開いた Visual Studio の開発者コマンドプロンプトから実行する必要があることに注意してください。Note that the setup.bat file must be run from a Developer Command Prompt for Visual Studio opened with administrator privileges. %SERVER_NAME% 変数には、サービスをホストするコンピューターの完全修飾ホスト名を設定する必要があります。You must set %SERVER_NAME% variable to fully-qualified host name of the computer that is used to host the service.

  4. サーバー証明書をクライアントの CurrentUser-TrustedPeople ストアにコピーします。Copy the server certificate into the CurrentUser-TrustedPeople store of the client. この操作は、サーバー証明書の発行元をクライアントが信頼できる場合は不要です。You do not need to do this when the server certificate is issued by a client trusted issuer.

  5. サービス コンピューターの Service.exe.config ファイルで、ベース アドレスの値を localhost から完全修飾コンピューター名に変更します。In the Service.exe.config file on the service computer, change the value of the base address to specify a fully-qualified computer name instead of localhost.

  6. サービス コンピューターで、コマンド プロンプトから service.exe を実行します。On the service computer, run service.exe from a command prompt.

  7. クライアント プログラム ファイルを、言語固有のフォルダーにある \client\bin\ フォルダーからクライアント コンピューターにコピーします。Copy the client program files from the \client\bin\ folder, under the language-specific folder, to the client computer.

  8. クライアント コンピューターの Client.exe.config ファイルで、エンドポイントのアドレス値をサービスの新しいアドレスに合わせます。In the Client.exe.config file on the client computer, change the address value of the endpoint to match the new address of your service.

  9. クライアント コンピューターで、コマンド プロンプト ウィンドウから Client.exe を起動します。On the client computer, launch Client.exe from a command prompt window.

  10. クライアントとサービスが通信できない場合は、「 WCF サンプルのトラブルシューティングのヒント」を参照してください。If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

サンプルの実行後にクリーンアップするにはTo clean up after the sample

  1. サンプルの実行が終わったら、サンプル フォルダーにある Cleanup.bat を実行します。Run Cleanup.bat in the samples folder once you have finished running the sample.