カスタム認証アクションの実装

11.1 カスタム認証アクションの理解

Oracle Access Management Identity Federationサーバー(Identity Federation)は、前処理および後処理のアクション・プラグインを使用してカスタム・アクションを実装します。前処理および後処理のプラグインは、フェデレーション・シングル・サインオン(SSO)フロー時に、Oracle Access Managerの呼出しの前または後に呼び出されるJSPまたはJavaEEサーブレットとして実装されます。次の各項では、アクションのしくみと、Identity Federationとの相互作用の方法について説明します。

11.1.1 前処理および後処理カスタム認証アクションの使用

アイデンティティ・プロバイダ(IdP)として動作するIdentity Federationは、Federation SSO operation時に常にOracle Access Managerを呼び出します。これは、ユーザーの識別、または、ユーザーがすでに認証されている場合は、ユーザーのセッションの確認のために行われます。Identity Federationがユーザーの識別が必要と判断した場合、ユーザーは、ルート・コンテキストとOAMエンドポイントの相対パスを指定して、Oracle Access Managerに転送されます。このとき、Oracle Access Managerは次のことを行います。

必要に応じて認証操作を実行します。
ユーザーのセッションの有効性を確認します
(オプション)認証検証を実行して、ユーザーがSP Partnerを使用してフェデレーションSSO操作を実行できることを確認します。

これらの操作が成功した場合、Oracle Access Managerはユーザーを認証情報(ユーザー識別子とアイデンティティが確認された時刻)とともにIdentity Federationに転送して戻します。Identity Federationが情報を分析し、ユーザー・セッションを作成または更新します。カスタム・アクションは、この相互作用時に、次のことに使用できます。

Identity FederationとOracle Access Manager認証エンジンの間で交換されるデータを操作する。たとえば、ユーザー名から電子メール・アドレスを構成できます。johndoeは、johndoe@mycompany.comになります。
認証時に追加の手順を実行する。たとえば、ユーザーに関する情報をさらに得るために、外部のデータソースまたはシステムに接続できます。

11.1.2 カスタム認証アクション・プラグインの設定

次の概要に、カスタム・アクション・プラグインの設定方法を示します。

説明に従って、1つ以上のカスタム・アクション・プラグインを実装します。
- Oracle Access Managerの呼出し前に実行される前処理アクション・プラグインを実装します。(「前処理カスタム・アクションの使用」を参照してください。)
- なんらかのアクションまたは変更を認証の後で実行するには、後処理プラグインを実装します。これは、ユーザーがOracle Access ManagerからIdentity Federationに戻されるときに発生します。(「後処理カスタム・アクションの使用」を参照してください。)
Oracle Access Managerが実行されているWebLogic管理対象サーバーにプラグインをデプロイします。
実装するプラグイン・タスクに基づいて、Identity Federationを構成します。
- プラグインが前処理タスクを実行する場合、Identity Federationを構成して、プラグイン(Oracle Access Managerでなく)を呼び出します。
- プラグインが後処理タスクを実行する場合、Identity Federationを構成して、Oracle Access Managerがプラグインを呼び出すようにします(Identity Federationにリダイレクトするのでなく)。

11.1.3 カスタム・アクション・フローの理解

Identity Federationがユーザーを認証する必要がある場合のフローは次のとおりです。

Identity Federationは、ランタイムIdP SSOフローの一部として、次の判断を下します。
- ユーザーが、Oracle Access Managerによってローカルに認証される必要があるかどうか。
- ユーザーが既存のセッションを持ち、Oracle Access Managerに転送されてセッションの有効性を確認する必要があるかどうか。
Identity Federation (IdPとして動作)は、前処理プラグインを呼び出して、適用できるカスタム・タスクを実行します。
前処理プラグインがOracle Access Managerを呼び出します。
Oracle Access Managerは、ユーザーをチャレンジおよび認証するか、ユーザーのセッションの有効性を確認します。
Oracle Access Managerは、認証データをバンドルし、後処理プラグインを呼び出して、適用できるカスタム・タスクを実行します。
後処理プラグインは、認証データを提供して、Identity Federationを呼び出します。
Identity Federation(IdPとして動作)が、操作を再開します。

図11-1は、Identity Federationがカスタマイズされ、次の時期にプラグインを呼び出すように構成されている場合のこのフローの説明です。

