トークンのサポート

[アーティクル]
04/07/2023

このトークンのサポートサンプルでは、WS-Security を使用するメッセージに追加トークンを追加する方法を示します。この例では、ユーザー名セキュリティトークンに加え、X.509 バイナリセキュリティトークンを追加します。トークンは、WS-Security メッセージヘッダーでクライアントからサービスに渡されます。そのメッセージの一部は X.509 証明書を所有していることを受信側に証明するため、X.509 セキュリティトークンに関連付けられた秘密キーで署名されます。これは、複数のクレームをメッセージに関連付けて送信側を認証または承認する必要がある場合に便利です。サービスは、要求/応答通信パターンを定義するコントラクトを実装します。

対象

このサンプルでは、次の方法を示します。

クライアントが追加セキュリティトークンをサービスに渡す方法。
サーバーが、追加セキュリティトークンに関連付けられたクレームにアクセスする方法。
サーバーの X.509 証明書を使用して、メッセージの暗号化や署名に使用する対称キーを保護する方法。

Note

このサンプルのセットアップ手順とビルド手順については、このトピックの最後を参照してください。

クライアントによる、ユーザー名トークンと X.509 サポートセキュリティトークンを使用した認証

サービスは、通信に使用する単一エンドポイントを公開します。エンドポイントは、BindingHelper クラスと EchoServiceHost クラスを使用してプログラムによって作成されます。エンドポイントは、アドレス、バインディング、およびコントラクトがそれぞれ 1 つずつで構成されます。バインディングは、SymmetricSecurityBindingElement と HttpTransportBindingElement を使用して、カスタムバインディングとして構成されます。このサンプルでは、SymmetricSecurityBindingElement を設定してサービス X.509 証明書を使用し、送信中の対称キーを保護して、WS-Security メッセージヘッダー内で UserNameToken とサポート X509SecurityToken を渡します。対称キーは、メッセージ本文とユーザー名セキュリティトークンの暗号化に使用されます。サポートトークンは、追加バイナリセキュリティトークンとして WS-Security メッセージヘッダー内で渡されます。サポートトークンの信頼性は、サポート X.509 セキュリティトークンに関連付けられている秘密キーを使用してメッセージに署名することによって証明されます。

public static Binding CreateMultiFactorAuthenticationBinding()
{
    HttpTransportBindingElement httpTransport = new HttpTransportBindingElement();

    // the message security binding element will be configured to require 2 tokens:
    // 1) A username-password encrypted with the service token
    // 2) A client certificate used to sign the message

    // Instantiate a binding element that will require the username/password token in the message (encrypted with the server cert)
    SymmetricSecurityBindingElement messageSecurity = SecurityBindingElement.CreateUserNameForCertificateBindingElement();

    // Create supporting token parameters for the client X509 certificate.
    X509SecurityTokenParameters clientX509SupportingTokenParameters = new X509SecurityTokenParameters();
    // Specify that the supporting token is passed in message send by the client to the service
    clientX509SupportingTokenParameters.InclusionMode = SecurityTokenInclusionMode.AlwaysToRecipient;
    // Turn off derived keys
    clientX509SupportingTokenParameters.RequireDerivedKeys = false;
    // Augment the binding element to require the client's X509 certificate as an endorsing token in the message
    messageSecurity.EndpointSupportingTokenParameters.Endorsing.Add(clientX509SupportingTokenParameters);

    // Create a CustomBinding based on the constructed security binding element.
    return new CustomBinding(messageSecurity, httpTransport);
}

この動作により、クライアント認証に使用されるサービス資格情報と、サービス X.509 証明書に関する情報が指定されます。サンプルでは、サービス X.509 証明書内のサブジェクト名として CN=localhost を使用しています。

