SAML トークンプロバイダー

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

このサンプルでは、カスタムクライアントの SAML トークンプロバイダーを実装する方法を示します。 Windows Communication Foundation (WCF) のトークンプロバイダーは、セキュリティインフラストラクチャに資格情報を提供するために使用されます。一般的に、トークンプロバイダーは、ターゲットをチェックし、適切な証明書を発行して、セキュリティインフラストラクチャがメッセージのセキュリティを保護できるようにします。 WCF には、既定の資格情報マネージャートークンプロバイダーが付属しています。また、WCF には CardSpace トークンプロバイダーも付属しています。カスタムトークンプロバイダーは、次の場合に便利です。

トークンプロバイダーが連携動作できない資格情報ストアがある場合。
ユーザーが詳細を提供した時点から WCF クライアントフレームワークで資格情報が使用されるまでの間に資格情報を変換するための、独自のカスタムメカニズムを提供する場合。
カスタムトークンを構築している場合。

このサンプルでは、WCF クライアントフレームワーク以外から取得した SAML トークンを使用できるようにする、カスタムトークンプロバイダーを構築する方法を示します。

このサンプルに示されている手順の概要は次のとおりです。

クライアントをカスタムトークンプロバイダーを使用して構成する手順。
SAML トークンをカスタムクライアント資格情報に渡す手順。
SAML トークンを WCF クライアントフレームワークに提供する手順。
サーバーがクライアントによってサーバーの X.509 証明書を使用して認証される手順。

このサービスでは、構成ファイル App.config で定義した、サービスとの通信に使用する 2 つのエンドポイントを公開します。各エンドポイントは、アドレス、バインディング、コントラクトで構成されます。バインディングの構成には、標準の wsFederationHttpBinding が使用されます。これはメッセージセキュリティを使用します。 1 つのエンドポイントは、クライアントが対称証明キーを使用する SAML トークンで認証を行うことを想定しています。これに対してもう 1 つのエンドポイントでは、クライアントが非対称証明キーを使用する SAML トークンで認証を行うことを想定しています。また、サービスは serviceCredentials 動作を使用してサービス証明書の構成も行います。 serviceCredentials 動作を使用すると、サービス証明書を構成できます。クライアントはサービス証明書を使用して、サービスを認証し、メッセージを保護します。次の構成では、このトピックの最後のセットアップ手順で説明しているサンプルセットアップでインストールされる "localhost" 証明書を参照しています。 serviceCredentials 動作を使用すると、SAML トークンに署名する信頼できる証明書を構成することもできます。次の構成では、サンプルでインストールされる 'Alice' 証明書を参照しています。

<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 that expect SAML tokens with Symmetric proof keys -->
   <endpoint address="calc/symm"
             binding="wsFederationHttpBinding"
             bindingConfiguration="Binding1"
             contract="Microsoft.ServiceModel.Samples.ICalculator" />
   <!-- Endpoint that expect SAML tokens with Asymmetric proof keys -->
   <endpoint address="calc/asymm"
             binding="wsFederationHttpBinding"
             bindingConfiguration="Binding2"
             contract="Microsoft.ServiceModel.Samples.ICalculator" />
  </service>
 </services>

 <bindings>
  <wsFederationHttpBinding>
   <!-- Binding that expect SAML tokens with Symmetric proof keys -->
   <binding name="Binding1">
    <security mode="Message">
     <message negotiateServiceCredential ="false"
              issuedKeyType="SymmetricKey"
              issuedTokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"  />
    </security>
   </binding>
   <!-- Binding that expect SAML tokens with Asymmetric proof keys -->
   <binding name="Binding2">
    <security mode="Message">
     <message negotiateServiceCredential ="false"
              issuedKeyType="AsymmetricKey"
              issuedTokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"  />
    </security>
   </binding>
  </wsFederationHttpBinding>
 </bindings>

 <behaviors>
  <serviceBehaviors>
   <behavior name="CalculatorServiceBehavior">
    <!--
    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>
     <!-- Set allowUntrustedRsaIssuers to true to allow self-signed, asymmetric key based SAML tokens -->
     <issuedTokenAuthentication allowUntrustedRsaIssuers ="true" >
      <!-- Add Alice to the list of certs trusted to issue SAML tokens -->
      <knownCertificates>
       <add storeLocation="LocalMachine"
            storeName="TrustedPeople"
            x509FindType="FindBySubjectName"
            findValue="Alice"/>
      </knownCertificates>
     </issuedTokenAuthentication>
     <serviceCertificate storeLocation="LocalMachine"
                         storeName="My"
                         x509FindType="FindBySubjectName"
                         findValue="localhost"  />
    </serviceCredentials>
   </behavior>
  </serviceBehaviors>
 </behaviors>

