SAML トークンの作成と追加

この章では、WS-Security ヘッダ要素に SMAL トークンを追加する方法を説明します。以下のトピックについて説明します。

%SAML.AssertionOpens in a new tab および関連クラスのクラス・リファレンスも参照してください。

SAML の完全サポートは実装されていません。“Caché の SAML サポート” は、最初の章の “Caché における WS-Security のサポート” に掲載した詳細のみに適用されます。

概要

Caché SOAP サポートでは、WS-Security ヘッダ要素に SAML トークンを追加できます。

必要に応じて、この SAML トークンを署名または暗号化のキー・マテリアルとして使用できます。そうすると、Caché が WS-Security SAML トークン・プロファイル仕様に準拠するようになります。キー・マテリアルは、Holder-of-key (HOK) メソッドと <SubjectConfirmationData> を持つ SAML アサーションの <SubjectConfirmation> 要素、または <KeyInfo> 下位要素を持つ <KeyInfoConfirmationData> から取得されます。

また、Sender-vouches (SV) メソッドを持つ <SubjectConfirmation> を追加することもできます。この場合、サブジェクトには、キーは含まれません。この場合にアサーションを保護するには、メッセージ・シグニチャから SAML トークンへのセキュリティ・トークン参照を取得します。

基本的な手順

SAML トークンを作成し、これを発信 SOAP メッセージに追加するには、次に説明する基本的な手順を使用するか、またはサブセクションで説明するバリエーションを使用します。

必要に応じて、%soap.inc インクルード・ファイルを組み込みます。このファイルには、使用する可能性のあるマクロが定義されています。
このドキュメントで前述の “プログラムによる資格情報セットの取得” の説明に従って、%SYS.X509CredentialsOpens in a new tab のインスタンスを作成します。
この Caché 資格情報セットには、所有している証明書を含める必要があります。以下はその例です。
```
 Set x509alias = "servercred" 
 Set pwd = "mypassword" 
 Set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)
```
指定の資格情報セットに関連付けられている証明書が含まれるバイナリ・セキュリティ・トークンを作成します。これには、%SOAP.Security.BinarySecurityTokenOpens in a new tab の CreateX509Token() クラス・メソッドを呼び出します。以下はその例です。
```
 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
```
credset は、前の手順で作成した Caché 資格情報セットです。
WS-Security ヘッダ要素にこのトークンを追加します。そのためには、Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。このメソッドの引数には、作成したトークンを使用します。以下はその例です。
```
 do ..SecurityOut.AddSecurityElement(bst)
```
バイナリ・セキュリティ・トークンに基づいて、署名済みの SAML アサーションを作成します。そのためには、%SAML.AssertionOpens in a new tab の CreateX509() クラス・メソッドを呼び出します。以下はその例です。
```
 set assertion=##class(%SAML.Assertion).CreateX509(bst)
```
このメソッドは %SAML.AssertionOpens in a new tab のインスタンスを返します。Caché は、このインスタンスの Signature、SAMLID、および Version の各プロパティを自動的に設定します。
このインスタンスは、<Assertion> 要素を表します。
%SAML.AssertionOpens in a new tab のインスタンスの以下の基本プロパティを指定します。
- IssueInstant では、このアサーションの発行日時を指定します。
- Issuer では、%SAML.NameIDOpens in a new tab のインスタンスを作成します。必要に応じてこのインスタンスのプロパティを指定し、アサーションの Issuer プロパティをこのインスタンスに設定します。
“SAML 文の追加” の説明に従って、SAML 文を追加します。
“<Subject> 要素の追加” の説明に従って、SAML アサーションに <Subject> 要素を追加します。
オプションで、“<SubjectConfirmation> 要素の追加” の説明に従って、<Subject> に <SubjectConfirmation> 要素を追加します。
Holder Of Key メソッドまたは Sender Voucher メソッドのいずれかを持つサブジェクトを確認できます。
“<Conditions> 要素の追加” の説明に従って、SAML <Conditions> 要素を指定します。
オプションで、“<Advice> 要素の追加” の説明に従って、<Advice> 要素を追加します。
Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。このメソッドの引数には、作成した SAML トークンを使用します。
オプションで、SOAP メッセージ・シグニチャから SAML アサーションに参照を追加することで、SAML アサーションに署名します。
シグニチャが %XML.Security.SignatureOpens in a new tab オブジェクトである場合、次のように SAML アサーションに署名します。
```
  Set str=##class(%SOAP.Security.SecurityTokenReference).GetSAMLKeyIdentifier(assertion) 
  Set ref=##class(%XML.Security.Reference).CreateSTR(str.GetId()) 
  Do signature.AddReference(ref)
```
この手順は、特に、Sender Vouches メソッドを持つ <SubjectConfirmation> を追加する場合にお勧めします。
SOAP メッセージを送信します。このドキュメントで前述の “セキュリティ・ヘッダ要素の追加” の一般的な手順を参照してください。