override protected void InitializeRuntime()
{
    // Extract the ServiceCredentials behavior or create one.
    ServiceCredentials serviceCredentials =
        this.Description.Behaviors.Find<ServiceCredentials>();
    if (serviceCredentials == null)
    {
        serviceCredentials = new ServiceCredentials();
        this.Description.Behaviors.Add(serviceCredentials);
    }

    // Set the service certificate
    serviceCredentials.ServiceCertificate.SetCertificate(
                                       "CN=localhost");

/*
Setting the CertificateValidationMode to PeerOrChainTrust means that if the certificate is in the Trusted People store, then it will be trusted without performing a validation of the certificate's issuer chain. This setting is used here for convenience so that the sample can be run without having to have certificates issued by a certification authority (CA).
This setting is less secure than the default, ChainTrust. The security implications of this setting should be carefully considered before using PeerOrChainTrust in production code.
*/
    serviceCredentials.ClientCertificate.Authentication.CertificateValidationMode = X509CertificateValidationMode.PeerOrChainTrust;

    // Create the custom binding and add an endpoint to the service.
    Binding multipleTokensBinding =
         BindingHelper.CreateMultiFactorAuthenticationBinding();
    this.AddServiceEndpoint(typeof(IEchoService),
                          multipleTokensBinding, string.Empty);
    base.InitializeRuntime();
}

サービスコード :

[ServiceBehavior(IncludeExceptionDetailInFaults = true)]
public class EchoService : IEchoService
{
    public string Echo()
    {
        string userName;
        string certificateSubjectName;
        GetCallerIdentities(
            OperationContext.Current.ServiceSecurityContext,
            out userName,
            out certificateSubjectName);
            return $"Hello {userName}, {certificateSubjectName}";
    }

    public void Dispose()
    {
    }

    bool TryGetClaimValue<TClaimResource>(ClaimSet claimSet,
            string claimType, out TClaimResource resourceValue)
            where TClaimResource : class
    {
        resourceValue = default(TClaimResource);
        IEnumerable<Claim> matchingClaims =
            claimSet.FindClaims(claimType, Rights.PossessProperty);
        if(matchingClaims == null)
            return false;
        IEnumerator<Claim> enumerator = matchingClaims.GetEnumerator();
        if (enumerator.MoveNext())
        {
            resourceValue =
              (enumerator.Current.Resource == null) ? null :
              (enumerator.Current.Resource as TClaimResource);
            return true;
        }
        else
        {
            return false;
        }
    }

    // Returns the username and certificate subject name provided by
    //the client
    void GetCallerIdentities(ServiceSecurityContext
        callerSecurityContext,
        out string userName, out string certificateSubjectName)
    {
        userName = null;
        certificateSubjectName = null;

       // Look in all the claimsets in the authorization context
       foreach (ClaimSet claimSet in
               callerSecurityContext.AuthorizationContext.ClaimSets)
       {
            if (claimSet is WindowsClaimSet)
            {
                // Try to find a Name claim. This will have been
                // generated from the windows username.
                string tmpName;
                if (TryGetClaimValue<string>(claimSet, ClaimTypes.Name,
                                                      out tmpName))
                {
                    userName = tmpName;
                }
            }
            else if (claimSet is X509CertificateClaimSet)
            {
                // Try to find an X500DistinguishedName claim. This will
                // have been generated from the client certificate.
                X500DistinguishedName tmpDistinguishedName;
                if (TryGetClaimValue<X500DistinguishedName>(claimSet,
                               ClaimTypes.X500DistinguishedName,
                               out tmpDistinguishedName))
                {
                    certificateSubjectName = tmpDistinguishedName.Name;
                }
            }
        }
    }
}

クライアントエンドポイントは、サービスエンドポイントと同様の方法で構成されます。クライアントは、同じ BindingHelper クラスを使用してバインディングを作成します。セットアップの残りの部分は、Client クラスにあります。クライアントはクライアントエンドポイントの動作コレクションに対するセットアップコード内に、ユーザー名セキュリティトークンに関する情報、サポート X.509 セキュリティトークン、およびサービス X.509 証明書に関する情報を設定します。