</system.serviceModel>

カスタムの SAML トークンプロバイダーを開発して WCF のセキュリティフレームワークに統合する方法を、次の手順に示します。

カスタムの SAML トークンプロバイダーを作成します。

サンプルでは、構築時に提供される SAML アサーションに基づいてセキュリティトークンを返す、カスタムの SAML トークンプロバイダーを実装します。

このタスクを実行するため、カスタムトークンプロバイダーは SecurityTokenProvider クラスから派生し、GetTokenCore メソッドをオーバーライドします。このメソッドは、新しい SecurityToken を作成して返します。

protected override SecurityToken GetTokenCore(TimeSpan timeout)
{
 // Create a SamlSecurityToken from the provided assertion
 SamlSecurityToken samlToken = new SamlSecurityToken(assertion);

 // Create a SecurityTokenSerializer that will be used to
 // serialize the SamlSecurityToken
 WSSecurityTokenSerializer ser = new WSSecurityTokenSerializer();
 // Create a memory stream to write the serialized token into
 // Use an initial size of 64Kb
 MemoryStream s = new MemoryStream(UInt16.MaxValue);

 // Create an XmlWriter over the stream
 XmlWriter xw = XmlWriter.Create(s);

 // Write the SamlSecurityToken into the stream
 ser.WriteToken(xw, samlToken);

 // Seek back to the beginning of the stream
 s.Seek(0, SeekOrigin.Begin);

 // Load the serialized token into a DOM
 XmlDocument dom = new XmlDocument();
 dom.Load(s);

 // Create a KeyIdentifierClause for the SamlSecurityToken
 SamlAssertionKeyIdentifierClause samlKeyIdentifierClause = samlToken.CreateKeyIdentifierClause<SamlAssertionKeyIdentifierClause>();

// Return a GenericXmlToken from the XML for the
// SamlSecurityToken, the proof token, the valid from and valid
// until times from the assertion and the key identifier clause
// created above
return new GenericXmlSecurityToken(dom.DocumentElement, proofToken, assertion.Conditions.NotBefore, assertion.Conditions.NotOnOrAfter, samlKeyIdentifierClause, samlKeyIdentifierClause, null);
}

カスタムセキュリティトークンマネージャーを作成します。

SecurityTokenManager クラスは、SecurityTokenProvider メソッド内で渡される特定の SecurityTokenRequirement の CreateSecurityTokenProvider の作成に使用されます。セキュリティトークンマネージャーは、トークン認証システムとトークンシリアライザーの作成にも使用されますが、このサンプルでは扱っていません。このサンプルでは、カスタムセキュリティトークンマネージャーは ClientCredentialsSecurityTokenManager クラスを継承し、渡されたトークンの要件で SAML トークンが必要であることが示されている場合に、CreateSecurityTokenProvider メソッドをオーバーライドしてカスタムの SAML トークンプロバイダーを返します。クライアント資格情報クラス (手順 3. を参照) がアサーションを指定していない場合、セキュリティトークンマネージャーは適切なインスタンスを作成します。

public class SamlSecurityTokenManager : ClientCredentialsSecurityTokenManager
{
 SamlClientCredentials samlClientCredentials;

 public SamlSecurityTokenManager ( SamlClientCredentials samlClientCredentials)
  : base(samlClientCredentials)
 {
  // Store the creating client credentials
  this.samlClientCredentials = samlClientCredentials;
 }

