1. 『Oracle Access Managementでのアプリケーションの開発』
  2. Access Managerによる開発
  3. カスタム・ページの開発

4 カスタム・ページの開発

Oracle Access Managerはデフォルトのログイン、ログアウト、エラーおよびパスワード・ページに加え、会社のブランドに合せたルック・アンド・フィールのカスタム・ページを作成できる拡張可能なフレームワークを提供しています。

この章では、カスタム・ページの開発方法および使用している環境へのデプロイ方法について説明します。この章には、次の項が含まれています。

4.1 カスタム・ページ・フレームワークについて

Access Managerには、ユーザーに表示される静的HTMLページのセットを含むフレームワークが用意されています。これらのデフォルト・ページを自社のルック・アンド・フィールを反映するようにカスタマイズしたり、すべて新しいページに置き換えることができます。ログイン、ログアウトおよびエラー条件処理時の認証で使用する対話型のカスタム・ページを作成できます。

通常、カスタム・ページ・フレームワークは動的であり、必要なロジックを実行できるスクリプトまたはアプリケーションとして実装する必要があります。そのため、たとえばユーザーがモバイル・ブラウザかデスクトップ・ブラウザのどちらからアクセスしているかに応じて異なるバージョンのログイン・フォームを表示するカスタムHTMLページを設計、実装およびデプロイできます。

ログイン、ログアウト、エラーおよびパスワード・ページは、カスタム・ページ・フレームワークの一部としてパッケージ化されます。すぐに使用できるWebアプリケーション・アーカイブ(WAR)ファイルが用意されているので、これを開始ポイントとしてカスタム・ページを開発できます。このWARの名前はoamcustompages.warで、MW_HOME/oam/server/tools/custompages/ディレクトリにあります。カスタムHTMLページを作成して、WARに追加してください。

ノート:

カスタム・ページは、既存のAccess Manager認証モジュールまたはカスタム認証プラグインと組み合せて使用できます。プラグインの開発の詳細は、「フォームベース・ログイン・ページ認証の理解」を参照してください。

ユーザー向けのカスタム・ページは、OAM_REQトークンおよび認証エンドポイントを返す必要があります。

関連項目:

4.1.1 OAM_REQトークンを返す

OAM_REQは、認証リクエスト・コンテキストCookieが有効な場合にAccess Managerによって設定またはクリアされる一時的なCookieです。このCookieは、Access Managerのみが認識しているキーで保護されています。OAM_REQは、問合せ文字列から取得して非表示のフォーム変数として返送する必要があります。

リソースがリクエストされると、OAMサーバーは資格証明コレクタ・ページにリダイレクトまたはフォワードして資格証明を収集します。また、OAM_REQトークンをログイン・ページに送信します。カスタマイズされたログイン・アプリケーションの場合、そのログイン・アプリケーションでリクエストからOAM_REQトークンを取得して、資格証明とともにOAMサーバーに送り返すようにする必要があります。OAM_REQは、問合せ文字列から取得して非表示のフォーム変数として返送する必要があります。たとえば:

String reqToken = request.getParameter(GenericConstants.AM_REQUEST_TOKEN_IDENTIFIER);
 
<%
if(reqToken != null && reqToken.length() > 0) { %>
<input type="hidden" name="<%=GenericConstants.AM_REQUEST_TOKEN_IDENTIFIER%>" value="<%=reqToken%>">
<%
}
%>

『Fusion Middleware Oracle Access Management管理者ガイド』のSSO Cookieの理解に関する項も参照してください。

4.1.2 エンド・ポイントを返す

エンド・ポイント/oam/server/auth_cred_submitをOAMサーバーに返す必要があります。たとえば: 

<form action="/oam/server/auth_cred
_submit"> or "http://oamserverhost:port/oam/server/auth
_cred_submit".

4.2 カスタム・ページによる認証

認証プロセスでは、リソースへのアクセスをリクエストしているユーザーに必要な資格証明を確認し、HTTPを介して資格証明を収集し、資格証明の検証結果を反映したHTTPレスポンスを返します。

図4-1は、Access Managerで保護されたリソースにアクセスするユーザーを認証するエンドツーエンドのリクエスト・フローで、最終的にエラー・ページが表示されます。

図4-1 認証リクエスト・フロー

図4-1の説明が続きます
「図4-1 認証リクエスト・フロー」の説明

このプロセスでは、認証(AuthN)プラグインを使用する特定の認証スキームによってリソースが保護されています。AuthNプラグインがアイデンティティ・ストアAPIを使用して資格証明を認証します。AuthNプラグインは、サード・パーティAPIもコールできます(図には非表示)。

  1. ユーザーが保護されたリソースをリクエストすると、認証フローがトリガーされ、ログイン・ページが表示されます。ユーザーが入力する必要な資格証明が、認証エンジンに送信されます。

  2. 認証を行うために、アイデンティティ・ストアAPIがバックエンド・ストアとの接続を確立します。アイデンティティ・ストアの例としてADとOVDが記載されています。

  3. アイデンティティ・ストア・レイヤーが、結果をプラグインおよび認証エンジン・レイヤーに返します。認証レイヤーで、バックエンドからのエラー・コードが対応するAccess Managerエラー・コードにマップされます。標準エラー・コードの詳細は、表4-2を参照してください。

    この結果には、アイデンティティ・ストアから取得した認証エラー・コードおよびネイティブ・エラー・コードが含まれます。ネイティブ・エラー・コードは、マップされていないセカンダリ・エラー・コード(p_sec_error_msg)としてログイン・ページに返されます。セカンダリ・エラー・コードの詳細は、「セカンダリ・エラー・メッセージの伝播」を参照してください。

    エラー・コードは問合せパラメータとしてエラー・ページおよびログイン・ページに返されます。エラー・コードはHTTPリクエスト・パラメータとしてエラー・ページに送信されます。問合せパラメータはp_error_codeという名前です。

  4. プライマリ・エラー・コード・メッセージとは、エラー・コードの詳細テキストを含むローカライズされた文字列です。これは、該当するリソース・バンドル・ファイルからエラー・コードを使用して取得できます。