Identity Federationが認証またはセッション検証のためにOracle Access Managerを呼び出す前。(「前処理カスタム・アクションの使用」を参照してください。)
Oracle Access Managerが認証またはセッション検証の後にIdentity Federationを呼び出す前。(「後処理カスタム・アクションの使用」を参照してください。)

図11-1 カスタム・アクション・プラグイン・フロー

「図11-1 カスタム・アクション・プラグイン・フロー」の説明

11.2 前処理カスタム・アクションの使用

前処理プラグインは、認証操作の一環として、Oracle Access Managerを呼び出す前にユーザーがリダイレクトされるモジュールです。このプラグインにより、認証前にカスタム・アクションを実行することが可能になります。プラグインの使用時には、Identity Federationはユーザーを認証エンジンにリダイレクトしません。かわりに、ユーザーをプラグインに内部的に転送し、認証中に使用する特定のデータをプラグインに渡します。カスタム・アクションの実行後、プラグインはIdentity Federationによって提供された元のデータとともに、認証フローを再開するように、ユーザーをOracle Access Managerに転送します。次の各項では、詳細を説明します。

11.2.1 前処理プラグインへのデータの引渡し

前処理カスタム・アクションは、Identity Federationと相互作用します。Identity Federationは、ユーザーをOracle Access Managerにリダイレクトするときに、HttpServletRequestオブジェクトの属性として、特定のデータをエンジンに渡します。前処理プラグインでも同じデータを使用できる必要があります。データには次のものが含まれます。

ユーザーにチャレンジするために使用されるデフォルト・スキーム識別子。この文字列は、oracle.security.fed.authn.defaultschemeidとして識別されます。
ユーザーにチャレンジするために使用される、サービス・プロバイダ(SP)が要求するスキーム識別子のリスト。この文字列リストは、oracle.security.fed.authn.schemeidlevelsとして識別されます。
スキーム識別子のリストがあるときに、ユーザーにチャレンジするスキームを決定する、SPによって要求される比較ルール。これは、oracle.security.fed.authn.schemeidcompとして識別される文字列です。
ユーザーがすでに認証済でもOracle Access Managerがユーザーをチャレンジすべきかどうかを示す強制認証フラグ。これは、oracle.security.fed.authn.forceauthnとして識別されるブール値です。指定されていない場合、falseとみなされます。
Oracle Access Managerがユーザーと視覚的に対話可能かどうかを示すパッシブ・フラグ。これは、oracle.security.fed.authn.passiveとして識別されるブール値です。指定されていない場合、falseとみなされます。
実行されているアクションを参照する識別子。この文字列は、oracle.security.fed.authn.refidとして識別されます。
設定されている場合のユーザーの識別子(userID)。この文字列は、oracle.security.fed.authn.useridとして識別されます。
設定されている場合、ユーザーの正規ユーザー識別名(userID + アイデンティティ・ストア名 + LDAP DN)。この文字列は、oracle.security.fed.authn.canonicaluseridとして識別されます。
設定されている場合、Identity Federation SessionID。この文字列は、oracle.security.fed.sessionidとして識別されます。
ユーザーの認証に使用するOracle Access Managerサーバーを参照する識別子。この文字列は、oracle.security.fed.authn.engineidとして識別されます。
フェデレーションされたSSO処理が行われている場合は、このローカル認証をリクエストしているリモートSPのパートナ名と説明。この文字列は、それぞれoracle.security.fed.authn.provideridとoracle.security.fed.authn.providerdescriptionとして識別されます。
Oracle Access Managerによる認証の後でユーザーがリダイレクトされるはずのWebコンテキスト。この文字列は、oracle.security.fed.return.webcontextとして識別されます。ルートWebコンテキストは、/oamです。
Oracle Access Managerによる認証の後でユーザーがリダイレクトされるはずのWeb相対パス。この文字列は、oracle.security.fed.return.webpathとして識別されます。相対パスは、/server/fed/authnです。

注意:

前処理プラグインは、HttpServletRequestオブジェクトに設定されている、次のものを除くすべての属性を変更できます。

oracle.security.fed.authn.defaultschemeid
oracle.security.fed.authn.schemeidlevels
oracle.security.fed.authn.schemeidcomp
oracle.security.fed.authn.refid
oracle.security.fed.authn.engineid
oracle.security.fed.return.webcontext
oracle.security.fed.return.webpath

11.2.2 前処理アクション用のIdentity Federationの構成

次の作業を実行することにより、ユーザーを前処理プラグインに転送するようにIdentity Federationを構成します。

WLST環境を入力します。