 public override SecurityTokenProvider CreateSecurityTokenProvider ( SecurityTokenRequirement tokenRequirement )
 {
  // If token requirement matches SAML token return the
  // custom SAML token provider
  if (tokenRequirement.TokenType == SecurityTokenTypes.Saml ||
      tokenRequirement.TokenType == "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1")
  {
   // Retrieve the SAML assertion and proof token from the
   // client credentials
   SamlAssertion assertion = this.samlClientCredentials.Assertion;
   SecurityToken prooftoken = this.samlClientCredentials.ProofToken;

   // If either the assertion of proof token is null...
   if (assertion == null || prooftoken == null)
   {
    // ...get the SecurityBindingElement and then the
    // specified algorithm suite
    SecurityBindingElement sbe = null;
    SecurityAlgorithmSuite sas = null;

    if ( tokenRequirement.TryGetProperty<SecurityBindingElement> ( "http://schemas.microsoft.com/ws/2006/05/servicemodel/securitytokenrequirement/SecurityBindingElement", out sbe))
    {
     sas = sbe.DefaultAlgorithmSuite;
    }

    // If the token requirement is for a SymmetricKey based token..
    if (tokenRequirement.KeyType == SecurityKeyType.SymmetricKey)
    {
     // Create a symmetric proof token
     prooftoken = SamlUtilities.CreateSymmetricProofToken ( tokenRequirement.KeySize );
     // and a corresponding assertion based on the claims specified in the client credentials
     assertion = SamlUtilities.CreateSymmetricKeyBasedAssertion ( this.samlClientCredentials.Claims, new X509SecurityToken ( samlClientCredentials.ClientCertificate.Certificate ), new X509SecurityToken ( samlClientCredentials.ServiceCertificate.DefaultCertificate ), (BinarySecretSecurityToken)prooftoken, sas);
    }
    // otherwise...
    else
    {
     // Create an asymmetric proof token
     prooftoken = SamlUtilities.CreateAsymmetricProofToken();
     // and a corresponding assertion based on the claims
     // specified in the client credentials
     assertion = SamlUtilities.CreateAsymmetricKeyBasedAssertion ( this.samlClientCredentials.Claims, prooftoken, sas );
    }
   }

   // Create a SamlSecurityTokenProvider based on the assertion and proof token
   return new SamlSecurityTokenProvider(assertion, prooftoken);
  }
  // otherwise use base implementation
  else
  {
   return base.CreateSecurityTokenProvider(tokenRequirement);
  }
}

カスタムクライアント資格情報を作成します。

クライアント資格情報クラスは、クライアントプロキシ用に構成された資格情報を表すために使用され、トークン認証システム、トークンプロバイダー、およびトークンシリアライザーの取得に使用されるセキュリティトークンマネージャーを作成します。

public class SamlClientCredentials : ClientCredentials
{
 ClaimSet claims;
 SamlAssertion assertion;
 SecurityToken proofToken;

 public SamlClientCredentials() : base()
 {
  // Set SupportInteractive to false to suppress Cardspace UI
  base.SupportInteractive = false;
 }

 protected SamlClientCredentials(SamlClientCredentials other) : base ( other )
 {
  // Just do reference copy given sample nature
  this.assertion = other.assertion;
  this.claims = other.claims;
  this.proofToken = other.proofToken;
 }

 public SamlAssertion Assertion { get { return assertion; } set { assertion = value; } }

 public SecurityToken ProofToken { get { return proofToken; } set { proofToken = value; } }
 public ClaimSet Claims { get { return claims; } set { claims = value; } }

 protected override ClientCredentials CloneCore()
 {
  return new SamlClientCredentials(this);
 }