バリエーション：<BinarySecurityToken> を使用しない手順

<BinarySecurityToken> には、シリアル化された Base 64 のエンコード形式の証明書が含まれています。このトークンを省略し、代わりに証明書を指定する情報を使用できます。受信者は、この情報を使用して、適切な場所から証明書を取得します。そのためには、前述の手順を使用しますが、以下の変更点があります。

手順 2 と 3 をスキップします。つまり、<BinarySecurityToken> の作成および追加は行わないでください。
手順 4 で、CreateX509() の最初の引数として資格情報セットを使用します (バイナリ・セキュリティ・トークンは使用しません)。以下はその例です。
```
 set assertion=##class(%SAML.Assertion).CreateX509(credset,referenceOption)
```
referenceOption には、必要に応じて、このドキュメントで前述の “X.509 資格情報の参照オプション” の説明に従って、値を指定します。$$$SOAPWSReferenceDirect 以外の任意の値を使用します。
(このバリエーションで実行しているように) 最初の引数として資格情報セットを指定する場合、既定の参照オプションは、証明書のサムプリントです。

バリエーション：署名なしの SAML アサーションの作成

署名なしの SAML アサーションを作成するには、前述の手順を使用しますが、以下の変更点があります。

手順 1、2 および 3 をスキップします。つまり、<BinarySecurityToken> の作成および追加は行わないでください。
手順 4 で、CreateX509() の代わりに Create() メソッドを使用します。このメソッドは、引数を取りません。以下はその例です。
```
 set assertion=##class(%SAML.Assertion).Create()
```
このメソッドは %SAML.AssertionOpens in a new tab のインスタンスを返します。Caché は、このインスタンスの SAMLID プロパティおよび Version プロパティを自動的に設定します。Signature プロパティは NULL です。

SAML 文の追加

SAML 文を %SAML.AssertionOpens in a new tab のインスタンスに追加するには、次の操作を実行します。

該当する文クラスの 1 つまたは複数のインスタンスを作成します。
必要に応じてこれらのインスタンスのプロパティを指定します。
%SAML.AttributeStatementOpens in a new tab の場合、Attribute プロパティは %SAML.AttributeOpens in a new tab、または %SAML.EncryptedAttributeOpens in a new tab のインスタンスです。
%SAML.AttributeOpens in a new tab の AttributeValue プロパティには属性値が格納されます。これは %SAML.AttributeValueOpens in a new tab インスタンスのリストです。
%SAML.AttributeOpens in a new tab インスタンスに属性値を追加する手順は以下のとおりです。
1. %SAML.AttributeValueOpens in a new tab のインスタンスを作成します。
2. %SAML.AttributeValueOpens in a new tab のメソッドを使用して属性を XML、文字列、または単一の子要素のいずれかとして指定します。
3. それらの属性値インスタンスを含むリストを作成します。
4. 属性値オブジェクトの AttributeValue プロパティをこのリストに設定します。
または AttributeValueOverride プロパティを直接指定します。この値には、完全一致文字列 (XML 混在コンテンツの文字列) を使用します。
それらの文インスタンスを含むリストを作成します。
アサーション・オブジェクトの Statement プロパティをこのリストに設定します。

<Subject> 要素の追加

<Subject> 要素を %SAML.AssertionOpens in a new tab のインスタンスに追加するには、次の操作を実行します。

%SAML.SubjectOpens in a new tab の新しいインスタンスを作成します。
必要に応じて件名のプロパティを設定します。
アサーション・オブジェクトの Subject プロパティをこのインスタンスに設定します。

<SubjectConfirmation> 要素の追加

<SubjectConfirmation> 要素を %SAML.AssertionOpens in a new tab のインスタンスに追加するには、次のサブセクションのいずれかで説明している手順に従います。

Holder-of-key メソッドを持つ <SubjectConfirmation>

Holder-of-key メソッドを持つ <SubjectConfirmation> を追加するには、次の手順を実行します。

