8 SAML API
WebLogic ServerはSAML 2.0をサポートしています。WebLogic Server実装では、以下がサポートされます。
-
SAML 2.0のWeb SSOプロファイルのHTTP POST、HTTPアーティファクトおよびHTTPリダイレクト・バインディングをサポートします。
-
SAML認証文とSAML属性文(SAML認可文はサポートされません)
WebLogic Server環境でのSAMLおよびSAMLアサーションの概要については、Oracle WebLogic Serverのセキュリティの理解のSecurity Assertion Markup Language (SAML)に関する項を参照してください。
SAML資格証明マッピング・プロバイダの構成の詳細は、『Oracle WebLogic Serverセキュリティの管理』のSAML 2.0のためのSAML 2.0資格証明マッピング・プロバイダの構成に関する項を参照してください。
SAML仕様については、http://www.oasis-open.orgを参照してください。『Security Assertion Markup Language (SAML) 2.0 Technical Overview』(http://www.oasis-open.org/committees/download.php/11511/sstc-saml-tech-overview-2.0-draft-03.pdf)も参照してください。
この章の内容は以下のとおりです。
SAML APIの説明
WebLogic ServerでSAMLを実装するのに使用できるWebLogic SAML APIについて学習します。
表8-1に、WebLogic SAML API 2.0の一覧を示します。詳細についてはJavadocを参照してください。
表8-1 WebLogic SAML 2.0 API
| WebLogic SAML 2.0 API | 説明 |
|---|---|
|
WebLogicセキュリティ・レルムでSAML 2.0セキュリティ・プロバイダを構成、制御、およびモニターするためのインタフェースとクラスを提供します。 |
|
|
SAML 2.0 Assertion AttributeStatementの1つの属性を表すクラス。 |
|
|
SAML 2.0アサーションのAttributeStatementを表すクラス。 |
|
|
サブジェクトからSAML 2.0 Assertionの属性へのマッピングを実行するためのインタフェース。 |
|
|
ユーザーとグループの情報をSAML 2.0アサーションにマッピングするために使用するインタフェース。 |
|
|
SAML 2.0属性文から属性プリンシパルへのマッピングを実行するためのインタフェース。 |
|
|
SAML 2.0アサーションに格納されたユーザー情報をローカル・ユーザー名にマップするために使用するインタフェース。 |
|
|
SAML 2.0アサーションに格納されたユーザー名とグループ情報を表すために使用します。 |
|
|
SAML 2.0 IDプロバイダおよびサービス・プロバイダ・パートナとメタデータの抽象インタフェース。 |
|
|
バインディング・クライアント・パートナとは、バックエンド・チャネルの通信をサポートするパートナ。 |
|
|
SAML 2.0 IDプロバイダ・パートナの抽象表現。 |
|
|
SAML 2.0サービス・エンドポイントの抽象表現。 |
|
|
このクラスは、アーティファクト解決サービスのエンド・ポイントのように索引化可能なエンド・ポイントを表します。 |
|
|
メタデータ・パートナは、主にSAML 2.0メタデータ・プロファイルで必要なパートナの連絡先情報を格納します。 |
|
|
SAML 2.0パートナの抽象表現。このインタフェースはパートナの必須情報を定義します。 |
|
|
SAML 2.0サービス・プロバイダ・パートナの抽象表現。 |
|
|
Web SSOプロファイルのSAML 2.0 IDプロバイダ・パートナの抽象表現。 |
|
|
Web SSOプロファイルのSAML 2.0パートナの抽象表現。 |
|
|
Web SSOプロファイルのSAML 2.0サービス・プロバイダ・パートナの抽象表現。 |
|
|
WSS SAMLトークン・プロファイルのSAML 2.0 IDプロバイダ・パートナの抽象表現。 |
|
|
WSS SAMLトークン・プロファイルのSAML 2.0パートナの抽象表現。 |
|
|
WSS SAMLトークン・プロファイルのSAML 2.0サービス・プロバイダ・パートナの抽象表現。特定の属性やメソッドはありません。 |
SAML SSO属性サポートの構成
SAMLアサーションとは、サブジェクト上で実行された認可操作、サブジェクトの属性情報、または特定のリソースについてサブジェクトに適用している認可データのいずれかに関して、SAML認証局によって作成されたデータです。SAML 2.0で使用するSAML SSO属性を構成できます。
この節では、以下のトピックについて説明します。
SAML SSO属性とは
SAMLの仕様(http://www.oasis-open.orgを参照)では、特定のサブジェクトに関する不特定の追加情報をSAMLパートナ間でアサーション内の属性文としてやり取りすることが許可されています。そのため、SAML属性アサーションとは、サブジェクトの属性に関してサイトが決定した情報を伝達する特定のタイプのSAMLアサーションということになります。
SAML 2.0の資格証明マッピング・プロバイダとIDアサーション・プロバイダのメカニズムでは、SAMLアサーションに書き込まれる追加の属性(グループ情報以外)を取得し、着信SAMLアサーションから属性をマップできるカスタム属性マッパーの使用がサポートされます。
これを実行するには:
-
(SAML IDプロバイダ・サイト上の)SAML資格証明マッパーは、このカスタム属性マッパーの存在に基づいて属性をパッケージする方法を決定します。
-
(SAML サービス・プロバイダ・サイト上の)SAML IDアサーション・プロバイダは、このカスタム名前マッパーの構成に基づいて属性を取得する方法を決定します。
-
Javaサブジェクトは、アサーションから取得された属性をアプリケーションで使用できるようにするために使用されます。これには、SAML認証プロバイダが構成され、仮想ユーザーがSAMLパートナ上で有効化されている必要があります。
必須のSAML 2.0基本属性プロファイル
SAML 1.1では、SAML属性の名前フォーマットを規定していません。
ただし、SAML 2.0基本属性プロファイルのみはSAML 2.0でサポートされています。SAML2AttributeInfoでurn:oasis:names:tc:SAML:2.0:attrname-format:basic名前フォーマットを持つ属性のみが、SAML 2.0アサーションに書き込まれます。
urn:oasis:names:tc:SAML:2.0:attrname-format:basic名前フォーマットはデフォルトなので、設定する必要はありません。
名前フォーマットをどうしても設定する場合、次に示すようにSAML2.AttributeInfo.setAttributeNameFormatメソッドでurn:oasis:names:tc:SAML:2.0:attrname-format:basicを指定する必要があります。
SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);複数の属性のSAML資格証明マッパーへの受け渡し
構成された属性マッパーが呼び出されると、Collection<SAML2AttributeStatementInfo>が返されます。複数の属性文を指定できます。それぞれの属性文には複数の属性が含まれ、それぞれの属性には複数の属性値が含まれる可能性があります。
この実行例は次のとおりです。
private Collection<SAML2AttributeStatementInfo> getAttributeStatementInfo(
Subject subject, ContextHandler handlers) {
Collection<SAML2AttributeInfo> attrs = new ArrayList<SAML2AttributeInfo>();
SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);
ArrayList<String> v = new ArrayList<String>();
v.add("Value1OfAttributeWithMultipleValue");
v.add("Value2OfAttributeWithMultipleValue");
v.add("Value3OfAttributeWithMultipleValue");
SAML2AttributeInfo attrInfo1 = new SAML2AttributeInfo(
"AttributeWithMultipleValue", v);
attrInfo1.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo1);
SAML2AttributeInfo attrInfo2 = new SAML2AttributeInfo(
"AttributeWithInvalidNameFormat",
"ValueOfAttributeWithInvalidNameFormatValue");
attrInfo2.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified");
attrs.add(attrInfo2);
SAML2AttributeInfo attrInfo3 = new SAML2AttributeInfo(
"AttributeWithNullValue", "null");
attrInfo3.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo3);
:
:
Collection<SAML2AttributeStatementInfo> attrStatements = new ArrayList<SAML2AttributeStatementInfo>();
attrStatements.add(new SAML2AttributeStatementInfo(attrs));
attrStatements.add(new SAML2AttributeStatementInfo(attrs1));
return attrStatements;
}SAML属性を実装する方法
この項では、SAML属性を実装するためにたどるプロセスを段階を踏んで説明します。
ノート:
この項では、使用する例にSAML 2.0インタフェース名を使用します。
SAML資格証明マッピング(IDプロバイダ)サイトから、
-
SAML2AttributeInfoおよびSAML2AttributeStatementInfoクラスをインスタンス化します。SAML2CredentialAttributeMapperインタフェースを実装します。また、同一の実装で
SAML2CredentialNameMapperインタフェースを実装します。(SAML2CredentialAttributeMapperおよびSAML2CredentialNameMapperインタフェースは、両方とも同一の実装内に存在する必要があります。)SAML2CredentialNameMapperインタフェースを実装すると、WebLogicリモート・コンソールを使用して、NameMapperClassName属性をSAML2CredentialAttributeMapperインスタンスのクラス名に設定できます。 -
WebLogicリモート・コンソールを使用して、新しいカスタム属性マッパーを識別するためにSAML資格証明マッピング・プロバイダの
NameMapperClassName属性を使用して、SAMLプロバイダ上または各パートナ上で新しいカスタム属性マッパーを構成します。「コンソールでカスタムSAML資格証明属性マッパーのクラスを使用可能にする」を参照してください。 -
SAML資格証明マッピング・プロバイダは、構成済のカスタム名マッパーが属性マッピング・インタフェースの実装であるかどうかを判定します。実装である場合、このプロバイダはカスタム属性マッピング・インタフェースを呼び出し、生成されたSAMLアサーションに書き込むための属性値を取得します。
-
SAML資格証明マッピング・プロバイダは、カスタム属性マッパーから取得された属性名または属性値を検証しません。
NULL以外の属性名を持つ任意の属性がSAMLアサーションの属性文に書き込まれます。NULLまたは空の属性名を持つ属性は無視され、次の属性が処理されます。
属性に複数の値が含まれる場合、各値はSAML属性文で単一の
<Attribute>の<AttributeValue>要素として表示されます。SAML 2.0の場合、NULLまたは空の属性値はアサーションおよび『OASIS SAML V2.0用プロトコル2005年3月』 (
http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf)に基づいて処理されます。urn:oasis:names:tc:SAML:2.0:attrname-format:basic以外の名前フォーマットを持つ属性はスキップされます。
SAML IDアサーション(サービス・プロバイダ)サイトから:
SAML 2.0属性インタフェースの例
この項では、追加属性をSAMLアサーションに書き込めるようにするSAML 2.0属性インタフェースの実装例を説明します。
カスタムSAML 2.0資格証明属性マッパーの例
例8-1は、SAML2CredentialNameMapperインタフェースおよびSAML2CredentialAttributeMapperインタフェースの両方を実装する単一クラスの例を示します。
例8-1 SAML 2.0資格証明属性マッパー
public class CustomSAML2CredentialAttributeMapperImpl implements
SAML2CredentialNameMapper, SAML2CredentialAttributeMapper {
private String nameQualifier = null;
public Collection<SAML2AttributeStatementInfo> mapAttributes(
Subject subject, ContextHandler handler) {
return getAttributeStatementInfo(subject, handler);
}
/**
* same as SAML2NameMapperImpl
*/
public SAML2NameMapperInfo mapName(String name, ContextHandler handler) {
System.out
.println("CustomSAML2CredentialAttributeMapperImpl:mapName: Mapped name: qualifier: "
+ nameQualifier + ", name: " + name);
return new SAML2NameMapperInfo(nameQualifier, name, null);
}
/**
* same as SAML2NameMapperImpl
*/
public synchronized void setNameQualifier(String nameQualifier) {
this.nameQualifier = nameQualifier;
}
/**
* same as SAML2NameMapperImpl
*/
public SAML2NameMapperInfo mapSubject(Subject subject,
ContextHandler handler) {
// Provider checks for null Subject...
Set subjects = subject.getPrincipals(WLSUser.class);
Set groups = subject.getPrincipals(WLSGroup.class);
String userName = null;
Set<String> groupStrings = new java.util.HashSet();
if (subjects == null || subjects.size() == 0) {
System.out
.println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: No valid WLSUser pricipals found in Subject, returning null");
return null;
}
if (groups == null || groups.size() == 0) {
System.out
.println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: No valid WLSGroup pricipals found in Subject, continuing");
}
else{
java.util.Iterator<WLSGroup> it = groups.iterator();
while(it.hasNext()){
WLSGroup wg = it.next();
groupStrings.add(wg.getName());
}
}
if (subjects.size() != 1) {
System.out
.println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: More than one WLSUser principal found in Subject, taking first user only");
}
userName = ((WLSUser) subjects.iterator().next()).getName();
if (userName == null || userName.equals("")) {
System.out
.println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: Username string is null or empty, returning null");
return null;
}
// Return mapping information...
System.out
TRACE.info("CustomSAML2CredentialAttributeMapperImpl:mapSubject: Mapped subject: qualifier: "
+ nameQualifier
+ ", name: "
+ userName
+ ", groups: "
+ groups);
SAML2NameMapperInfo saml2NameMapperInfo = new
SAML2NameMapperInfo(nameQualifier, userName, groupStrings);
//SAML2NameMapperInfo saml2NameMapperInfo = new
SAML2NameMapperInfo(nameQualifier, userName, groups);
return new SAML2NameMapperInfo(nameQualifier, userName, groups);
}
private Collection<SAML2AttributeStatementInfo> getAttributeStatementInfo(
Subject subject, ContextHandler handlers) {
Collection<SAML2AttributeInfo> attrs = new ArrayList<SAML2AttributeInfo>();
SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);
ArrayList<String> v = new ArrayList<String>();
v.add("Value1OfAttributeWithMultipleValue");
v.add("Value2OfAttributeWithMultipleValue");
v.add("Value3OfAttributeWithMultipleValue");
SAML2AttributeInfo attrInfo1 = new SAML2AttributeInfo(
"AttributeWithMultipleValue", v);
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo1);
:
:
Collection<SAML2AttributeStatementInfo> attrStatements = new ArrayList<SAML2AttributeStatementInfo>();
attrStatements.add(new SAML2AttributeStatementInfo(attrs));
attrStatements.add(new SAML2AttributeStatementInfo(attrs1));
return attrStatements;
}
}
「コンソールでカスタムSAML資格証明属性マッパーのクラスを使用可能にする」で説明されているように、WebLogicリモート・コンソールを使用して、ユーザー名マッパー・クラス名をこのマッパー実装の完全修飾クラス名に構成します。
カスタム・マッパー実装によって返されたSAML2AttributeStatementInfoオブジェクトのコレクションでカプセル化された属性は、SAML 2.0資格証明マッピング・プロバイダによって生成されたアサーションに含まれます。
カスタムSAML 2.0 IDアサーション・プロバイダ属性マッパー
例8-2は、SAML2IdentityAsserterNameMapperおよびSAML2IdentityAsserterAttributeMapperの実装例を示します。
例8-2 カスタムSAML 2.0 IDアサーション・プロバイダ属性マッパー
public class CustomSAML2IdentityAsserterAttributeMapperImpl implements
SAML2IdentityAsserterNameMapper, SAML2IdentityAsserterAttributeMapper {
/**
* same as SAML2NameMapperImpl
*/
public String mapNameInfo(SAML2NameMapperInfo info, ContextHandler handler) {
// Get the user name ...
String userName = info.getName();
System.out
.println("CustomSAML2IdentityAsserterAttributeMapperImpl:mapNameInfo: returning name: "
+ userName);
return userName;
}
}
:
:
public Collection<Object> mapAttributeInfo0(
Collection<SAML2AttributeStatementInfo> attrStmtInfos,
ContextHandler contextHandler) {
if (attrStmtInfos == null || attrStmtInfos.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: attrStmtInfos has no elements");
return null;
}
Collection<Object> customAttrs = new ArrayList<Object>();
for (SAML2AttributeStatementInfo stmtInfo : attrStmtInfos) {
Collection<SAML2AttributeInfo> attrs = stmtInfo.getAttributeInfo();
if (attrs == null || attrs.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: no attribute in statement: "
+ stmtInfo.toString());
} else {
for (SAML2AttributeInfo attr : attrs) {
if (attr.getAttributeName().equals("AttributeWithSingleValue")){
CustomPrincipal customAttr1 = new CustomPrincipal(attr
.getAttributeName(), attr.getAttributeNameFormat(),
attr.getAttributeValues());
customAttrs.add(customAttr1);
}else{
String customAttr = new StringBuffer().append(
attr.getAttributeName()).append(",").append(
attr.getAttributeValues()).toString();
customAttrs.add(customAttr);
}
}
}
}
return customAttrs;
}
public Collection<Principal> mapAttributeInfo(
Collection<SAML2AttributeStatementInfo> attrStmtInfos,
ContextHandler contextHandler) {
if (attrStmtInfos == null || attrStmtInfos.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: attrStmtInfos has no elements");
return null;
}
Collection<Principal> pals = new ArrayList<Principal>();
for (SAML2AttributeStatementInfo stmtInfo : attrStmtInfos) {
Collection<SAML2AttributeInfo> attrs = stmtInfo.getAttributeInfo();
if (attrs == null || attrs.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: no attribute in statement: "
+ stmtInfo.toString());
} else {
for (SAML2AttributeInfo attr : attrs) {
CustomPrincipal pal = new CustomPrincipal(attr
.getAttributeName(), attr.getAttributeNameFormat(),
attr.getAttributeValues());
pals.add(pal);
}
}
}
return pals;
}
SAML 2.0 IDアサーション・プロバイダは、SAMLアサーションから取得した属性をサブジェクトを介してコンシューマで使用できるようにします。
「コンソールでカスタムSAML IDアサーション・プロバイダ・クラスを使用可能にする」で説明されているように、WebLogicリモート・コンソールを使用して、ユーザー名マッパー・クラス名をこのマッパー実装の完全修飾クラス名に構成します。
仮想ユーザーがSAMLでログインすることを許可している場合は、SAML認証プロバイダのインスタンスを作成して構成する必要があります。「SAML認証プロバイダの構成」を参照してください。
仮想ユーザーが有効化しており、SAML認証プロバイダが構成されている場合、カスタム属性マッパーによって返される属性がサブジェクトに追加されます。
マッパーから返された属性は、マッピングされた属性のクラス・タイプに応じて、サブジェクト・プリンシパルまたはプライベートな資格証明として保存されます。具体的には、マッパーがPrincipalオブジェクトのコレクションを返す場合、マッピングされた属性はサブジェクト・プリンシパル設定に保存されます。それ以外の場合、サブジェクトのプライベートな資格証明の設定は、マッピングされた属性を伝達するために使用されます。コード例では、両方のアプローチが示されています。
アプリケーション・コードは、サブジェクトに追加される属性を示すためにマッパーが使用するオブジェクトのクラス・タイプに関する情報を取得する必要があります。アプリケーションは、顧客属性マッパーが属性の表示に使用するクラス・タイプが付与されると、サブジェクトのプライベートな資格証明またはプリンシパルの設定からSAML属性を取得できます。
コンソールでカスタムSAML資格証明属性マッパーのクラスを使用可能にする
SAML資格証明マッピング・プロバイダがSAML2CredentialAttributeMapper (SAML 2.0)インスタンスを使用するには、WebLogicリモート・コンソールを使用して既存のNameMapperClassName属性をこのSAML2CredentialAttributeMapperインスタンスのクラス名に設定します。
つまり、WebLogicリモート・コンソールの名前マッパー・クラス名属性のフィールドを使用して、アクティブ・セキュリティ・レルムでSAML2CredentialAttributeMapperインスタンスのクラス名を指定します。
WebLogic SAML資格証明マッピング・プロバイダを使用してカスタム・ユーザー名マッパーを使用するには、次の手順を実行します。
- WebLogicリモート・コンソールで、「ツリーの編集」、「セキュリティ」、「レルム」、myRealm、「資格証明マッパー」の順に移動し、SAML資格証明マッピング・バージョン2プロバイダの名前を選択します。
- 「SAML資格証明マッパーV2パラメータ」タブの「名前マッパーのクラス名」フィールドで、
SAML2CredentialAttributeMapperの実装のクラス名を入力します。クラス名はシステムのクラスパスに存在する必要があります。 - 「保存」をクリックします。
コンソールでカスタムSAML IDアサーション・プロバイダ・クラスを使用可能にする
SAML IDアサーション・プロバイダがこのSAML2IdentityAsserterAttributeMapper (SAML 2.0)インスタンスを使用するには、WebLogicリモート・コンソールを使用して、既存のNameMapperClassName属性をこのSAML2IdentityAsserterAttributeMapperインスタンスのクラス名に設定します。
つまり、名前マッパー・クラス名属性のコンソール制御を使用して、アクティブ・セキュリティ・レルムでSAML2IdentityAsserterAttributeMapperインスタンスのクラス名を指定します。
WebLogic SAML IDアサーション・プロバイダを使用してカスタム・ユーザー名マッパーを使用するには:
- WebLogicリモート・コンソールで、「ツリーの編集」、「セキュリティ」、「レルム」、myRealm、「認証プロバイダ」の順に移動し、SAML IDアサーション・プロバイダ・バージョン2プロバイダの名前を選択します。
- 「SAML IDアサーション・プロバイダV2パラメータ」タブの「名前マッパー・クラス名」フィールドに、
SAML2IdentityAsserterAttributeMapper実装のクラス名を入力します。クラス名はシステムのクラスパスに存在する必要があります。 - 「保存」をクリックします。