 public override SecurityTokenManager CreateSecurityTokenManager()
 {
  // return custom security token manager
  return new SamlSecurityTokenManager(this);
 }
}

カスタムクライアント資格情報を使用するようクライアントを構成します。

サンプルでは既定のクライアント資格情報を削除し、新しいクライアント資格情報クラスを提供して、クライアントがカスタムクライアント資格情報を使用できるようにします。

// Create new credentials class
SamlClientCredentials samlCC = new SamlClientCredentials();

// Set the client certificate. This is the cert that will be used to sign the SAML token in the symmetric proof key case
samlCC.ClientCertificate.SetCertificate(StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "Alice");

// Set the service certificate. This is the cert that will be used to encrypt the proof key in the symmetric proof key case
samlCC.ServiceCertificate.SetDefaultCertificate(StoreLocation.CurrentUser, StoreName.TrustedPeople, X509FindType.FindBySubjectName, "localhost");

// Create some claims to put in the SAML assertion
IList<Claim> claims = new List<Claim>();
claims.Add(Claim.CreateNameClaim(samlCC.ClientCertificate.Certificate.Subject));
ClaimSet claimset = new DefaultClaimSet(claims);
samlCC.Claims = claimset;

// set new credentials
client.ChannelFactory.Endpoint.Behaviors.Remove(typeof(ClientCredentials));
client.ChannelFactory.Endpoint.Behaviors.Add(samlCC);

サービスでは、呼び出し元に関連するクレームが表示されます。このサンプルを実行すると、操作要求および応答がクライアントのコンソールウィンドウに表示されます。クライアントをシャットダウンするには、クライアントウィンドウで Enter キーを押します。

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

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

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

サーバー証明書の作成 :

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

証明書は、LocalMachine ストアの場所の My (Personal) ストアに保存されます。
```
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 によって生成される証明書がクライアントシステムにより暗黙には信頼されないからです。マイクロソフト発行の証明書など、クライアントの信頼されたルート証明書に基づいた証明書が既にある場合は、クライアント証明書ストアにサーバー証明書を配置するこの手順は不要です。
```
certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r LocalMachine -s TrustedPeople
```
発行元の証明書の作成

Setup.bat バッチファイルの次の行は、使用する発行元の証明書を作成します。 %USER_NAME% 変数は発行元の名前です。この変数を変更して、使用する発行元の名前を指定します。このバッチファイルでの既定値は Alice です。

証明書は、CurrentUser 保存場所の My ストアに保存されます。
```
echo ************
echo Server cert setup starting
echo %SERVER_NAME%
echo ************
echo making server cert
echo ************
makecert.exe -sr CurrentUser -ss My -a sha1 -n CN=%USER_NAME% -sky exchange -pe
```
サーバーの信頼された証明書ストアへの発行元証明書のインストール

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

サンプルをセットアップしてビルドするには

Windows Communication Foundation サンプルの 1 回限りのセットアップの手順を実行したことを確認します。
ソリューションをビルドするには、「Windows Communication Foundation サンプルのビルド」の手順に従います。

Note

Svcutil.exe を使用してこのサンプルの構成を再生成した場合は、クライアントコードに一致するように、クライアント構成内のエンドポイント名を変更してください。

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

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

Note

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

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

サービスコンピューターにサービスバイナリ用のディレクトリを作成します。
サービスプログラムファイルを、サービスコンピューターのサービスディレクトリにコピーします。 Setup.bat ファイルと Cleanup.bat ファイルもサービスコンピューターにコピーします。
コンピューターの完全修飾ドメイン名を含むサブジェクト名を持つサーバー証明書が必要です。新しい証明書名を反映するには、Service.exe.config ファイルを更新する必要があります。サーバー証明書を作成するには、Setup.bat バッチファイルを変更します。 Setup.bat ファイルは、管理者特権で開いた Visual Studio ウィンドウの開発者コマンドプロンプトで実行する必要があります。 %SERVER_NAME% 変数には、サービスをホストするコンピューターの完全修飾ホスト名を設定する必要があります。
サーバー証明書をクライアントの CurrentUser-TrustedPeople ストアにコピーします。この手順は、サーバー証明書の発行元をクライアントが信頼できる場合は不要です。
サービスコンピューターの Service.exe.config ファイルで、ベースアドレスの値を localhost から完全修飾コンピューター名に変更します。
サービスコンピューターで、コマンドプロンプトから Service.exe を実行します。
クライアントプログラムファイルを、言語固有のフォルダーにある \client\bin\ フォルダーからクライアントコンピューターにコピーします。
クライアントコンピューターの Client.exe.config ファイルで、エンドポイントのアドレス値をサービスの新しいアドレスに合わせます。
クライアントコンピューターで、コマンドプロンプトウィンドウから Client.exe を起動します。
クライアントとサービスの間で通信できない場合は、WCF サンプルのトラブルシューティングのヒントに関するページをご覧ください。

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

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

SAML トークン プロバイダー

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