このドキュメントで前述の “プログラムによる資格情報セットの取得” の説明に従って、%SYS.X509CredentialsOpens in a new tab のインスタンスを作成します。
また、アサーションの署名に使用した資格情報セットと同じものを使用することもできます。
オプションで、指定の資格情報セットに関連付けられている証明書が含まれるバイナリ・セキュリティ・トークンを作成して追加します。
トークンを作成するには、%SOAP.Security.BinarySecurityTokenOpens in a new tab の CreateX509Token() クラス・メソッドを呼び出します。以下はその例です。
```
 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
```
credset は、前の手順で作成した資格情報セットです。
WS-Security ヘッダ要素にこのトークンを追加するには、Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。このメソッドの引数には、作成したトークンを使用します。
SAML アサーション・オブジェクトの Subject プロパティの AddX509Confirmation() メソッドを呼び出します。
```
method AddX509Confirmation(credentials As %SYS.X509Credentials, 
                           referenceOption As %Integer) as %Status
```
credentials には、バイナリ・セキュリティ・トークンまたは資格情報セットを使用します。ここでトークンを使用する場合は、referenceOption を指定しないでください。後者の場合、このドキュメントで前述の “X.509 資格情報の参照オプション” の説明に従って、値を指定します。

<SubjectConfirmation> 要素は、X.509 KeyInfo 要素に従います。

Sender-vouches メソッドを持つ <SubjectConfirmation>

Sender-vouches メソッドを持つ <SubjectConfirmation> を追加するには、次の手順を実行します。

SAML アサーション・オブジェクトの Subject プロパティの NameID プロパティを設定します。
SAML アサーション・オブジェクトの Subject プロパティの AddConfirmation() メソッドを呼び出します。
```
method AddConfirmation(method As %String) as %Status
```
method では、$$$SAMLSenderVouches、$$$SAMLHolderOfKey、または $$$SAMLBearer を指定します。

この場合、必ず SAML アサーションに署名して、その SAML アサーションを保護します。

<EncryptedKey> を持つ <SubjectConfirmation>

<EncryptedKey> 要素を含んだ <SubjectConfirmationData> を持つ <SubjectConfirmation> を追加するには、次の手順を実行します。

このドキュメントで前述の “プログラムによる資格情報セットの取得” の説明に従って、%SYS.X509CredentialsOpens in a new tab のインスタンスを作成します。
また、アサーションの署名に使用した資格情報セットと同じものを使用することもできます。
SAML アサーション・オブジェクトの Subject プロパティの NameID プロパティを設定します。
SAML アサーション・オブジェクトの Subject プロパティの AddEncryptedKeyConfirmation() メソッドを呼び出します。
```
method AddEncryptedKeyConfirmation(credentials As %X509.Credentials) as %Status
```
引数には、先ほど作成した %SYS.X509CredentialsOpens in a new tab のインスタンスを使用します。

Holder-of-key として BinarySecret を持つ <SubjectConfirmation>

Holder-of-key として BinarySecret を持つ <SubjectConfirmation> を追加するには、次の手順を実行します。

SAML アサーションに署名するときに、以下のように署名を作成します。
```
set sig=##class(%XML.Security.Signature).Create(assertion,$$$SOAPWSIncludeNone,$$$SOAPWSSAML)
```
assertion は、SAML アサーションです。このシナリオでは、Create() メソッドを使用することに注意してください。$$$SOAPWSSAML 参照オプションは、SAML アサーションへの参照を作成します。
BinarySecret を作成します。これには、%SOAP.WST.BinarySecretOpens in a new tab の Create() メソッドを呼び出します。
```
set binsec=##class(%SOAP.WST.BinarySecret).Create()
```
SAML アサーション・オブジェクトの Subject プロパティの AddBinarySecretConfirmation() メソッドを呼び出します。
```
set status=assertion.Subject.AddBinarySecretConfirmation(binsec)
```
binsec の場合は、前の手順で作成した BinarySecret を使用します。

これにより、<BinarySecret> を含んだ <KeyInfo> を含む <SubjectConfirmationData> を含んだ <SubjectConfirmation> が追加されます。

<Conditions> 要素の追加

<Conditions> 要素を %SAML.AssertionOpens in a new tab のインスタンスに追加するには、次の操作を実行します。

%SAML.ConditionsOpens in a new tab のインスタンスを作成します。
必要に応じてこのインスタンスのプロパティを指定します。
アサーション・オブジェクトの Conditions プロパティをこのインスタンスに設定します。

<Advice> 要素の追加

<Advice> 要素を %SAML.AssertionOpens in a new tab のインスタンスに追加するには、次の操作を実行します。

次のクラスの 1 つまたは複数のインスタンスを作成します。
必要に応じてこれらのインスタンスのプロパティを指定します。
それらの Advice インスタンスを含むリストを作成します。
アサーション・オブジェクトの Advice プロパティをこのリストに設定します。