API を使用した SAML sender-vouches トークンの作成

SAML ライブラリー API を使用して、sender-vouches 確認方式を組み込んだ SAML sender-vouches トークン を作成します。sender-vouches 確認方式 は、サーバーがクライアント識別またはクライアントの動作を 伝搬する必要がある場合に使用されます。

このタスクについて

WebSphere® サーバーに SAML 機能がインストールされると、SAML ライブラリー API が 提供されます。このライブラリーを SAML sender-vouches トークン作成のために使用します。SAML ライブラリー API を使用して、必要な SAML 構成 オブジェクトを作成することができます。次に、それらの構成オブジェクトを使用して SAML sender-vouches トークンを生成します。

手順

  1. SAML トークン・バージョンをパラメーターとして使用して、SAMLTokenFactory インスタンスを 作成します。
    1. 以下のコード行を使用して、メソッドをインポートします。
      import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
    2. トークン・バージョンに基づいて、インスタンス作成のための以下のコード行のいずれかを使用 します。
      • バージョン 1.1 SAML トークンの場合、SAMLTokenFactory インスタンスを作成するために 以下のコード行を追加します。
        SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
      • バージョン 2.0 SAML トークンの場合、SAMLTokenFactory インスタンスを作成するために 以下のコード行を追加します。
        SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token20);
  2. インスタンスの作成が終わったら、SAMLTokenFactory が RequesterConfig インスタンスの作成に使用されます。これは、要求側の認証要件に従って、トークンがどのように 生成されるのかを決定します。 sender-vouches トークン用の RequesterConfig インスタンス を作成するには、次のコード行を使用します。
    RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
    単純 な sender-vouches トークンを生成するにはデフォルトの RequestConfig インスタンスで十分ですが、 RequesterConfig インスタンスをカスタマイズして、追加のアサーションを SAML トークン に組み込むことができます。例えば、 パスワード認証情報をトークンに組み込むには、 メソッド setAuthenticationMethod を使用します。
    reqData.setAuthenticationMethod(“password”);
    sender-vouches アサーション 用のトラスト検査は、発行者ではなく、送信者の責任であるため、 アサーション内に Enveloped-Signature エレメントは必要ありません。Enveloped-Signature エレメントを SAML アサーションから削除するには、例えば、以下のように setAssertionSignatureRequired メソッドを使用します。
    reqData.setAssertionSignatureRequired(false);
  3. SAMLTokenFactory API を使用して、トークン発行者を記述する ProviderConfig インスタンス を作成します。ProviderConfig インスタンスは、 SAML 暗号化および署名のための鍵を識別する鍵ストアおよびトラストストアの情報 と、SAML 発行者名を指定します。 ProviderConfig インスタンスの作成には、プロパティー・ファイルからのプロパティー値 が使用されます。このプロパティー・ファイルは ProviderConfig オブジェクトの デフォルト値を指定します。Java™ クライアント環境では、 このプロパティー・ファイルは JVM システム・プロパティー com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath によって定義されます。
    WebSphere Application Server ランタイム環境 では、このプロパティー・ファイルの名前は SAMLIssuerConfig.properties です。 このファイルは、優先順に、サーバー・レベル構成ディレクトリーの下、 またはセル・レベル・ディレクトリーの下に、置くことができます。 以下はサーバー・レベル・パスの例です。
    app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
    以下はセル・レベル・パスの例です。
    app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties

    JVM システム・プロパティー com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath は、 このプロパティーがサーバー・ランタイム環境で定義されている場合は無視されます。 すべてのプロパティーの詳しい説明については、『トークン作成中の SAML トークンの構成』を 参照してください。

    以下のコード行を使用して、デフォルト ProviderConfig インスタンスを作成します。

    ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“any issuer name”);
    発行者名 はオプションです。発行者名が指定されている場合、SAML アサーション に発行者名が含まれます。発行者名が指定されていない場合、 SAMLIssuerConfig.properties からのデフォルト発行者名プロパティー が発行者名として使用されます。
  4. オプション: 新規 SAML トークンを作成する場合、 SAMLTokenFactory は Java 認証・承認サービス (JAAS) サブジェクトまたは CredentialConfig インスタンスの どちらかを使用して、新規 SAML トークンに値を設定します。 JAAS サブジェクトを使用してトークンにデータを取り込む場合は、com.ibm.websphere.security.auth.WSSubject getCallerSubject() API または getRunAsSubject() API を使用して、要求側クライアントまたは実行スレッドの ID を表す JAAS サブジェクトを取得します。
    • JAAS サブジェクトを使用して新規 SAML トークンを 作成する場合、SAMLTokenFactory API がサブジェクト PrivateCredentials リスト内で SAMLToken オブジェクト を探します。SAMLToken オブジェクトが存在する 場合、NameId または NameIdentifier オブジェクトが新規 SAML トークンにコピーされます。また、 SAMLTokenFactory は、SAML 属性および AuthenticationMethod 方式を、 既存の SAML トークンから新規 SAML トークンにコピーします。新規 SAML トークン は、新しい発行者名、新しい署名証明書、確認方式、 holder-of-key 確認方式用の新しい KeyInfo、および、 新しい NotBefore および NotOnAfter 条件を含みます。これらのトークン設定値 は、ProviderConfig オブジェクトおよび RequesterConfig オブジェクト内の 構成パラメーターによって決まります。

      サブジェクト内に SAMLToken オブジェクトがない場合、 WSPrincipal プリンシパル名のみがサブジェクトから新規 SAML トークンに コピーされます。サブジェクト中の他の属性 は新規 SAML トークンにコピーされません。同様に、発行者名、署名証明書、 確認方式、holder-of-key 用の KeyInfo、 NotBefore および NotOnOrAfter 条件は、 ProviderConfig オブジェクトおよび RequesterConfig オブジェクト内の構成パラメーターによって決まります。

      代替方法として、 実行スレッドで RunAsSubject メソッドを使用して SAML トークンを 作成することもできます。この方法を使用する場合は、SAML トークン作成用に JAAS サブジェクト または CredentialConfig オブジェクトを SAMLTokenFactory に渡さないで ください。その代わりに、前に説明したように、既存の SAML トークンの内容 が新規 SAML トークンにコピーされます。

    • SAML トークンを作成する別の方法は、 CredentialConfig オブジェクトを使用して、 SAML の NameId および属性をプログラムで設定する方法です。この方法は、以下の 環境で使用してください。
      • 新規 SAML トークンにカスタム SAML 属性を含める必要がある。
      • SAMLTokenFactory を使用して SAML トークンに JAAS サブジェクトから自動的に値を設定するのではなく、 SAML トークンが手動で作成される。
      • 既存の SAML トークンがサブジェクト内にない。
      • 使用可能な JAAS サブジェクトがない。
    1. JAAS オブジェクトを使用せずに CredentialConfig オブジェクトを作成するには、 以下のコード行を使用します。
      CredentialConfig cred = samlFactory.newCredentialConfig ();
      この CredentialConfig オブジェクトには初期値が提供されていないため、 setter メソッドを使用して CredentialConfig オブジェクトに値を設定する必要があります。
    2. SAML NameIdentifier または NameID を設定するには、次のコード行を使用します。
      cred.setRequesterNameID("any name");
      setRequesterNameID() メソッド に渡されるパラメーターの値は、SAML トークン内で プリンシパル名として使用されます。この名前は、SAML バージョン 1.1 トークン内の NameIdentifier、 または、SAML バージョン 2.0 トークン内の NameId として、アサーションに含まれます。 例えば、setRequesterNameID() メソッドに渡されたパラメーターの値が Alice の場合、以下のアサーションが SAML バージョン 1.1 トークンで生成されます。
      <saml:NameIdentifier>Alice</saml:NameIdentifier>
      SAML バージョン 2.0 トークン 内では次のアサーションが生成されます。
      <saml2:NameID>Alice</saml2:NameID> 
    3. アサーションの <AttributeStatement> 部分に SAML 属性を含めるには、 次のコードを使用します。
      SAMLAttribute samlAttribute = new SAMLAttribute("email" /* Name*/, new String[] {"joe@websphere"} 
      /*Attribute Values*/, null, "IBM WebSphere namespace" /* namespace*/, "email" /* format*/, "joe" /*friendly name */);
      ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
      al.add(samlAttribute)
      sattribute = new SAMLAttribute("Membership", new String[] {"Super users", "Gold membership"}, null, null /* format*/, null, null );
      al.add(samlAttribute );
      cred.setSAMLAttributes(al);
      このサンプル・コードは、以下の <Attribute> アサーションを 生成します。
      <saml:Attribute AttributeName="email" NameFormat="email" AttributeNamespace="IBM WebSphere namespace">
      <saml:AttributeValue>joe@websphere</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute AttributeName="Membership">
      <saml:AttributeValue>Super users</saml:AttributeValue><saml:AttributeValue>Gold membership</saml:AttributeValue>
      </saml:Attribute>
  5. 次のコード行を使用して SAML sender-vouches トークンを生成します。
    SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
    このメソッドは、Java セキュリティー権限 wssapi.SAMLTokenFactory.newSAMLToken を必要とします。

    例セクションに 記述されている前述の手順のコード行を使用して、コード・サンプルを完成してください。

SAML バージョン 1.1 sender-vouches トークン をサブジェクトから作成するには、次のサンプル・コードを使用します。
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11)

RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“WebSphere Server”);

Subject subject =  com.ibm.websphere.security.auth.WSSubject.getRunAsSubject();

SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
サブジェクトを使用せずに SAML バージョン 1.1 sender-vouches トークン を作成するには、次のサンプル・コードを使用します。
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();reqData.setAuthenticationMethod("Password"); //Authentication method for Assertion

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(Self issuer);

CredentialConfig cred = samlFactory.newCredentialConfig ();cred.setRequesterNameID("Alice");   // SAML NameIdentifier
//SAML attributes:	
SAMLAttribute attribute = new SAMLAttribute
   ("email" /* Name*/, new String[] {"joe@websphere"} 
   /*Attribute Values in String*/,null 
   /*Attribute Values in XML */, "WebSphere" /* Namespace*/, "email" /* format*/, "joe" /*Friendly_name */);
ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
al.add(attribute);
attribute = new SAMLAttribute("Membership", new String[] {"Super users", "My team"}, null, null, null, null  );
al.add(attribute);
cred.setSAMLAttributes(al);
SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);

トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_createsendervouchestoken
ファイル名:twbs_createsendervouchestoken.html