$IAM_HOME/common/bin/wlst.sh
WLS管理サーバーに接続します。

connect()
Domain Runtimeフォルダに移動します。

domainRuntime()
putStringProperty() WLSTコマンドを実行して次のプロパティを設定します。
- preauthnenginewebcontextプロパティは、カスタムJSPページまたは前処理プラグインのサーブレットが存在するWebコンテキストを参照します。CUSTOM_WEB_CONTEXTを、プラグインに固有の値で置き換えます。
  
  putStringProperty("/authnengines/preauthnenginewebcontext", "CUSTOM_WEB_CONTEXT ")
- preauthnenginewebpathプロパティは、前処理プラグインが存在するWebコンテキストにおけるパスを参照します。CUSTOM_WEB_PATHを、プラグインに固有の値で置き換えます。
  
  putStringProperty("/authnengines/preauthnenginewebpath", "CUSTOM_WEB_PATH")
putBooleanProperty() WLSTコマンドを実行して、前処理カスタム・プラグインを有効または無効にします。
- 前処理プラグインを呼び出すようにIdentity Federationを構成するには、putBooleanProperty("/authnengines/preauthnengineenabled", "true")
- 前処理プラグインを呼び出さないようにIdentity Federationを構成するには、putBooleanProperty("/authnengines/preauthnengineenabled", "false")

11.3 例: カスタム・アクションの前処理

この項では、ユーザーがOracle Access Managerにリダイレクトされる前に、Identity Federationにより呼び出される単純な前処理プラグインを示します。この前処理プラグインは、フェデレーションSSO操作が実行されるSPパートナの名前を取得して、カスタム・ページ(たとえば、カスタム・エラー・ページ)が使用できるカスタムCookieに保存します。この例の内容は次のとおりです。

Identity FederationがIdPとして動作している場合
この例ではカスタム認証前プラグインが、SPパートナ名を含むCookieを設定するためｎに使用されます。Cookieは、fed-sppartner-cookieと呼ばれます。

前処理プラグインは、ルート・コンテキストが/pluginに設定されたWebアプリケーションから構成されています。これは、SPパートナ名をCookieに設定する1つのJSPページ(名前はcookiepartnerset.jsp)を含みます。cookiepartnerset.jspはcookiepartnerset.jspの実装例です。

cookiepartnerset.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*, javax.naming.*, 
  javax.naming.directory.*, java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
String partnerName = (String)request.getAttribute
  ("oracle.security.fed.authn.providerid");
 
Cookie cookie = new Cookie("fed-sppartner-cookie", partnerName);
response.addCookie(cookie);
 
// forward to the OAM server to resume the flow
request.getSession().getServletContext().getContext("/oam").getRequestDispatcher
 ("/server/fed/authn").forward(request, response);
%>

注意:

このWebアプリケーションのWARファイルは、Oracle Access Managerが実行されているWLS管理対象サーバーにデプロイする必要があります。

フローを再開するために、プラグインは、ユーザーを内部転送によりOracle Access Managerにリダイレクトします。前処理プラグインを呼び出すようにIdentity Federationを構成するには、次の手順を実行します。

WLST環境を入力します。

$IAM_HOME/common/bin/wlst.sh
WLS管理サーバーに接続します。

connect()
Domain Runtimeフォルダに移動します。

domainRuntime()
putStringProperty() WLSTコマンドを実行してpreauthnenginewebcontextプロパティを設定します。

putStringProperty("/authnengines/preauthnenginewebcontext", "/plugin")
putStringProperty() WLSTコマンドを実行してpreauthnenginewebpathプロパティを設定します。

putStringProperty("/authnengines/preauthnenginewebpath", "/cookiepartnerset.jsp")
putBooleanProperty() WLSTコマンドを実行して、Identity Federationが前処理プラグインを起動できるようにします。

putBooleanProperty("/authnengines/preauthnengineenabled", "true")

11.4 後処理カスタム・アクションの使用

Oracle Access Manager認証エンジンが処理を完了した後、ユーザーがIdentity Federationにリダイレクトされる前に、ユーザーは認証操作の一環として後処理プラグイン・モジュールにリダイレクトされます。このプラグインにより、認証後にカスタム・アクションを実行することが可能になります。

後処理プラグインが使用中のとき、Oracle Access Managerはそれに対して内部的にユーザーおよび認証データを転送します。カスタム・アクションの実行後、プラグインは認証データとともにユーザーをIdentity Federationに戻します。プラグインは、認証フローの一環としてプラグインに渡されたデータ(すなわちHttpServletRequestオブジェクトに設定されている属性)をIdentity Federationに提供する必要があります。次の各項で詳しく説明します。

