SAML認証で使用したデバッグ手順

 SAML認証のデバッグで使用した、いくつかの手順を紹介します。

公開鍵証明書の確認

SAMLの認証スキームの編集画面より、証明を登録したときに証明書が無効ですと表示されれることがあります。

証明書の貼り付け方に問題があるのか（コピペミスなど）、または証明書自体に問題があるのか、このメッセージだけでは特定が難しいです。openssl x509 -textを実行することで、証明書の内容が確認できている場合は、さらに難しいです。

openssl x509 -in 公開鍵証明書ファイル -text -noout

マニュアルには記載されていませんが、Oracle APEXで扱う公開鍵証明書を検証するファンクションがあります。WWV_FLOW_PUBLIC_KEY_UTIL.IS_CERTIFICATEです。公開鍵証明書を文字列として受け取り、証明書として正しければTRUE、そうでなければFALSEを返します。

このファンクションを使った検証スクリプトの雛形です。

opensslではパースできるのに、上記でFALSEとなる（Certificate is NOT valid.が印刷される）場合は、Oracle APEXが提供しているファンクションを使って、証明書がパースできるかどうか確認します。WWV_FLOW_PUBLIC_KEY_UTIL.PARSE_CERTIFICATEを使います。

このファンクションを使った検証スクリプトの雛形です。

スクリプトの実行にあたっては、事前にAPEXのスキーマをCURRENT_SCHEMAに設定します。

APEX 22.1の場合は、APEX_220100がAPEXがインストールされているスキーマになります。

alter session set current_schema = APEX_220100;

残念ながらAutonomous Databaseでは、APEXのスキーマは保護されています。そのため、内部で使用するパッケージに含まれるプロシージャやファンクションを呼び出すことはできません。オンプレの環境を用意する必要があります。

正常に実行されると、以下のように表示されます。

SQL> alter session set current_schema = apex_220100;

Session altered.

SQL> @verify-cert

Certificate is valid.

PL/SQL procedure successfully completed.

SQL> @parse-cert

cert_sig_algorithm = c_sha256_rsa

key_algorithm = RSA

key_length = 2048

PL/SQL procedure successfully completed.

SQL> 

HARファイルの確認

ORDSへ送信されるOriginヘッダーの内容は、HARをエクスポートして確認しています。

ChromeまたはEdgeを例に取ります。ブラウザの開発者ツールを実行し、ネットワークを開きます。

最初に、それまでの記録をクリアします。

レコード・ボタンをクリックして、ネットワーク・ログの記録を開始します。記録中は、ボタンが赤くなります。

ネットワーク・ログを記録するURLにアクセスします。

記録したデータを、ファイルにダウンロードします。

レコード・ボタンをクリックし、レコーディングを停止します。

ダウンロードしたファイルの内容を確認します。

HTTPヘッダーなどの情報を確認することができます。

ブラウザごとに操作に違いがあります。使用しているブラウザでのHARの取得方法を確認しましょう。

d0、d1、d2スクリプトの使用

SAMLコールバックのデバッグ・メッセージを取得するには、インスタンス全体でデバッグを有効にする必要があります。

このためにAPEXのダウンロード・メディアのapex/utilities/debug以下に配置されているd0.sqlを使用します。

APEXのデータベースに、sysまたはsystemで接続し、CURRENT_SCHEMAをAPEXのスキーマに設定します。続いてd0.sqlを実行します。デバッグ・レベルが9、つまり完全トレースになります。APEX全体への影響が大きいため、本番環境での実施には特別な注意が必要です。

SQL> alter session set current_schema = apex_220100;

Session altered.

SQL> @d0

Changed debug level from "" to "9"

SQL> 

SAMLのサインインを実施します。

再度d0.sqlを実行し、デバッグ・メッセージの取得を停止します。

SQL> alter session set current_schema = apex_220100;

Session altered.

SQL> @d0

Changed debug level from "" to "9"

SQL> @d0

Changed debug level from "9" to ""

SQL> 

d1.sqlを実行し、直近のAPEXへのアクセスを一覧します。

PAGE_VIEW_ID  STARTED  SECS   LVL  COUNT PATH_INFO       APP:PAGE SESSION_ID   WORKSPACE USER