次の各項では、詳細を説明します。

4.2.1 エージェントを使用した認証

HTTPクライアントAPIを使用したプログラムによる認証は、OAMサーバーでサポートされています。詳細は、次の各項を参照してください。

4.2.1.1 OAMサーバーを使用したプログラム・ベースの認証

このリリースのOAMサーバーでは、JavaScriptを使用して資格証明入力用のログイン・フォームをクライアントに送信します。クライアントまたはデバイスがスクリプトベースのリダイレクトに対応していない場合は、クライアントが使用するユーザー・エージェントをプログラムによるクライアントとして構成する必要があります。すると、OAMサーバーは、そのクライアントをブラウザ・ベースのクライアントではなくプログラムによるクライアントとして認識します。この場合、OAMサーバーはJavaScriptベースのリダイレクトを使用します。

次に、oam-config.xmlでの構成設定の例を示します。userAgentType設定の下には複数のエントリを追加できます。 

<Setting Name="userAgentType" Type="htf:map">
   <Setting Name="Mozilla/4.0 (compatible; Windows NT 5.1)
 OracleEMAgentURLTiming/3.0" Type="xsd:string">PROGRAMATIC</Setting>
 </Setting>
4.2.1.2 プロセスの概要: プログラムによるクライアントの開発

Access Managerのプログラムによるクライアントを開発する場合は、次のプロセスを使用します。

  • アプリケーションからクライアントAPIを使用して、保護されているリソースをHTTPチャネル経由で呼び出します。

  • OAMサーバーが、リクエスト・パラメータsite2pstoretokenとp_submit_urlを持つログイン・ページへリダイレクトします。

    p_submit_urlには、プログラムによる認証エンドポイントが格納されています。たとえば、http(s)://host:port/sso/authとなります。デフォルトのブラウザ・アクションURLはサーバー側にセッションを作成しますが、プログラムによる認証エンドポイントにはこのURLがありません。プログラムによる認証エンドポイントは、認証ごとにセッションを作成するのではなく、1ユーザーに1個のグローバル・セッションを使用します。このセッションは、特定の1ユーザーに対してプログラムによって実行されるすべての認証に共通です。

  • プログラムによるクライアントからプログラムによるエンドポイントへ資格証明が送信されます。

  • クライアントは、ステップ3で取得したssousername、password、s2pstoretokenの情報をp_submit_urlへ送信する必要があります。

  • OAMサーバーが資格証明を検証し、有効ならば、最初の保護されたアプリケーションへリクエストをリダイレクトします。

  • 資格証明の検証がエラーの場合は、p_error_codeが返されます。

4.2.2 要求していないPOSTを使用した認証

要求していないPOSTを使用したプログラムによる認証には、次のプロセスを使用します。

  1. 直接認証を有効化します。

    oam-config.xmlで、DirectAuthenticationServiceDescriptorの下のServiceStatusがtrueに設定されていることを確認します。(DirectAuthenticationServiceDescriptorはOAMServicesDescriptorの下にあります)。

  2. 次の情報をエンドポイントhttps://oam_host:oam_port/oam/server/authenticationに送信します。

    • ユーザー名

    • パスワード

    • 成功URL。たとえば、http://machinename.example.com:7778/sample-web/headers.jsp。

  3. 資格証明が認証されると、OAMサーバーはHTTPリダイレクト(HTTPレスポンス・コード302)の一部としてOAM_ID Cookieを設定してから、成功URLにリダイレクトします。

直接認証をPOSTでのみ許可する(またはその逆の)には:

  1. Oracle Access Management管理コンソールにログインし、「ポリシー構成」→「アプリケーション・ドメイン」に移動します。

  2. 「IAMSuite」を選択します。「リソース」に移動し、リソース/oamDirectAuthenticationを検索して編集します。

  3. 「操作」で、POSTを除く、サポートしないすべての操作の選択を解除します。たとえば、GET、DELETEなどです。

ユーザー名とパスワードの資格証明の認証方法を成功URLごとに変えるには:

  1. 直接認証リクエスト時にusername、passwordおよびsuccessurlとともに、パラメータtypeと認証メカニズムを指定する値を渡します。
  2. 「IAMSuite」アプリケーション・ドメインに移動します。リソースURL /oamDirectAuthentication、およびtypeという名前の問合せ文字列とステップ1で指定した値を使用して、新規のリソースを作成します。
  3. このリソースを、選択したtypeをサポートする認証スキームに関連付けます。
  4. URL /oamDirectAuthenticationと問合せ文字列typeの様々な値(たとえば、type=FORM、type=CREDS)を使用して複数のリソースを作成し、対応する認証スキームに関連付けます。

4.2.3 DCC WebGatesでの要求していないログインを使用した認証

