SAML トークン・ライブラリー API
SAML トークン・ライブラリーのアプリケーション・プログラミング・インターフェース (API) は、 SAML トークンの作成、検証、解析、および抽出に使用できるさまざまなメソッドを提供します。
概要
SAML バージョン 1.1 および SAML バージョン 2.0 の ライブラリー実装は、holder-of-key (HoK)、bearer、 および sender-vouches という 3 タイプのサブジェクト確認を提供します。SAML トークン・ライブラリー API を 使用して、SAML HoK トークンまたは bearer トークンの属性の作成、検証、および 抽出を行うことができます。Web サービス SOAP メッセージからの SAML トークン伝搬についても説明します。API の使用法を示すサンプル・コード が用意されています。
SAML を使用する WebSphere® Application Server は、bearer および HoK のサブジェクト確認をサポートするデフォルト・ポリシー・セットを提供します。
WSS API SAML サポートは、com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory インターフェースおよび com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient インターフェースを補完します。 com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken() メソッドを使用して生成される SAMLToken は、SAMLTokenFactory プログラミング・インターフェースおよび WSSTrustClient プログラミング・インターフェースによって処理できます。 一方、SAMLTokenFactory によって生成される SAMLToken または WSSTrustClient によって返される SAMLToken は、WSS API で使用できます。 アプリケーションでどの API を使用するか決定することは、特定のニーズによって異なります。 WSS API SAML サポートは、Web サービス・クライアント・アプリケーションに関する限り、SAMLTokenFactory インターフェースおよび WSSTrustClient インターフェースと同等の機能を提供するという点では、自己完結的です。SAMLTokenFactory インターフェースには、SAMLToken を検証し、認証された SAMLToken を表す JAAS サブジェクトを作成する追加機能があります。この検証は、 Web サービス・プロバイダー側で役に立ちます。SAMLToken を消費するようにアプリケーションを開発する場合、 SAMLTokenFactory プログラミング・インターフェースがより適しています。
トークン作成パラメーターの構成
トークン作成パラメーター を構成するときの構成情報は、要求側エンティティー、発行側エンティティー、または受信側エンティティーのいずれかに 関連しています。この例では、構成情報は、要求側エンティティーおよび発行側エンティティー について定義されています。サポートされるサブジェクト確認タイプ ごとに、要求側エンティティーについて事前に構成された 属性が SAML トークン・ライブラリーによって提供されます。これらの属性は、WebSphere ランタイム環境による自己発行 SAML トークンの作成中に使用されます。自己発行 SAML トークンは、セキュリティー・トークン・サービス (STS) から要求されるトークンではなく、ローカルで生成されるトークンです。 デフォルト・パラメーターに対してこれらの属性を カスタマイズする必要がある場合、RequesterConfig パラメーターを使用してください。詳しくは、 『SAMLTokenFactory API の RequesterConfig パラメーター』トピックを 参照してください。
// Setup the requester's configuration information (parameters needed
// to create the token specified as configuration properties).
// in this case we are using the configuration information to create a
// SAML token that contains a symmetric holder of key subject
// confirmation.
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Set recipient's public key alias
// (in this example we use SOAPRecipient), so the provider can encrypt secret
// key for the receiving end.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Set the authentication method that took place. This is an optional
// parameter. reqData.setAuthenticationMethod("Password");
// Set issuer information by instantiating a default ProviderConfig.
// See javadocs for the SAMLTokenFactory class on the details of the
// default values and how to modify them.
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
SAML トークン・ファクトリー・インスタンスの作成
SAML トークン・タイプ としてバージョン 1.1 またはバージョン 2.0 のどちらかを指定して、SAMLTokenFactory クラスを使用します。SAML トークン作成に 関する追加パラメーターを設定します。// Instantiate a token factory based on the version level of the token
// to use. In this example we use the SAML v1.1 token factory.
SAMLTokenFactory samlFactory =
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Retrieve the caller subject or the runAsSubject (depending on your
// scenario) then use the Subject to get a CredentialConfig object
// using the SAML token library.
// This invocation requires the
// wssapi.SAMLTokenFactory.newCredentialConfig" Java Security
// permission.
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);
SAML トークンの作成
// Now create the SAML token. This invocation requires the
// "wssapi.SAMLTokenFactory.newSAMLToken" Java Security permission.
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
SAML トークンの検証
SAML トークンを 受け取るエンティティー (例えば、ビジネス・サービス) は、 SAML トークン・ライブラリー API を使用して、受け取ったトークンを使用前に検証することができます。例えば、 要求側からの SAML 属性を抽出する前に、サービスがトークンを検証 する必要がある場合などがあります。既存の SAML アサーション文書 の検証を、コンシューマーからの構成データを使用して行うことができます。ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
XMLStructure xml =
try {
SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
// token successfully validated
} catch(WSSException e) {
// token failed validation
}
サブジェクトにマップされる SAML トークン ID
サブジェクトを 作成するために SAML トークンを使用できます。SAML トークン内の名前 ID がユーザー・レジストリー内のユーザーに マップされることによって、サブジェクトのプリンシパル名が取得されます。Subject subject;
SAMLToken aSAMLToken = …;
try {
subject = samlFactory.newSubject(aSAMLToken);
} catch(WSSException e) {
}
アサーション・エレメントの解析
SAML トークン の受信者は、SAML トークン・ライブラリー API に含まれている SAMLToken API を使用して、 SAML トークンからアサーション・エレメントを解析および 抽出できます。例えば、次のコードを使用して、トークン作成時間を 抽出できます。Date dateCreated = samlToken.getSamlCreated();
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
byte[] hokBytes = samlToken.getHolderOfKeyBytes();
すべての SAML API の 詳細については、API 資料で SAMLToken インターフェースに関する説明を お読みください。
SAML トークン属性の抽出
以下のコード・スニペットのように、SAMLToken API を使用して、 開始エンティティー (サービス要求元) からの SAML 属性を抽出します。// Get all attributes
List<SAMLAttribute> allAttributes =
((SAMLToken) samlToken).getSAMLAttributes();
// Iterate over the attribute and process accordingly
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while (iter.hasNext()) {
SAMLAttribute anAttribute = iter.next();
// Handle attributes
String attributeName = anAttribute.getName();
String[] attributeValues = anAttribute.getStringAttributeValue();
}
サンプル・コード
上記の操作の いくつかについて、SAML トークン・ライブラリー API をどのように 使用すれば実行できるのかをサンプル・コードで示します。SAML プロパティー・ファイルのロケーションを指し示す JVM プロパティーがあることが、このコードを実行するための前提条件です。 SAML プロパティー・ファイル SAMLIssuerConfig.properties には、 SAML トークンの発行者 (プロバイダー) に関連した構成属性が 含まれている必要があります。セル・レベルの SAMLIssuerConfig.properties ファイルのデフォルト・ロケーションは、app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts です。
サーバー・レベルのデフォルト・ロケーションは、app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME です。
IssuerURI=WebSphere
TimeToLive=3600000
KeyStorePath=c:/samlsample/saml-provider.jceks
KeyStoreType=jceks
KeyStorePassword=myissuerstorepass
KeyAlias=samlissuer
KeyName=CN=SAMLIssuer, O=IBM, C=US
KeyPassword=xxxxxxxxx
TrustStorePath=c:/samlsample/saml-provider.jceks
TrustStoreType=jceks
TrustStorePassword=yyyyyyyy
package samlsample;
import java.util.List;
import java.util.Iterator;
import java.util.ArrayList;
import javax.security.auth.Subject;
// Import methods from the SAML token library
import com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.wssecurity.saml.config.ProviderConfig;
import com.ibm.wsspi.wssecurity.saml.config.RequesterConfig;
import com.ibm.wsspi.wssecurity.saml.config.CredentialConfig;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import com.ibm.wsspi.wssecurity.core.token.config.RequesterConfiguration;
public class SamlAPIsample {
public void testSAMLTokenLibrary() throws Exception {
try {
// Get an instance of the SAML v1.1 token factory
SAMLTokenFactory samlFactory = SAMLTokenFac
tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Generate default requester data for a subject confirmation of
// type holder-of-key (secret key).
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Set the recipient's key alias, so that the issuer can encrypt
// the secret key for recipient as part of the subject confirmation.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Set the authentication method that took place. requesterData.setAuthenticationMethod("Password");
System.out.println("default holder of key confirmation key type is: "+
Requester
Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));
Requester
Data.getRSTTProperties().put(RequesterConfiguration.RSTT.KEYTYPE,
"http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey");
requesterData.getRSTTProperties().put(
RequesterConfiguration.RSTT.APPLIESTO_ADDRESS,
"http://localhost:9080");
requesterData.setConfirmationMethod("holder-of-key");
// Set the recipient's key alias so that token infomation such as
// the secret HoK can be encrypted by the issuer and decrypted by the
// recipient.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
requesterData.setAuthenticationMethod("Password");
requesterData.getRSTTProperties().put(
RequesterConfiguration.RSTT.ENCRYPTIONALGORITHM,
"http://www.w3.org/2001/04/xmlenc#aes128-cbc");
requester
Data.getRSTTProperties().put(RequesterConfiguration.RSTT.TOKENTYPE,
"http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-
1.1#SAMLV1.1");
requesterData.setRequesterIPAddress("9.53.52.65");
// Print requester configuration items
System.out.println("authentication method for requester is: "+
requesterData.getAuthenticationMethod());
System.out.println("confirmation method for requester is: "+
requesterData.getConfirmationMethod());
System.out.println("key alias for requester is: "+
requesterData.getKeyAliasForRequester());
System.out.println("key alias for recipient as set in requester config is "+
requesterData.getKeyAliasForAppliesTo());
System.out.println("holder of key confirmation key type is: "+
Requester
Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));
// Get an instance of the Credential config object
CredentialConfig cred = samlFactory.newCredentialConfig (); cred.setRequesterNameID("Alice");
// Set some user attributes
ArrayList<SAMLAttribute> userAttrs = new ArrayList<SAMLAttribute>();
SAMLAttribute anAttribute = new SAMLAttribute("EmployeeInfo",
new String[] {"GreenRoofing","JohnDoe", "19XY981245"},
null, "WebSphere Namespace", null, "JohnDoeInfo " );
userAttrs.add(anAttribute);
cred.setSAMLAttributes(userAttrs);
// Get default provider configuration
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer"); System.out.println("time to live from the default provider config: "+
samlIssuerCfg.getTimeToLive());
System.out.println("keyStore path from default provider config: "+
samlIssuerCfg.getKeyStoreConfig().getPath());
System.out.println("keyStore type from default provider config: "+
samlIssuerCfg.getKeyStoreConfig().getType());
System.out.println("key alias from default provider config: "+
samlIssuerCfg.getKeyInformationConfig().getAlias());
// Generate the SAML token
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, requesterData, samlIssuerCfg);
System.out.println("token's creation Date is:
"+((SAMLToken)samlToken).getSamlCreated().toString());
System.out.println("token's expiration Date is:
"+((SAMLToken)samlToken).getSamlExpires().toString());
System.out.println("token's subject confirmation method is:
"+((SAMLToken)samlToken).getConfirmationMethod());
// Create a Subject, mapping the name identifier in the token to a user
// in the user registry to obtain the Principal name
Subject subject = samlFactory.newSubject((SAMLToken)samlToken);
// Retrieve attributes from the token
List<SAMLAttribute> allAttributes =
((SAMLToken) samlToken).getSAMLAttributes();
// Iterate through the attributes and process accordingly
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while (iter.hasNext()) {
SAMLAttribute attribute = iter.next();
String attributeName = attribute.getName();
String[] attributeValues = attribute.getStringAttributeValue();
System.out.println("attribute name = "+ attributeName +
" attribute value = ["+
attributeValues[0]+ ",
"+attributeValues[1]+ ", "+
attributeValues[2]+"]");
}
} catch(Exception e) {
e.printStackTrace();
}
}
}
サンプル・コード出力
default holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
authentication method for requester is: Password
confirmation method for requester is: holder-of-key
key alias for requester is: null
key alias for recipient as set in requester config is SOAPRecipient
holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
time to live from the default provider config: 3600000
keyStore path from default provider config: C:/saml/samlsample/saml-provider.jceks
keyStore type from default provider config: jceks
key alias from default provider config: samlissuer
token's creation Date is: Mon Sep 14 15:49:00 CDT 2009
token's expiration Date is: Mon Sep 14 16:49:00 CDT 2009
token's subject confirmation method is: urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
attribute name = EmployeeInfo attribute value = [GreenRoofing, JohnDoe, 19XY981245]