11.4.1 後処理プラグインへのデータの引渡し

後処理プラグインは、Identity Federationと相互作用します。Oracle Access ManagerはユーザーをIdentity Federationにリダイレクトするときに、HttpServletRequestオブジェクトの属性として、特定のデータをプラグインに渡します。データには次のものが含まれます。

実行された要求済アクションを参照する識別子。文字列は、oracle.security.fed.authn.refidとして識別されます。
Oracle Access Managerによって実行された認証のschemeIDとレベル。文字列は、oracle.security.fed.authn.result.schemeidlevelとして識別されます。
認証操作の結果。操作が成功した場合、文字列はoracle.security.fed.authn.result.statuscodeによりSUCCESSとして識別されます。
フェデレーションされたSSO処理が行われている場合は、このローカル認証をリクエストしているリモートSPのパートナ名。文字列は、oracle.security.fed.authn.provideridとして識別されます。
ユーザーを認証するために使用されるOracle Access Managerモジュール識別子。文字列は、oracle.security.fed.authn.engineidとして識別されます。
ユーザーの正規識別名(userID + アイデンティティ・ストア名 + LDAP DN)。文字列は、oracle.security.fed.authn.useridとして識別されます。
認証時刻。日付は、oracle.security.fed.authn.authntimeとして識別されます。
認証済セッションの有効期限。日付は、oracle.security.fed.authn.expirationtimeとして識別されます。
ユーザーのOracle Access Manager SessionID。文字列は、oracle.security.fed.authn.oamsessionidとして識別されます。
ユーザーのOracle Access Managerセッション・タイプ。文字列は、oracle.security.fed.authn.oamsessiontypeとして識別されます。
設定されている場合、Identity Federation SessionID。文字列は、oracle.security.fed.sessionidとして識別されます。

注意:

プラグインは、HttpServletRequestオブジェクトに設定されているすべての属性(次のものを除く)を変更できます。

oracle.security.fed.authn.result.schemeidlevel
oracle.security.fed.authn.engineid
oracle.security.fed.authn.oamsessionid
oracle.security.fed.authn.oamsessiontype
oracle.security.fed.sessionid

カスタム後処理プラグインは、これらのオプションの要素を追加できます。

SAML属性として送信SAMLアサーションに含まれる属性のマップ。このマップは、Stringオブジェクトをキーとして持ち、Stringオブジェクトのコレクション(セットまたはリスト)を値(oracle.security.fed.authn.fedattributesとして識別されます)として持ちます。

属性は、そのままの形で送信SSOレスポンスに含まれ、この現在のフェデレーションSSO操作のためにのみ送信されます。それらは、その後、破棄されます。
SP Partnerエントリ内の構成済NameID式の代わりにSAML NameID値として使用される文字列。SAML 2.0 SPパートナの場合、この文字列は、SPパートナのためのNameID書式が「永続」または「一時」でない場合にのみ使用されます。文字列は、oracle.security.fed.authn.feduseridとして識別されます。

この文字列は、この現在のフェデレーションSSO操作のためのNameIDとしてのみ使用され、その後、破棄されます。

処理後、後処理プラグインは、Identity Federationにユーザーを転送する必要があります。(プラグインがない場合はOracle Access Managerが呼び出します)。

ルートWebコンテキストは、/oamfedです
相対パスは、/user/loginssoです

11.4.2 後処理アクション用のIdentity Federationの構成

次の作業を実行することにより、ユーザーを後処理プラグインに転送するようにIdentity Federationを構成します。

WLST環境を入力します。

$IAM_HOME/common/bin/wlst.sh
WLS管理サーバーに接続します。

connect()
Domain Runtimeフォルダに移動します。

domainRuntime()
putStringProperty() WLSTコマンドを実行して次の2つのプロパティを設定します。
- postauthnenginewebcontextプロパティは、カスタムJSPページまたは後処理プラグインのサーブレットが存在するWebコンテキストを参照します。CUSTOM_WEB_CONTEXTを、プラグインに固有の値で置き換えます。
  
  putStringProperty("/authnengines/postauthnenginewebcontext", "CUSTOM_WEB_CONTEXT")