次の手順は、DCC WebGatesを使用する非請求ログインを構成します。

  1. DCC WebGateを構成します。

    『Oracle Fusion Middleware Oracle Access Management管理者ガイド』のX509認証用のDCC WebGateの構成に関する項を参照してください。

  2. 直接認証を有効化します。

    oam-config.xmlファイルのDirectAuthenticationServiceDescriptorの下にあるServiceStatusがtrueに設定されていることを確認します。DirectAuthenticationServiceDescriptorパラメータは、OAMServicesDescriptorの下にあります。

  3. DCC WebGateプロファイルのユーザー定義パラメータに、TunneledUrls=/oam/server/authenticationを追加します。

    /oam/server/authenticationは直接認証URLです。

  4. DCC WebGateを再起動します。
  5. ホスト/ポートのバリエーションがリソースのWebGateに追加されたことを確認します。

    たとえば、リソースのWebGateがhttp://<RWG-Host>:<port>/の場合、ホストのバリエーション<RWG-Host>とポートのバリエーション<port>をHost Identifierに追加します。

    ノート:

    DCC WebGatesではHost Identifierの構成は不要なので、リソースのWebGateホスト識別子にのみホストのバリエーションを追加します。リソースWebGateおよびDCC WebGateには、異なるプロファイルとホストの識別子のセットがあります。

  6. DCC WebGateアプリケーション・ドメインのパブリック・リソース認可および認証ポリシーを使用して、/pages/login.jspと/oam/**と/oamsso-bin/login.plを保護します。

    /oam/server/authenticationは、DCCアプリケーション・ドメインのパブリック・リソース認可および認証ポリシー・スキームで保護してください。/oamsso-bin/login.plと/pages/login.jspはログイン・ページであり、DCCのパブリック・リソースとしてマークしてください。successurl値は保護されている必要があり、ポスト・パラメータとして提供されます。

    ノート:

    直接認証URLを使用して保護されているリソースの認証スキームを構成するには、「要求していないPOSTを使用した認証」を参照してください。

  7. DCC認証エンドポイントには、http://<dcc-host>:<dcc-port>/oam/server/authenticationでアクセスできます。

    特定のアプリケーションにマップできるTYPEパラメータがあります。リソースにアクセスするには、このDCCエンドポイントにユーザー名、パスワードおよびsuccessurlパラメータをポストします。

4.3 カスタム・ログイン・ページについて

カスタム・ログイン・ページをWARファイルとして作成し、必要なリソース・バンドル・ファイルと一緒にパッケージ化できます。WARファイルは、DCCの背後にあるアプリケーション上にデプロイできます。DCCが使用されていない場合は、ECCが実行されているサーバーと同じサーバー上にこのページをデプロイできます。

ECCを使用している場合は、カスタムWARファイルを使用して認証スキームに次の設定を指定する必要があります。

  • コンテキスト・タイプ = CustomWar

  • チャレンジURL = WARファイル内のログイン・ページのURLに対する相対パス

  • コンテキスト値 = カスタムWARのルート・パスカスタマイズしたエラー・ページをカスタムWARファイルに含める場合は、その絶対URLを認証ポリシーの失敗リダイレクトURIで指定する必要があります。たとえば、http://host:port/SampleLoginWar/pages/MFAError.jspです。

関連項目:

4.3.1 フォームベース・ログイン・ページ認証の理解

フォームベース認証では、Access Managerの認証メカニズムを使用してログイン資格証明を処理するカスタムWebフォームを開発できます。これらのフォームはHTMLページであり、ログイン情報を複数言語で表示したり、会社のプレゼンテーション標準に準拠したユーザー・インタフェース・エレメントを表示したり、パスワード管理に必要な機能を追加することができます。

フォームまたはログイン・アプリケーションは、ユーザーからのリダイレクトを処理してHTMLをレンダリングする任意のテクノロジ(JSP、ASP.net、Perl、PHPなど)を使用して記述できます。これによって、会社の標準を反映するようにページのルック・アンド・フィールをカスタマイズしたり、ユーザーの資格証明をOAMサーバーに送信する前にユーザーの送信(POST)を前処理することが、必要に応じてできるようになります。

リクエスト・キャッシュのモードとして、basic、cookie、formの3つがサポートされています。basicモードで動作する場合、request_idが必須パラメータであり、返送する必要があります。formモードでは、OAM_REQトークンが必須であり、存在する場合は返送する必要があります。cookieモードでは、OAM_REQがCookieとして設定されます。

カスタム・ログイン・フォーム・ページには次のような要件があります。

  • 目的の認証モジュールをサポートするようにページを構築する必要があります。

  • ページでOAM_REQトークンの取得をサポートする必要があります。「OAM_REQトークンを返す」を参照してください。

  • ページでエンド・ポイントを取得する必要があります。「エンド・ポイントを返す」を参照してください。

4.3.2 ページ・リダイレクション・プロセスの概要

Access Managerによる認証に対応したカスタム・ログイン・ページを記述する場合、OAMサーバーの外部でホストされたログイン・ページへユーザーをリダイレクトするのが一般的な方法です。ユーザーは、記述したカスタム・ページまたはアプリケーションにリダイレクトされます。

フォームベース認証スキームが外部チャレンジ・タイプで作成されている場合、OAMエージェントはユーザーをまずobrareq.cgi URLへリダイレクトし、このURLはこのユーザーを、認証スキームのチャレンジURLとして指定されたログイン・ページへリダイレクトします。チャレンジ・リダイレクトURLは、DCCまたはECCエンドポイントを宣言します。チャレンジURLは、FORMなどのチャレンジ・メソッドに関連付けられたURLです。

リダイレクト・ページで、request_idとredirect_urlが問合せ文字列に追加されます。たとえば: 

?request_id=5092769420627701289&redirect_url=http%3A%2F%2Fexample.com%3A7777%2Fscripta%2Fprintenv

x509認証スキームを使用する場合は、透過的に認証が実行されるため、ログイン資格証明専用のページはありません。ただし、ページ・リダイレクションは非フォームベースの認証方式にも適用されます。たとえば、x509認証スキームを使用する場合、保護されているリソースを表示する前に、機密保護に関する免責条項などへユーザーをリダイレクトできます。この場合、免責条項ページへのパスを入力し、そのページを/oam/CredCollectServlet/X509ページにリダイレクトさせます。オリジナルの問合せスキームを必ず提示してください。

4.4 カスタム・エラー・ページの理解

この項では、カスタム・エラー・ページの開発に固有の情報について説明しています。次の情報が含まれます。

使用している環境で、エラー・コード問合せパラメータp_error_codeおよびp_sec_error_msgがどのようにカスタム・エラー・コードにマップされるかについては、「サンプル・コード: エラー・コードの取得」を参照してください。

ノート:

「認証プラグインのエラー・コード」および「サンプル・コード: パスワード・ポリシー・エラー・コードの取得」

4.4.1 エラー・ページのカスタマイズの有効化

カスタム・エラー・ページをパッケージ化し、そのまま使用できるWebアプリケーション・アーカイブ(WAR)ファイルとしてデプロイすると、updateCustomPages WLSTコマンドを使用して有効化および無効化できます。カスタム・エラー・ページには、カスタムWebアプリケーションをデプロイする際に従う必要がある特定の場所があります。その場所を次に示します。 

http(s)://<host>:<port>/<context>/pages/Error.<pageExtension>

関連項目:

Oracle Fusion Middleware WebLogic Scripting Tool Identity and Access Managementコマンド・リファレンス(updateCustomPagesやその他のWLSTコマンドに関する情報。)

カスタム・エラー・ページおよびカスタム・ログアウト・ページのデプロイメント・パスの指定

4.4.2 標準エラー・コード

Access Managerでは、失敗の理由を示す標準エラー・コードが提供されています。一般的な理由として、ユーザー名およびパスワードの無効な組合せ、ロック中または無効なユーザー・アカウント、内部処理エラーなどがあります。認証エラーの理由はバックエンド・アイデンティティ・ストアから取得され、Access Managerサーバーで管理されている特定のエラー・コードにマップされます。そして、このエラー・コードがログインまたはエラー・ページに伝播されます。(カスタム・エラー・ページには、内部サーバー・エラーも表示されます。)

表4-1は、ログイン・ページおよびエラー・ページで使用できる標準エラー情報をまとめたものです。

表4-1 エラー情報の種類

メッセージ・タイプ 説明

エラー・コード

特定の数値を含む文字列。エラー・コードはAccess Managerのみによって管理されます。問合せ文字列パラメータはp_error_codeという名前です。

プライマリ・エラー・メッセージ

エラー・コードの詳細テキストを含むローカライズされた文字列。クライアントのロケール、つまりユーザーのブラウザの言語設定に依存します。

セカンダリ・エラー・メッセージ

失敗の実際の原因を含むローカライズされていない文字列。セカンダリ・エラー・メッセージは、カスタム認証プラグインから提供される場合と、アイデンティティ・ストアから返される場合があります。問合せ文字列パラメータはp_sec_error_msgという名前です。

表4-2は、OAMサーバーによって送信されるエラー・メッセージ・コードおよび対応するプライマリ・エラー・メッセージを網羅したリストです。プライマリ・エラー・メッセージがアプリケーション用にカスタマイズされている場合、アプリケーションでこのカスタム・メッセージを、OAMサーバーによって管理されている対応する標準エラー・コードにマップする必要があります。エラー・コードOAM-1とOAM-2に違いはありません。

表4-2 標準エラー・コードおよびメッセージ

エラー・コード プライマリ・エラー・メッセージ

OAM-1

指定したユーザー名またはパスワードが正しくありません。

OAM-2

指定したユーザー名またはパスワードが正しくありません。

OAM-3

資格証明の処理中に予期しないエラーが発生しました。アクションを再試行してください。

OAM-4

システム・エラーです。システム管理者に連絡してください。

OAM-5

ユーザー・アカウントがロックされているか、無効です。システム管理者に連絡してください。

OAM-6

ユーザーはすでにセッションの最大許容数に達しました。ログインを再試行する前に、既存のセッションの1つをクローズしてください。

OAM-7

システム・エラーです。アクションを再試行してください。このエラーが続く場合は、管理者に連絡してください。

OAM-8

認証に失敗しました。

OAM-9

システム・エラーです。アクションを再試行してください。このエラーが続く場合は、管理者に連絡してください。

OAM-10

パスワードの有効期限が切れました。システム管理者に連絡してください。

4.4.3 セキュリティ・レベルの構成

エラー・コードのセキュリティ・レベルによってOAMサーバーが返すエラー・コードが決まります。セキュリティ・レベルは、管理者がAccess Manager管理コンソールの構成パネルを使用して構成します。カスタム・ログイン・ページのエラー・コードを構成するとき、次のセキュリティ・レベル設定が使用できます。

  • セキュア: セキュリティ・レベルが最も高い設定。汎用的なエラー・メッセージを表示し、エラーの内部的な理由についての情報はほとんど提供しません。

  • 外部: 推奨するデフォルトのレベル。

  • 内部: セキュリティ・レベルが最も低い設定。エラー・コードをログイン・ページまたはエラー・ページに伝播できます。

表4-3は、セキュリティ・レベルに応じてログインまたはエラー・ページに伝播される標準エラー・コード(表4-2を参照)のリストです。

表4-3 セキュリティ・レベル別のエラー状態マッピング

エラー状態 内部モード 外部モード セキュア・モード

無効なログインを試行しました。

OAM-1

OAM-2

OAM-8

送信された資格証明の処理がなんらかの理由で失敗しました。たとえば、WNAモードでspnegoトークンが受信されない場合などです。

OAM-3

OAM-3

OAM-8

なんらかの理由で認証例外が発生しました。

OAM-4

OAM-4

OAM-9

ユーザー・アカウントがなんらかの状況によりロックされています。たとえば、無効な試行の回数が上限を超えた場合などです。

OAM-5

OAM-5

OIMが統合されている場合はOAM-8またはOAM-9

ユーザー・アカウントが無効です。

OAM-5

OAM-5

OAM-9

ユーザーが最大許容セッション数を超えました。

これは構成可能な属性です。

OAM-6

OAM-6

OAM-9

複数の理由が考えられます。セキュリティ上の理由から、正確な理由はユーザー・レベルには伝播されません。

特定のメッセージが伝播されない場合は、デフォルトのエラー・メッセージが表示されます。

OAM-7

OAM-7

OAM-9

エラー状態が発生すると、デフォルト・ページが認証ポリシーのfailure-redirect-urlでオーバーライドされていないかぎり、OAMサーバーはデフォルト・エラー・ページをフォワードします。カスタム・エラー・ページを使用する場合は、サーバーがカスタム・ページへリダイレクトするように、そのエラー・ページの絶対URLを認証ポリシーのfailure_redirect_urlで設定する必要があります。カスタム・ログイン・ページは通常、エラー・ページとして機能するロジックを持っています。

エラー状態OAM-1およびOAM-8の場合、資格証明を再度収集できるので、ユーザーはログイン・ページに戻されます。

4.4.4 セカンダリ・エラー・メッセージの伝播

認証エンジン・レイヤーで、バックエンド・アイデンティティ・ストアからの例外がOAMサーバー固有のエラー・コードにマップされます。その後、これらのコードが伝播されます。プラグインは、セカンダリ・エラー・コードを取得して伝播することにより、適切なアクションを実行させることができます。

ノート:

プライマリ・エラー・コードは、どのモードでもエラーまたはログイン・ページに伝播されます。セカンダリ・エラー・メッセージは、セキュリティ・レベルが内部に設定されている場合のみ伝播されます。詳細は、「セキュリティ・レベルの構成」を参照してください。

セカンダリ・エラー・メッセージは、HTTPリクエスト・パラメータとしてエラー・ページに送信されます。問合せパラメータはp_sec_error_msgという名前です。このメッセージはバックエンドからのコードとメッセージ・テキストを連結した文字列で、翻訳はされていません。

たとえば、OVDがバックエンドであり、無効な資格証明が入力されると、認証が失敗し、その理由としてバックエンドからLDAP:error code 49-Invalid Credentialsが返され、OAMサーバー・エラー・コードOAM-1が返されます。この場合、次のデータがログイン・ページに表示されます。

4.4.5 サンプル・コード: エラー・コードの取得

エラー・コードは、HTTPリクエスト・パラメータとしてエラー・ページに送信されます。問合せパラメータはp_error_codeという名前です。このパラメータ値には、OAMサーバーが返したエラー・コード値が含まれています(OAM-1など)。

ノート:

Access Managerの標準エラー・コードおよび対応するメッセージは、表4-2を参照してください。これらのエラー・コードに追加情報はありません。

カスタム・ログイン・ページをカスタム・リソース・バンドルに関連付けることにより、エラー・コードを意味のあるメッセージに変換してエンド・ユーザーに表示できます。ただし、意味のあるエラー・メッセージや翻訳がカスタム・ログイン・ページで必要なければ、カスタム・リソース・バンドルは必要ありません。

ローカル・リソース・バンドル・ファイルを作成し、表4-3のように、エラー状態をAccess Managerエラー・コードにマップする必要があります。このファイルをログイン・ページまたはエラー・ページで使用できます。例4-1にリソース・バンドル・コードの例を示します。また、例4-2にエラー・コード・ページの例を示します。

例4-1 リソース・バンドル・コード

package mytest.error;
     Import java.util.ListResourceBundle;
  public class ExampleErrorMsg extends ListResourceBundle {
	/* (non-Javadoc)
	 * @see java.util.ListResourceBundle#getContents()
	 */
	public Object[][] getContents()
    {
        return m_contents;
    }
    /** The Constant m_contents. */
    private static final Object[][] m_contents =
     {
        {"OAM-1", " An incorrect Username or Password was
 specified "},
        {"OAM-2", " An incorrect Username or Password was
 specified "},
        {"OAM-3", "Unexpected Error occurred while processing
 credentials. Please retry your action again!"},
        {"", ……};
             }
     }

例4-2 エラー・コード・ページ

<%@page import="mytest.error.ExampleErrorMsg"%>
  //initializing the messageBundle first
  String defaultResourceBundle = "mytest.error.ExampleErrorMsg";
  java.util.Locale myLocale = request.getLocale();
  ResourceBundle msgBundle=
 ResourceBundle.getBundle(defaultResourceBundle,myLocale);
String errCode = request.getParameter("p_error_code");
String secondaryErrMessage = request.getParameter("p_sec_error_msg");
  <%
        if(errCode != null && errCode.length() > 0) {
          try {
             simpleMessage = msgBundle.getString(errCode);
          } catch(Exception e) {
             //get the default authn failed message
             simpleMessage = msgBundle.getString("OAM-8");
          }
  %>
  <div class="message-row"> 
      <p class="loginFailed"> <%=simpleMessage%> </p> 
  </div>

4.4.6 エラー・データ・ソースの一覧

表4-4は、認証プラグインで使用できるエラー・データ・ソースをまとめたものです。

表4-4 認証プラグインのエラー・データ・ソース

ソース パラメータ

エラー・コード

HTTPリクエスト・パラメータ: p_error_code

プライマリ・エラー・メッセージ

リソース・バンドルからエラー・コードを使用して取得されます。

セカンダリ・エラー・メッセージ(内部エラー・モードの場合のみ送信)

HTTPリクエスト・パラメータ: p_sec_error_msg

サーバー・エラー・コードを連結したリスト

HTTPリクエスト・パラメータ: p_error_codes_list

パスワード・プラグインのエラー・メッセージ

HTTPリクエスト・パラメータ: rejectedRulesDesc

プラグイン・クライアント・レスポンス

HTTPリクエスト・パラメータ: PLUGIN_CLIENT_RESPONSE

プラグイン・エラー・レスポンス

HTTPリクエスト・パラメータ: PLUGIN_ERROR_RESPONSE

4.5 カスタム・パスワード・ページの理解

ユーザー認証用のカスタム・パスワード・ページを記述する一般的な方法は、Access Managerの外部にホストされているパスワード・ページにユーザーをリダイレクトすることです。カスタム・ページは、ユーザーからのリダイレクトを処理してHTMLをレンダリングするように記述します。

Access Managerは、フォームベースのJava Server Pages (JSP)でユーザーが入力したパスワードおよびパスワードの変更を処理します。このページは、複数の言語でカスタマイズしたり、会社のロゴを表示できます。カスタム・パスワード・ページは、JSPで保管することも、ASP.net、Perl、PHPおよび他の同様なテクノロジを使用して記述することもできます。このページによって、ユーザーの資格証明をAccess Managerに送信する前に、必要に応じてユーザーの送信(POST)を前処理できるようになります。後続の項で詳細を示します。

4.5.1 パスワード・ページWARのカスタマイズ

ログインおよびパスワード・ページに必要な変換バンドルを含む基本的なWebアーカイブ(WAR)ファイルは、Access Managerをインストールする際に提供されます。このWARはoamcustompages.warと呼ばれ、パスワード・ページをカスタマイズする際の開始点となります。カスタム・パスワード・サービス・フォーム・ページの要件は、次のとおりです。

このWARは、$IDM_HOME//oam/server/tools/custompages/ディレクトリにあります。このWARを使用すると、基本的な構造がすでに存在しているというメリットを得られます。図4-2にWARの構造を示します。CSSおよび画像は、要件に応じてカスタマイズ可能です。

図4-2 アーカイブされていないWAR

図4-2の説明が続きます
図4-2「アーカイブされていないWAR」の説明

4.5.2 リクエスト・キャッシュの使用

リクエスト・キャッシュのモードとして、basic、form、cookieの3つがサポートされています。

  • basicモードでは、request_idが必須パラメータとして定義されており、これを返送する必要があります。

  • formモードでは、OAM_REQトークンが必須として定義されており、可能な場合はこれを返送する必要があります。

  • cookieモードでは、OAM_REQをCookieとして設定します。

4.5.3 パスワード・サービスURLの指定

パスワード・ページの開始点はpswd.jspです。このページの場所は、Oracle Access Management管理コンソールを使用して、「パスワード・ポリシー」の下に構成されます。パスワード・ポリシー管理に関する項を参照してください。

  1. 管理者としてAccess Manager管理コンソールにログインします。
  2. 「Access Manager」の下の「パスワード・ポリシー」リンクをクリックします。
  3. 「パスワード・サービスURL」属性の値を定義または変更します。
  4. 「適用」をクリックします。

4.5.4 サンプル・コード: 警告メッセージの取得

ユーザー向けのページでは、パスワードの有効期限が切れるまでの日数にアクセスできます。次のコード・スニペットで、パスワードの有効期限が切れるまでの日数または時間を取得する方法を示します。

String message = "";
if(errCode != null && errCode.equals("1")) {
message = msgBundle.getString("USER_PSWD_WARNING") + errCode +
msgBundle.getString("USER_PSWD_DAY");
} else if (errCode != null && errCode.equals("0")) { message =
msgBundle.getString("USER_PSWD_WARNING_HOURS"); } else {
message = msgBundle.getString("USER_PSWD_WARNING")+ " " + errCode + " " +
msgBundle.getString("USER_PSWD_DAYS");
}

4.5.5 サンプル・コード: パスワード・ポリシー・エラー・コードの取得

ユーザー向けのページでは、パスワード・ポリシーの結果コンテキストにアクセスでき、該当するメッセージを取得できます。各メッセージには、場合によって追加情報が含まれていることがあります。次のコードの抜粋は、ページでパスワード・ポリシーの結果コンテキストからメッセージと追加情報を取得する方法を示しています。 

String simpleMessage = "";
  String result = request.getParameter("rejectedRuleDesc");
  if(result.indexOf('~') != -1) {
   String[] results = result.split("~");
   for(String eachResult : results) {
      if(eachResult.indexOf(":") != -1) {
        String messageKey = eachResult.substring(0, eachResult.indexOf(":"));
        String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(messageKey);
        String placeHolderValue = eachResult.substring(eachResult.indexOf(":") + 1, eachResult.length());
        String displayValue = Localizer.localize(resourceBundleKey, placeHolderValue, myLocale);
        simpleMessage += displayValue + "<br>";
      }
      else {
        String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(eachResult);
        String displayValue = Localizer.localize(resourceBundleKey, null, myLocale);
        simpleMessage += displayValue + "<br>";
 
      }
   }
  }

たとえば、パスワードの文字数が足りない場合、コンテキストの結果は次のようになります。

  • PasswordRuleDescription.getResourceBundleKey()は、"passwordPolicy.error.minLength"を返します

  • PasswordRuleDescription.getPlaceHolderValue()が最小文字数を返します。

  • PassswordRuleDescription.eachDesc.getDisplayValue()が完全に翻訳されたメッセージを返します。

パスワード・プラグインがパスワード・ページにリダイレクトし、対応するメッセージがパスワード・ポリシーから取得されます。これらのエラー・コードは、HTTPリクエスト・パラメータruleDesとしてパスワード・ポリシー・ページに送信されます。表4-5は、パスワードの検証時に返される可能性のあるエラー・コード、メッセージ・キーおよび対応するメッセージのリストです。

表4-5 パスワード検証エラー・コード

URL内のメッセージ・キー リソース・バンドルのメッセージ・キー メッセージ・テキスト

PSWD-1

passwordPolicy.message.minLength

パスワードは{0}文字以上である必要があります。

PSWD-2

passwordPolicy.message.maxLength

パスワードは{0}文字以下である必要があります。

PSWD-3

passwordPolicy.message.minAlpha

パスワードには英文字を{0}文字以上含める必要があります。

PSWD-4

passwordPolicy.message.minNumber

パスワードには数字を{0}文字以上含める必要があります。

PSWD-5

passwordPolicy.message.minAlphaNumeric

パスワードには英数字を{0}文字以上含める必要があります。

PSWD-6

passwordPolicy.message.minSpecialChars

パスワードには特殊文字を{0}文字以上含める必要があります。

PSWD-7

passwordPolicy.message.maxSpecialChars

パスワードには特殊文字を最大{0}文字しか使用できません。

PSWD-8

passwordPolicy.message.maxRepeated

パスワードでの特定の文字の繰返しは{0}回までです。

PSWD-9

passwordPolicy.message.minUnique

パスワードには一意の文字を{0}文字以上含める必要があります。

PSWD-10

passwordPolicy.message.minUpperCase

パスワードには大文字を{0}文字以上含める必要があります。

PSWD-11

passwordPolicy.message.minLowerCase

パスワードには小文字を{0}文字以上含める必要があります。

PSWD-12

passwordPolicy.message.maxAge

パスワードは最終パスワード変更の{0}日後に期限切れになります。

PSWD-13

passwordPolicy.message.warnAfter

パスワード変更リマインダは最終パスワード変更の{0}日後に送信されます。

PSWD-14

passwordPolicy.message.reqdChars

パスワードには次の文字を含める必要があります: {0}

PSWD-15

passwordPolicy.message.invalidChars

パスワードに次の文字を含めることはできません: {0}

PSWD-16

passwordPolicy.message.validChars

パスワードには次の文字を含めることができます: {0}

PSWD-17

passwordPolicy.message.invalidStrings

パスワードに次の文字列を含めることはできません: {0}

PSWD-18

passwordPolicy.message.startsWithChar

パスワードはアルファベットで開始する必要があります。

PSWD-19

passwordPolicy.message.disAllowUserId

パスワードは、ユーザーIDと同じにすることも、ユーザーIDを含めることもできません。

PSWD-20

passwordPolicy.message.disAllowFirstName

パスワードは、名と同じにすることも、名を含めることもできません。

PSWD-21

passwordPolicy.message.disAllowLastName

パスワードは、姓と同じにすることも、姓を含めることもできません。

PSWD-22

passwordPolicy.message.dictMessage

辞書にあるような言葉はパスワードにできません。

PSWD-23

passwordPolicy.message.enforceHistory

{0}つ前までのパスワードはいずれもパスワードにできません。

PSWD-24

passwordPolicy.message.minAge

最終パスワード変更後{0}日間はパスワードを変更できません。

PSWD-25

passwordPolicy.message.minUnicode

パスワードにはUnicode文字を{0}文字以上含める必要があります。

PSWD-26

passwordPolicy.message.maxUnicode

パスワードには{0}文字を超えるUnicode文字は使用できません。

4.5.6 サンプル・コード: パスワード・ポリシー・ルールの取得

ユーザー向けのページでは、ユーザーに適用されるパスワード・ポリシー・ルールにアクセスできます。各メッセージには、場合によって追加情報が含まれていることがあります。次のコードの抜粋は、ページでパスワード・ポリシーの結果コンテキストからルールと追加情報を取得する方法を示しています。 

String simpleMessage = "";
String result = request.getParameter("ruleDesc");
if(result.indexOf('~') != -1) {
String[] results = result.split("~");
for(String eachResult : results) {
if(eachResult.indexOf(":") != -1) {
String messageKey = eachResult.substring(0, eachResult.indexOf(":"));
String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(messageKey);
String placeHolderValue = eachResult.substring(eachResult.indexOf(":") + 1, eachResult.length());
String displayValue = Localizer.localize(resourceBundleKey, placeHolderValue, myLocale);
simpleMessage += displayValue + "<br>";
}
else {
String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(eachResult);
String displayValue = Localizer.localize(resourceBundleKey, null, myLocale);
simpleMessage += displayValue + "<br>";
 
}
}
}

たとえば、パスワードの文字数が足りない場合、コンテキストの結果は次のようになります。

  • PasswordRuleDescription.getResourceBundleKey()は、"passwordPolicy.error.minLength"を返します

  • PasswordRuleDescription.getPlaceHolderValue()が最小文字数を返します。

  • PassswordRuleDescription.eachDesc.getDisplayValue()が完全に翻訳されたメッセージを返します。

4.6 カスタム・ページでの資格証明コレクタの使用

資格証明収集コンポーネントを有効にすると、カスタム・ページ向けの通信エンドポイントとして使用できます。資格証明コレクタにより、カスタマイズしたユーザー・インタフェースとの対話が容易になります。

2つのAccess Manager資格証明収集コンポーネントのどちらか一方を有効にして、カスタム・ページ向けの通信エンドポイントとして使用したり、カスタマイズしたユーザー・インタフェースとの対話を容易にすることができます。Access Manager資格証明収集コンポーネントには次のものがあります。

  • 組込み資格証明コレクタ(ECC): 追加のインストールや設定なしですぐに使用できます。ECCを使用する場合、デフォルト・ページには以下の場所からアクセスできます。

    • ログイン・ページ: http(s)://host:port/oam/pages/login.jsp

    • エラー・ページ: http(s)://host:port/oam/pages/servererror.jsp

  • 外部資格証明コレクタ(DCC): 本番デプロイにおけるスケーラビリティおよびセキュリティ分離を向上させる場合には、これをお薦めします。DCCを使用する場合、デフォルト・ページには次の場所からアクセスできます。

    • ログイン・ページ: /oamsso-bin/login.pl

    • ログイン・アクションURL: /oam/server/auth_cred_submit。これは、認証スキーム・パラメータでactionが構成されていない場合のデフォルトのアクションURLです。デフォルトのURLに対応する物理ページはありません。URLの場所に物理ページが必要になるのは、認証スキームでactionが構成されており、アクションURLでランタイムaction typeの結果がパス・スルーの場合のみです。

    • エラー・ページ: /oberr.cgi。これは、DCCによって認識されるURLパターンであり、物理的な場所ではありません。

ユーザーとの対話用にどちらの資格証明収集コンポーネントを有効にした場合も、使用している環境におけるカスタム・ページの設計や実装はほとんど同じです。

ノート:

Access Managerサーバーの資格証明コレクタの詳細は、DCC対応の11g WebGateと認証ポリシーの構成に関する項を参照してください。

この項では、DCCの詳細を説明しています。

4.6.1 カスタム・ページを伴う外部資格証明コレクタについて

カスタム・ページから資格証明を収集するためにDCCを使用する場合、主に次のような違いがあります。

  • 次のWebgate Oracleホーム(WebgateOH)ディレクトリにあるHTMLテンプレートを使用してPerlスクリプトとして実装されたデフォルト・ページとともに、DCCがインストールされます。

    • WebgateOH/webgate/ohs/oamsso

    • WebgateOH/webgate/ohs/oamsso-bin

  • サポートされている認証メカニズム向けのログイン・ページのカスタマイズに加え、デフォルトのエラーおよびログアウト・ページもカスタマイズできます。

    • 認証フローの外でエラー状態が発生したときや、認証スキームで失敗リダイレクトURLが指定されていない場合、デフォルト・エラー・ページがトリガーされます。デフォルト・エラー・ページのテンプレートおよび関連付けられたエラー・メッセージは、Webgate Oracleホーム内の言語およびロケールごとのサブディレクトリにあります。たとえば、en-usの正確な場所はWebgateOH/webgate/ohs/lang/en-us/WebGate.xmlです。

    • デフォルト・ログアウト・ページは、WebgateOH/webgate/ohs/oamsso-bin/logout.plにあります。

  • カスタム・ページは、DCCをホストしているOracle HTTP Server上にデプロイするか、JSPまたはサーブレットの場合は、その前にあるWebコンテナ上にデプロイできます。

  • HTMLフォームが収集したデータをDCCにポストできるよう、構成可能なURLを使用します。認証スキームのactionチャレンジ・パラメータで、資格証明を収集できるURLを指定します。

  • requestid問合せパラメータの処理は必要ありません。

4.6.2 DCCを使用したフォームベース・ログイン・ページの作成

DCCを使用してフォームベース・ログイン・ページを作成するには:

  1. ユーザーの資格証明(ユーザー名およびパスワード)を送信できるHTMLフォームを作成します。
  2. フォームを、DCCを持つWebサーバー上の、保護されていないディレクトリまたは匿名認証スキームで保護されているディレクトリに置きます。
  3. フォームベース認証スキームを作成し、チャレンジURLとしてログイン・フォームへのパスを指定します。
  4. HTTP GETまたはPOSTを使用して、フォーム・アクションをコールします。
  5. ログイン・フォームのアクションで、ポリシーを使用してターゲットURLを保護します。
  6. チャレンジ・パラメータを認証スキームで構成します。
  7. 資格証明の処理に使用する認証モジュールを指定します。

4.6.3 DCCトンネリングのためのカスタム・ログインおよびエラー・ページについて

DCCトンネリングを使用する場合、カスタム・ログインおよびエラー・ページを作成できます。デフォルト・ページには、次の場所からアクセスします。

  • ログイン・ページ: http(s)://DCChost:DCCport/oam/pages/login.jsp

  • エラー・ページ: http(s)://DCChost:DCCport/oam/pages/servererror.jsp

これらのカスタム・ページを作成、使用するには、手順(「DCCを使用したフォームベース・ログイン・ページの作成」に類似)に従ってください。資格証明収集およびDCCトンネリングの詳細は、資格証明収集およびログインの理解に関する項を参照してください。

4.7 カスタム・エラー・ページおよびカスタム・ログアウト・ページのデプロイメント・パスの指定

カスタム・アプリケーションをデプロイする際、カスタム・エラーおよびログアウト・ページは特定のパスにする必要があります。エラー・ページのパスは次のとおりです。

http(s)://<host>:<port>/<context>/pages/Error.<pageExtension>

ログアウト・ページのパスは次のとおりです。 

http(s)://<host>:<port>/<context>/pages/Logout.<pageExtension>

contextおよびpageExtensionは、updateCustomPages WLSTコマンドを使用して構成できる変数です。pageExtensionのデフォルト値はjspですが、コマンドを実行している間、空白のままにしておくこともできます。updateCustomPagesによって、コンテキスト・パスおよびページ拡張子が構成に追加されます。 

<Setting Name="ssoengine" Type="htf:map">
  <Setting Name="ErrorConfig" Type="htf:map">
  <Setting Name="ErrorMode" Type="xsd:string">EXTERNAL</Setting>
  <Setting Name="CustomPageExtension" Type="xsd:string">html</Setting>
  <Setting Name="CustomPageContext" Type="xsd:string">SampleApp</Setting>
</Setting>
</Setting>

ノート:

詳細は、『Oracle Fusion Middleware Identity and Access ManagementのためのWebLogic Scripting Toolコマンド・リファレンス』のupdateCustomPagesに関する項を参照してください。