static void Main()
 {
     // Create the custom binding and an endpoint address for
     // the service.
     Binding multipleTokensBinding =
         BindingHelper.CreateMultiFactorAuthenticationBinding();
         EndpointAddress serviceAddress = new EndpointAddress(
         "http://localhost/servicemodelsamples/service.svc");
       ChannelFactory<IEchoService> channelFactory = null;
       IEchoService client = null;

       Console.WriteLine("Username authentication required.");
       Console.WriteLine(
         "Provide a valid machine or domain account. [domain\\user]");
       Console.WriteLine("   Enter username:");
       string username = Console.ReadLine();
       Console.WriteLine("   Enter password:");
       string password = "";
       ConsoleKeyInfo info = Console.ReadKey(true);
       while (info.Key != ConsoleKey.Enter)
       {
           if (info.Key != ConsoleKey.Backspace)
           {
               if (info.KeyChar != '\0')
               {
                   password += info.KeyChar;
                }
                info = Console.ReadKey(true);
            }
            else if (info.Key == ConsoleKey.Backspace)
            {
                if (password != "")
                {
                    password =
                       password.Substring(0, password.Length - 1);
                }
                info = Console.ReadKey(true);
            }
         }
         for (int i = 0; i < password.Length; i++)
            Console.Write("*");
         Console.WriteLine();
         try
         {
           // Create a proxy with the previously create binding and
           // endpoint address
              channelFactory =
                 new ChannelFactory<IEchoService>(
                     multipleTokensBinding, serviceAddress);
           // configure the username credentials, the client
           // certificate and the server certificate on the channel
           // factory
           channelFactory.Credentials.UserName.UserName = username;
           channelFactory.Credentials.UserName.Password = password;
           channelFactory.Credentials.ClientCertificate.SetCertificate(
           "CN=client.com", StoreLocation.CurrentUser, StoreName.My);
              channelFactory.Credentials.ServiceCertificate.SetDefaultCertificate(
           "CN=localhost", StoreLocation.LocalMachine, StoreName.My);
           client = channelFactory.CreateChannel();
           Console.WriteLine("Echo service returned: {0}",
                                           client.Echo());

           ((IChannel)client).Close();
           channelFactory.Close();
        }
        catch (CommunicationException e)
        {
         Abort((IChannel)client, channelFactory);
         // if there is a fault then print it out
         FaultException fe = null;
         Exception tmp = e;
         while (tmp != null)
         {
            fe = tmp as FaultException;
            if (fe != null)
            {
                break;
            }
            tmp = tmp.InnerException;
        }
        if (fe != null)
        {
           Console.WriteLine("The server sent back a fault: {0}",
         fe.CreateMessageFault().Reason.GetMatchingTranslation().Text);
        }
        else
        {
         Console.WriteLine("The request failed with exception: {0}",e);
        }
    }
    catch (TimeoutException)
    {
        Abort((IChannel)client, channelFactory);
        Console.WriteLine("The request timed out");
    }
    catch (Exception e)
    {
         Abort((IChannel)client, channelFactory);
          Console.WriteLine(
          "The request failed with unexpected exception: {0}", e);
    }
    Console.WriteLine();
    Console.WriteLine("Press <ENTER> to terminate client.");
    Console.ReadLine();
}

呼び出し元の情報の表示

呼び出し元の情報を表示するには、次のコードに示すように ServiceSecurityContext.Current.AuthorizationContext.ClaimSets を使用できます。 ServiceSecurityContext.Current.AuthorizationContext.ClaimSets には、現在の呼び出し元に関連付けられている承認クレームが含まれています。これらのクレームは、メッセージで受信したすべてのトークンについて Windows Communication Foundation (WCF) によって自動的に提供されます。