- postauthnenginewebpathプロパティは、後処理プラグインが存在するWebコンテキストにおけるパスを参照します。CUSTOM_WEB_PATHを、プラグインに固有の値で置き換えます。
  
  putStringProperty("/authnengines/postauthnenginewebpath", "CUSTOM_WEB_PATH")
putBooleanProperty() WLSTコマンドを実行して、後処理プラグインを有効または無効にします。
- 後処理プラグインを呼び出すようにIdentity Federationを構成するには、putBooleanProperty("/authnengines/postauthnengineenabled", "true")。
- 後処理プラグインを呼び出さないようにIdentity Federationを構成するには、putBooleanProperty("/authnengines/postauthnengineenabled", "false")

11.5 例: カスタム・アクションの後処理

この項では、ローカル認証操作の最後にユーザーがIdentity Federationにリダイレクトされる前に、Oracle Access Managerにより呼び出される単純な後処理プラグインを示します。このプラグインは、ブラウザが提示するカスタムCookieにアクセスし、データを抽出して、データを属性として設定します。Identity Federationはそれを送信SAMLアサーションに含めます。この例の内容は次のとおりです。

Identity FederationがIdPとして動作している場合。
カスタム・ポスト認証プラグインは、一部の属性を、attr1およびattr2と呼ばれるセッション属性として設定します。
Identity Federation(IdPとして動作)は、アサーション作成時にフェデレーションSSO操作が実行されるSPパートナに、attr1およびattr2属性を送信します。
カスタム・コンポーネントにより、この例で使用するCookieが設定されます。

この例では、プラグインは認証が成功した後、別のコンポーネントによって設定済のカスタムCookieから抽出した次の属性を追加します。

cookie-languageには、ユーザーの優先言語が含まれます。
cookie-homepageには、ユーザーの優先ホームページが含まれます。

後処理プラグインは、ルート・コンテキストが/pluginに設定されたWebアプリケーションから構成されています。データをカスタムCookieから抽出してセッション属性として設定する1つのJSPページ(名前はcookieextract.jsp)が含まれます。cookieextract.jspは、cookieextract.jspの実装例です。

cookieextract.jsp

<%@page buffer="5" autoFlush="true" session="false"%>
<%@page language="java" import="java.util.*, javax.naming.*, 
  javax.naming.directory.*, java.net.*"%>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
 
// check if authentication was successful
if ("SUCCESS".equals(request.getAttribute("oracle.security.fed.authn.result.statuscode")))
{
        // authentication was successful. Attributes will be added
        Map attributes = new HashMap();
        
        // get the cookie
        Cookie[] cookies = request.getCookies();
        String cookieValue = null;
        for(int i = 0; i < cookies.length; i++)
        { 
                Cookie cookie = cookies[i];
                if (cookie.getName().equals("customcookie")) 
                        cookieValue = cookie.getValue();
        }
        if (cookieValue != null && cookieValue.length() > 0)
        {
                StringTokenizer st = new StringTokenizer(cookieValue, "+");
                String language = st.nextToken();
                String homepage = st.nextToken();
 
                attributes.put("cookie-language", language);
                attributes.put("cookie-homepage", homepage);
 
                request.setAttribute( "oracle.security.fed.authn.fedattributes", attributes);
        }
}
 
// forward to the OIF server to resume the flow
request.getSession().getServletContext().getContext("/oamfed").getRequestDispatcher("/user/loginsso").forward(request, response);
%>

注意:

このWebアプリケーションのWARファイルは、OAMが実行されているWLS管理対象サーバーにデプロイする必要があります。

プラグインは、フローを再開するために、内部転送によってユーザーをIdentity Federationサーバーにリダイレクトします。ローカル認証フローの終了時に後処理プラグインを呼び出すようにIdentity Federationを構成するには、次の手順に従ってください。

WLST環境を入力します。

$IAM_HOME/common/bin/wlst.sh
WLS管理サーバーに接続します。

connect()
Domain Runtimeフォルダに移動します。

domainRuntime()
putStringProperty() WLSTコマンドを実行してpostauthnenginewebcontextプロパティを設定します。

putStringProperty("/authnengines/postauthnenginewebcontext", "/plugin")
putStringProperty() WLSTコマンドを実行してpostauthnenginewebpathプロパティを設定します。

putStringProperty("/authnengines/postauthnenginewebpath", "/cookieextract.jsp")
putBooleanProperty() WLSTコマンドを実行して、後処理プラグインを有効にします。

putBooleanProperty("/authnengines/postauthnengineenabled", "true")