------------- -------- ------ --- ------ ---------------------------- ---------- --------------------------------- -------------------- --------------------------------

@d2 8003      06:00:00 0.03       16 DBMS_SCHEDULER/ORACLE_APEX_M 0   Unknown

AIL_QUEUE

@d2 8004      06:00:00 0.01       5 DBMS_SCHEDULER/ORACLE_APEX_W 0   Unknown

S_NOTIFICATIONS

@d2 8005      06:00:02 0.01       9 DBMS_SCHEDULER/ORACLE_APEX_P 0   Unknown

URGE_SESSIONS

@d2 8006      06:00:10 0.20 WRN    220 show       4500:1000  0-16849648434733   INTERNAL nobody

PAGE_VIEW_ID  STARTED  SECS   LVL  COUNT PATH_INFO       APP:PAGE SESSION_ID   WORKSPACE USER

------------- -------- ------ --- ------ ---------------------------- ---------- --------------------------------- -------------------- --------------------------------

@d2 8007      06:00:11 0.72     1610 show       4550:1 0-16849648434733   INTERNAL nobody

@d2 8618      06:00:24 0.18 WRN    315 show       102:1 0-9657959965886   APEXDEV nobody

@d2 8619      06:00:43 0.36 WRN    508 ajax plugin       102:1 0-9657959965886   APEXDEV nobody

30 rows selected.

SQL> 

アプリケーションIDやページIDなどを参照して、確認すべきページ・ビューIDを特定します。SAMLコールバックのPATH_INFOはajax pluginになります。

上記の例では@d2 8619より、SAMLコールバックのデバッグ・メッセージを確認することができます。

SQL> @d2 8619

デバッグ・メッセージが手元のファイルにダウンロードされ、エディタが開きます。

詳細なデバッグ・メッセージを参照できます。通常は、このデータをファイルに保存してオラクルのサポートに提出することになるでしょう。

画面へのエラー詳細表示

ORDSのプロパティdebug.printDebugToScreenをtrueにすると、ブラウザの画面にエラーの詳細が表示されます。マニュアルのこちらに説明があります。

debug.printDebugToScreenがfalse（デフォルト）のときに、ORDSでエラーが発生した画面です。

ORDS 22.1にて、上記のプロパティをtrueにする方法です。ordsコマンドのパスおよび構成ファイルが含まれるディレクトリは、インストール毎に異なります。

/usr/local/bin/ords --config /etc/ords/config config set debug.printDebugToScreen true

[oracle@apex ~]$ /usr/local/bin/ords --config /etc/ords/config config set debug.printDebugToScreen true

ORDS: Release 22.1 Production on Tue Jun 14 04:39:29 2022

Copyright (c) 2010, 2022, Oracle.

Configuration:

  /etc/ords/config/

The global setting named: debug.printDebugToScreen was set to: true

[oracle@apex ~]$ 

変更を有効にするには、ORDS（またはTomcat）を再起動する必要があります。

ORDS 21.4.3以前では、以下のコマンドを実行します。

java -jar ords.war set-property debug.printDebugToScreen true

[oracle@ords ords]$ java -jar ords.war set-property debug.printDebugToScreen true

2022-06-14T04:45:10.789Z INFO        Modified: /opt/oracle/ords/conf/ords/defaults.xml, setting: debug.printDebugToScreen = true

[oracle@ords ords]$

ORDS 221.1および21.4.3の双方で、上記のコマンドによって、設定ファイルに以下の行が書き込まれます。設定ファイルの名前はORDS 22.1ではsettings.xml、ORDS 21.xではdefaults.xmlになります。

<entry key="debug.printDebugToScreen">true</entry>

以上の変更より、エラーの詳細が画面に表示されます。

エラー発生時の詳細が画面に表示されるため、この状況での本番運用は望ましくありません。デバッグが終了したら、以下のコマンドにより設定を削除します。

/usr/local/bin/ords --config /etc/ords/config config delete debug.printDebugToScreen

[oracle@apex ~]$ /usr/local/bin/ords --config /etc/ords/config config delete debug.printDebugToScreen

ORDS: Release 22.1 Production on Tue Jun 14 05:00:18 2022

Copyright (c) 2010, 2022, Oracle.

Configuration:

  /etc/ords/config/