bool TryGetClaimValue<TClaimResource>(ClaimSet claimSet, string
                         claimType, out TClaimResource resourceValue)
    where TClaimResource : class
{
    resourceValue = default(TClaimResource);
    IEnumerable<Claim> matchingClaims =
    claimSet.FindClaims(claimType, Rights.PossessProperty);
    if (matchingClaims == null)
          return false;
    IEnumerator<Claim> enumerator = matchingClaims.GetEnumerator();
    if (enumerator.MoveNext())
    {
        resourceValue = (enumerator.Current.Resource == null) ? null : (enumerator.Current.Resource as TClaimResource);
        return true;
    }
    else
    {
         return false;
    }
}

// Returns the username and certificate subject name provided by the client
void GetCallerIdentities(ServiceSecurityContext callerSecurityContext, out string userName, out string certificateSubjectName)
{
    userName = null;
    certificateSubjectName = null;

    // Look in all the claimsets in the authorization context
    foreach (ClaimSet claimSet in
      callerSecurityContext.AuthorizationContext.ClaimSets)
    {
        if (claimSet is WindowsClaimSet)
        {
            // Try to find a Name claim. This will have been generated
            //from the windows username.
            string tmpName;
            if (TryGetClaimValue<string>(claimSet, ClaimTypes.Name,
                                                     out tmpName))
            {
                userName = tmpName;
            }
        }
        else if (claimSet is X509CertificateClaimSet)
         {
            //Try to find an X500DistinguishedName claim.
            //This will have been generated from the client
            //certificate.
            X500DistinguishedName tmpDistinguishedName;
            if (TryGetClaimValue<X500DistinguishedName>(claimSet,
               ClaimTypes.X500DistinguishedName,
               out tmpDistinguishedName))
            {
                    certificateSubjectName = tmpDistinguishedName.Name;
            }
        }
    }
}

サンプルの実行

このサンプルを実行すると、最初にクライアントから、ユーザー名トークンのユーザー名とパスワードを入力するように求められます。サービスの WCF では、ユーザー名トークンに指定された値がシステムによって提供される ID にマップされるため、必ずシステムアカウントの正しい値を入力してください。その後、クライアントではサービスからの応答が表示されます。クライアントをシャットダウンするには、クライアントウィンドウで Enter キーを押します。

セットアップバッチファイル

このサンプルに用意されている Setup.bat バッチファイルを使用すると、適切な証明書を使用してサーバーを構成し、インターネットインフォメーションサービス (IIS) でホストされるアプリケーションを実行できるようになります。このアプリケーションは、サーバー証明書ベースのセキュリティを必要とします。このバッチファイルは、別のコンピューターを使用する場合またはホストなしの場合に応じて変更する必要があります。

次に、バッチファイルのセクションのうち、適切な構成で実行するために変更が必要となる部分を示します。

クライアント証明書の作成

Setup.bat バッチファイルの次の行は、使用するクライアント証明書を作成します。 %CLIENT_NAME% 変数は、クライアント証明書のサブジェクトを指定します。このサンプルでは、サブジェクト名として "client.com" を使用します。

証明書は、CurrentUser ストアの場所の My (Personal) ストアに保存されます。

echo ************
echo making client cert
echo ************
makecert.exe -sr CurrentUser -ss MY -a sha1 -n CN=%CLIENT_NAME% -sky exchange -pe

クライアント証明書のサーバーの信頼されたストアへのインストール

Setup.bat バッチファイルの次の行を使用して、クライアント証明書をサーバーの信頼されたユーザーのストアにコピーします。この手順が必要なのは、Makecert.exe によって生成される証明書が、サーバーのシステムにより暗黙には信頼されないからです。マイクロソフト発行の証明書など、クライアントの信頼されたルート証明書に基づいた証明書が既にある場合は、クライアント証明書ストアにサーバー証明書を配置するこの手順は不要です。

echo ************
echo copying client cert to server's CurrentUserstore
echo ************
certmgr.exe -add -r CurrentUser -s My -c -n %CLIENT_NAME% -r LocalMachine -s TrustedPeople

サーバー証明書の作成

Setup.bat バッチファイルの次の行は、使用するサーバー証明書を作成します。 %SERVER_NAME% 変数はサーバー名です。この変数を変更して、使用するサーバー名を指定します。このバッチファイルでの既定は localhost です。

証明書は、LocalMachine ストアの場所の My (Personal) ストアに保存されます。証明書は、IIS でホストされるサービスの LocalMachine ストアに保存されます。自己ホスト型サービスの場合、バッチファイルで文字列 LocalMachine を CurrentUser に置き換えて、サーバー証明書を CurrentUser ストアの場所に保存します。

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

サーバー証明書のクライアントの信頼された証明書ストアへのインストール

Setup.bat バッチファイルの次の行は、サーバー証明書をクライアントの信頼されたユーザーのストアにコピーします。この手順が必要なのは、Makecert.exe によって生成される証明書がクライアントシステムにより暗黙には信頼されないからです。マイクロソフト発行の証明書など、クライアントの信頼されたルート証明書に基づいた証明書が既にある場合は、クライアント証明書ストアにサーバー証明書を配置するこの手順は不要です。

echo ************
echo copying server cert to client's TrustedPeople store
echo ************certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople

証明書の秘密キーへのアクセスの有効化

IIS でホストされるサービスから証明書の秘密キーへのアクセスを有効にするには、IIS でホストされる処理が実行されているユーザーアカウントに、秘密キーへの適切なアクセス許可を付与する必要があります。これは、Setup.bat スクリプトの最後の手順によって実現されます。

echo ************
echo setting privileges on server certificates
echo ************
for /F "delims=" %%i in ('"%ProgramFiles%\ServiceModelSampleTools\FindPrivateKey.exe" My LocalMachine -n CN^=%SERVER_NAME% -a') do set PRIVATE_KEY_FILE=%%i
set WP_ACCOUNT=NT AUTHORITY\NETWORK SERVICE
(ver | findstr /C:"5.1") && set WP_ACCOUNT=%COMPUTERNAME%\ASPNET
echo Y|cacls.exe "%PRIVATE_KEY_FILE%" /E /G "%WP_ACCOUNT%":R
iisreset

サンプルをセットアップ、ビルド、および実行するには

Windows Communication Foundation サンプルの 1 回限りのセットアップの手順を実行したことを確認します。
ソリューションをビルドするには、「Windows Communication Foundation サンプルのビルド」の手順に従います。
サンプルを単一コンピューター構成で実行するか、複数コンピューター構成で実行するかに応じて、次の手順に従います。

サンプルを同じコンピューターで実行するには

管理者特権で実行した Visual Studio コマンドプロンプト内で、サンプルのインストールフォルダーから Setup.bat を実行します。これにより、サンプルの実行に必要なすべての証明書がインストールされます。

Note

Setup.bat バッチファイルは、Visual Studio コマンドプロンプトから実行します。 Visual Studio コマンドプロンプト内で設定された PATH 環境変数は、Setup.bat スクリプトで必要な実行可能ファイルが格納されているディレクトリを指しています。サンプルの使用が終わったら、Cleanup.bat を実行して証明書を削除してください。他のセキュリティサンプルでも同じ証明書を使用します。
Client.exe を \client\bin で起動します。クライアントアクティビティがクライアントのコンソールアプリケーションに表示されます。
クライアントとサービスの間で通信できない場合は、WCF サンプルのトラブルシューティングのヒントに関するページをご覧ください。

サンプルを複数コンピューターで実行するには