The global setting named: debug.printDebugToScreen was removed from the configuration

[oracle@apex ~]$ 

ORDS 21.xではエディタでdefaultsxmlを開いて、該当の設定を削除します。

変更の反映には、ORDSの再起動が必要です。

SAML認証で使用した、デバッグ手順の紹介は以上になります。

完

APEXアプリケーションの開発用途のワークスペースを作成する

 データベースが２つあり、それぞれAPEXがインストールされているとします。片方のデータベースからコンポーネント（ページも同様）単位でエクスポートを行い、別のデータベースの同じアプリケーションにインポートする方法を紹介します。

コンポーネントおよびページ単位のエクスポート/インポートを行うには、両方のデータベースのワークスペースIDとアプリケーションIDが一致している必要があります。アプリケーションについてはIDが一致しているだけではなく、アプリケーション自体があらかじめエクスポート/インポートによって作成されていることが必須です。

以下より、そのような条件を満たす開発向けのインスタンスを作成する方法を紹介します。

説明のためにAlways FreeのAutonomous Transaction Processingを使います。

最初にインスタンスAPEXPRODが作成済みとします。APEXのワークスペースとしてAPPWKSPが作成されています。

アプリケーションとしては、サンプル・データセットのEMP/DEPTをインストールすると作成できるデモ - 従業員 / 部門を使います。

スキーマAPPWKSPには、表EMPやDEPTといったオブジェクトが作成されています。

select * from user_objects

ワークスペースAPPWKSPのワークスペースIDを確認します。

select workspace_id, workspace from apex_workspaces where workspace = 'APPWKSP'

開発用途のワークスペースを作成するために必要な情報は以上です。

データベースのクローンを作成して対応

APEXのワークスペースやアプリケーションもデータベースに保存されているため、データベースごとクローンすると開発用途の環境が出来上がります。その場合は特にワークスペースIDを意識する必要がありません。

Always Freeのデータベースは２つまで作成できるため、他にデータベースを作成していなければデータベースのクローンを実行できます。

OCIのコンソールの他のアクションのクローンの作成を実行します。

クローン・タイプの選択として、フル・クローンを選びます。ソースのクローニングはデータベース・インスタンスからのクローニングを選択します。過去の状態が必要な場合、または、現在稼働しているデータベースに極力影響を与えたくない場合は、バックアップからのクローニングも選択対象になるでしょう。

これ以外に入力する情報は、データベースの新規作成に必要な情報と同じです。

以下の例では、表示名とデータベース名をAPEXDEVとしています。

管理者資格証明のパスワードを入力し、Autonomous Databaseのクローンの作成を実行します。

しばらくすると、データベースがクローンとして作成されます。

クローンしたデータベースには、APEXのワークスペース、アプリケーション、登録済みのユーザー等も含まれます。そのため、クローン元と同様にワークスペース名APPWKSP、ユーザーAPPWKSPにてサインインできます。

作成済みのアプリケーションもクローンに含まれています。

ワークスペースIDも同じ値になります。

別のデータベースでの対応

元になるインスタンスよりワークスペースのエクスポートを実行します。

管理サービスにサインインし、ワークスペースの管理を開きます。

ワークスペースのエクスポートを開きます。

エクスポートするワークスペース（今回はAPPWKSP）を選択し、ワークスペースのエクスポートを実行します。

チーム開発を含めるははい、エクスポート・タイプは最小がデフォルトです。そのまま変更せず、ファイルを保存をクリックします。

ワークスペース名.sql、今回の例ではAPPWKSP.sqlというファイルが、ワークスペースのエクスポートとしてダウンロードされます。ファイルがダウンロードされたら、取消をクリックしてダイアログを閉じます。

エクスポート・タイプは最小の他に、完全も選択可能です。ただし、ヘルプには以下のように記載されているので、通常は最小を選択します。

SQLスクリプト、SQLコマンドの履歴、保存されたSQL、ユーザー・プリファレンス、開発者のログイン履歴、電子メール・ログおよびユーザー・インタフェースのデフォルトを含め、すべてのワークスペース・アーティファクトを別のインスタンスに複製する場合にのみ、「完全」に設定します。ほとんどの場合は、デフォルト値「最小」を変更しないでください。