サービスコンピューターにディレクトリを作成します。インターネットインフォメーションサービス (IIS) 管理ツールを使用して、このディレクトリ用に servicemodelsamples という仮想アプリケーションを作成します。
サービスプログラムファイルを \inetpub\wwwroot\servicemodelsamples からサービスコンピューターの仮想ディレクトリにコピーします。ファイルのコピー先が \bin サブディレクトリであることを確認します。 Setup.bat、Cleanup.bat、ImportClientCert.bat の各ファイルもサービスコンピューターにコピーします。
クライアントコンピューターにクライアントバイナリ用のディレクトリを作成します。
クライアントプログラムファイルを、クライアントコンピュータに作成したクライアントディレクトリにコピーします。 Setup.bat、Cleanup.bat、ImportServiceCert.bat の各ファイルもクライアントにコピーします。
サーバーで、管理者特権で開いた Visual Studio の開発者コマンドプロンプトで setup.bat service を実行します。 setup.bat に service 引数を指定して実行すると、コンピューターの完全修飾ドメイン名を使用してサービス証明書が作成され、Service.cer というファイルにエクスポートされます。
Web.config を編集して、新しい証明書名 (<serviceCertificate> の findValue 属性) を反映します。これは、コンピューターの完全修飾ドメイン名と同じです。
Service.cer ファイルを、サービスディレクトリからクライアントコンピューターのクライアントディレクトリにコピーします。
クライアントで、管理者特権で開いた Visual Studio の開発者コマンドプロンプトで setup.bat client を実行します。 setup.batに client 引数を指定して実行すると、client.com というクライアント証明書が作成され、Client.cer というファイルにエクスポートされます。
クライアントコンピューターの Client.exe.config ファイルで、エンドポイントのアドレス値をサービスの新しいアドレスに合わせます。そのためには、localhost をサーバーの完全修飾ドメイン名に置き換えます。
Client.cer ファイルを、クライアントディレクトリからサーバーのサービスディレクトリにコピーします。
クライアントで ImportServiceCert.bat を実行します。これにより、サービス証明書が Service.cer ファイルから CurrentUser - TrustedPeople ストアにインポートされます。
サーバーで ImportClientCert.bat を実行します。これにより、クライアント証明書が Client.cer ファイルから LocalMachine - TrustedPeople ストアにインポートされます。
クライアントコンピューターで、コマンドプロンプトウィンドウから Client.exe を起動します。クライアントとサービスの間で通信できない場合は、WCF サンプルのトラブルシューティングのヒントに関するページをご覧ください。

サンプルの実行後にクリーンアップするには

サンプルの実行が終わったら、サンプルフォルダーにある Cleanup.bat を実行します。

Note

このサンプルを別のマシンで実行している場合、このスクリプトはサービス証明書をクライアントから削除しません。複数のコンピューターで証明書を使用する WCF サンプルを実行した場合は、CurrentUser-TrustedPeople ストアにインストールされたサービス証明書を忘れずに削除してください。削除するには、コマンド certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name> を実行します。たとえば、certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com となります。

次の方法で共有

トークンのサポート

対象

クライアントによる、ユーザー名トークンと X.509 サポートセキュリティトークンを使用した認証

呼び出し元の情報の表示

サンプルの実行

セットアップバッチファイル

クライアント証明書の作成

クライアント証明書のサーバーの信頼されたストアへのインストール

サーバー証明書の作成

サーバー証明書のクライアントの信頼された証明書ストアへのインストール

証明書の秘密キーへのアクセスの有効化

サンプルをセットアップ、ビルド、および実行するには

サンプルを同じコンピューターで実行するには

サンプルを複数コンピューターで実行するには

サンプルの実行後にクリーンアップするには

その他のリソース

次の方法で共有

トークンのサポート

対象

クライアントによる、ユーザー名トークンと X.509 サポート セキュリティ トークンを使用した認証

呼び出し元の情報の表示

サンプルの実行

セットアップ バッチ ファイル

クライアント証明書の作成

クライアント証明書のサーバーの信頼されたストアへのインストール

サーバー証明書の作成

サーバー証明書のクライアントの信頼された証明書ストアへのインストール

証明書の秘密キーへのアクセスの有効化

サンプルをセットアップ、ビルド、および実行するには

サンプルを同じコンピューターで実行するには

サンプルを複数コンピューターで実行するには

サンプルの実行後にクリーンアップするには

その他のリソース

クライアントによる、ユーザー名トークンと X.509 サポートセキュリティトークンを使用した認証

セットアップバッチファイル