エクスポートしたワークスペースを、開発用途のデータベースにインポートします。

APEXの管理サービスにサインインし、ワークスペースの管理を開きます。

ワークスペースのインポートを開きます。

ファイルのインポートとして、エクスポートしたワークスペースのファイル（今回はAPPWKSP.sql）を選択します。

次へ進みます。

インストールをクリックして、ワークスペースをインポートします。

デフォルト・パーシング・スキーマの作成について確認されます。

APEXのワークスペースのインポートには、ワークスペースに紐づいていたスキーマおよびスキーマに含まれるデータベース・オブジェクトは含まれません。あらかじめ（または、ワークスペースの作成後に）元のデータベースからData Pumpなどでエクスポート/インポートを行い、別途複製する必要があります。

今回は、スキーマAPPWKSPを新規作成しています。次へ進みます。

表示されたプライマリ・スキーマおよび指定された追加スキーマへの完全なアクセス権を持つワークスペースのインストールを実行する場合に選択してください。にチェックを入れます。

次へ進みます。

インポートするワークスペースのワークスペースIDは、元のワークスペースIDと同じになります。

ワークスペースのインストールを実行します。

ワークスペースのインポートが完了します。今回の手順では、スキーマAPPWKSPも作成されます。

既存のワークスペースより、インポートされたワークスペースを確認できます。

ワークスペースのエクスポート/インポートではなく、単にワークスペースを作成する場合は、ワークスペースの作成時に詳細を開き、ワークスペースIDを指定します。

この場合でも、開発用途のワークスペースとして使用できますが、ワークスペースに作成されたApplication Expressユーザーなど、ワークスペースに構成済みの情報はコピーされません。

ページのエクスポートとインポートの確認

データベースAPEXPRODよりAPEXアプリケーションをエクスポートし、開発用途のデータベースAPEXDEVへインポートします。ワークスペースはAPPWKSPです。

データベースAPEXDEVのワークスペースAPPWKSPにサインインし、アプリケーションのインポートを開始します。

アプリケーションのインポート時に、次のアプリケーションとしてインストールとして、エクスポート・ファイルのアプリケーションID 100を再利用を選択します。アプリケーションIDの数値はアプリケーションによって異なりますが、再利用をすることにより同じアプリケーションIDにてインストールされます。

サンプル・データセットのEMP/DEPTをインストールし、表EMPとDEPTをインストールしておきます。

データベースAPEXDEVのワークスペースAPPWKSPにサインインし、ページの新規作成とエクスポートを行います。

アプリケーションデモ - 従業員/部門に、表EMPを操作する対話グリッドのページを作成します。

ページ作成ウィザードを起動し、フォームを選択します。

編集可能対話グリッドを選択します。

ページ名は対話グリッドとします。次へ進みます。

ナビゲーションのプリファレンスとして、新規ナビゲーション・メニュー・エントリの作成を選択します。

次へ進みます。

データ・ソースの表/ビューの名前として、EMPを指定します。作成をクリックします。

対話グリッドのページが作成されます。作成されたページを実行すると、以下のようになります。

ナビゲーション・メニューに対話グリッドが表示されます。

ページのユーティリティ・メニューを開いて、エクスポートを実行します。

指定されているページを確認し、ページのエクスポートを実行します。

fアプリケーションID_page_ページ番号.sql（今回はf100_page_7.sql）というファイルがダウンロードされます。

このファイルを、開発用途のデータベースにインポートします。

アプリケーション・ビルダーよりインポートを実行します。

ドラッグ・アンド・ドロップの領域に先ほどダウンロードしたファイルf100_page_7.sqlを選択します。ファイル・タイプとして、データベース・アプリケーション、ページまたはコンポーネントのエクスポートを選択します。

次へ進みます。

ファイルのアップロードが完了したので、次へ進みます。

 ページの起点として、このページは、現行のワークスペースのアプリケーションからエクスポートされました。と表示されます。

ページのインストールを実行します。

ページがインポートされます。ページを実行して、結果を確認します。

ページのみのインポートなので、ナビゲーション・メニューは作成されていません。

以上で、ページ単位のエクスポート/インポートの手順を確認できました。

Oracle APEXのアプケーション作成の参考になれば幸いです。

完