6 mod_plsqlからORDSへの移行
この章では、mod_plsqlアプリケーションをOracle REST Data Services (ORDS)に移行する方法を示します。
Oracle REST Data Servicesは、Oracle HTTP Serverおよびmod_plsqlのかわりとなるJava EEベースのサービスです。Oracle HTTP Serverのmod_plsqlアプリケーションは、新しいORDS構成ファイルを定義することでORDSに移行できます。beforeプロシージャ、afterプロシージャ、リクエスト検証ファンクション、owa_customパッケージ、ドキュメント・アップロード・プロシージャおよびドキュメント表などのmod_plsqlのデータベース・リソースは、ORDSへの移行時に変更する必要はありません。
6.1 Oracle HTTP Serverのmod_plsqlの認証
Oracle HTTP Serverのmod_plsqlアプリケーションは、データベース・アクセス記述子(DAD)ファイルで構成されます。
- 基本認証: ユーザー名とパスワードはDADファイルに格納されるため、エンド・ユーザーはログインする必要がありません。この方法は、公開情報を提供するWebページに便利です。
- 基本動的認証: ユーザーはブラウザの「HTTP基本認証」ダイアログ・ボックスに資格証明を入力します。ログアウトする唯一の方法は、ブラウザのすべてのインスタンスを閉じることです。
- カスタム認証: アプリケーションは、ユーザーが記述した認証ファンクションを呼び出して、データベース・レベルではなくアプリケーション内でユーザーを認証できます。
関連トピック
6.2 Oracle HTTP ServerのDADファイルの例
この項では、Oracle HTTP ServerのDADファイルの例を示します。
dads.conf
ファイルには、基本認証、基本動的認証およびカスタム認証を示す3つの場所と次のディレクティブが含まれています。
PlsqlBeforeProcedure
PlsqlAfterProcedure
PlsqlRequestValidationFunction
PlsqlDocumentTablename
PlsqlDocumentProcedure
例6-1 dads.confファイル
# ============================================================================
# mod_plsql DAD Configuration File
# ============================================================================
<Location /pls/basic_auth>
SetHandler pls_handler
Order deny,allow
Allow from all
AllowOverride None
PlsqlDatabaseUsername PRIVILEGED_USER
PlsqlDatabasePassword passwordF0R$0RD5Example
PlsqlDatabaseConnectString oracle-ee:1521:ORCLPDB1 ServiceNameFormat
PlsqlAuthenticationMode Basic
PlsqlBeforeProcedure sample_plsql_app_metadata.beforeProc
PlsqlAfterProcedure sample_plsql_app_metadata.afterProc
PlsqlRequestValidationFunction sample_plsql_app_metadata.validationFunc
PlsqlDocumentTablename privileged_user.doc_table
PlsqlDocumentProcedure privileged_user.upload
</Location>
<Location /pls/basic_dynamic_auth>
SetHandler pls_handler
Order deny,allow
Allow from all
AllowOverride None
PlsqlDatabaseConnectString oracle-ee:1521:ORCLPDB1 ServiceNameFormat
PlsqlAuthenticationMode Basic
PlsqlBeforeProcedure sample_plsql_app_metadata.beforeProc
PlsqlAfterProcedure sample_plsql_app_metadata.afterProc
PlsqlRequestValidationFunction sample_plsql_app_metadata.validationFunc
</location>
<Location /pls/custom_auth>
SetHandler pls_handler
Order deny,allow
Allow from all
AllowOverride None
PlsqlDatabaseUsername PRIVILEGED_USER
PlsqlDatabasePassword passwordF0R$0RD5Example
PlsqlDatabaseConnectString oracle-ee:1521:ORCLPDB1 ServiceNameFormat
PlsqlAuthenticationMode CustomOwa
PlsqlBeforeProcedure sample_plsql_app_metadata.beforeProc
PlsqlAfterProcedure sample_plsql_app_metadata.afterProc
PlsqlRequestValidationFunction sample_plsql_app_metadata.validationFunc
</location>
6.3 ORDSへのmod_plsql設定のマッピング
この項では、ORDSへのmod_plsql設定のマッピングを示します。
ORDSでは、Oracle HTTP Serverのmod_plsql DADファイルで定義される場所と同様の構成ファイルを指定できます。各構成ファイルはords_conf/ords/conf
ディレクトリに定義され、構成ファイルはords_conf/ords/url-mapping.xml
ファイルを使用して特定のURLにマップされます。ORDSには、mod_plsqlディレクティブを移行する際に使用できる次の構成可能なパラメータがあります。
表6-1 mod_plsqlディレクティブからORDS設定へのマッピング
mod_plsqlの設定 | ORDSの設定 | 説明 |
---|---|---|
PlsqlDatabaseUserName |
db.username |
データベースへのログインに使用するユーザー名を指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlDatabasePassword |
db.password |
データベースへのログインに使用するパスワードを指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlDatabaseConnectString |
次のような複数の設定があります。
|
Oracle Databaseへの接続を指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlAuthenticationMode |
security.requestAuthenticationFunction |
アクセスできるように、使用する認証モードを指定します。
ORDSの同等の構成パラメータの例: <entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry> ORDSとmod_plsqlは同等です。 |
PlsqlBeforeProcedure |
procedure.preProcess |
リクエストされたプロシージャのコール前に起動するプロシージャを指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlAfterProcedure |
procedure.postProcess |
リクエストされたプロシージャのコール後に起動するプロシージャを指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlRequestValidationFunction |
security.requestValidationFunction |
アプリケーション定義のPL/SQLファンクションを指定します。このファンクションにより、リクエストされたプロシージャのさらなる処理を許可または拒否できます。 ORDSとmod_plsqlは同等です。 |
PlsqlDocumentTablename |
owa.docTable |
すべてのドキュメントのアップロード先となるデータベース内の表を指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlDocumentProcedure |
N/A |
ドキュメントのダウンロード開始時にコールするプロシージャを指定します。 ORDSでは、ドキュメント・プロシージャはリクエストされたリソースです。構成ファイルには定義しません。 ORDSとmod_plsqlは同等です。 |
PlsqlDocumentPath |
N/A |
ORDSには同等のものはありません。 |
PlsqlDefaultPage |
misc.defaultPage |
URLに何も指定されていない場合にコールするデフォルトのプロシージャを指定します。 ORDSとmod_plsqlは同等です。 |
PlsqlErrorStyle |
debug.printDebugToScreen |
mod_plsqlエラーのエラー・レポート・モードを指定します。
ORDSとmod_plsqlは同等です。 |
PlsqlExclusionList |
security.exclusionList |
ブラウザから直接実行することが禁じられているプロシージャ、パッケージまたはスキーマ名のパターンを指定します。 構成可能なパラメータを理解するを参照してください。 ORDSとmod_plsqlは同等です。 |
PlsqlIdleSessionCleanupInterval |
jdbc.InactivityTimeout |
アイドル・データベース・セッションがクローズされてクリーン・アップされるまでの時間(分数)を指定します。 値は0からN秒です。ここで、0 (デフォルト)はアイドル接続がプールから削除されないことを意味します。 ORDSとmod_plsqlは同等です。 |
PlsqlMaxRequestsPerSession |
jdbc.MaxConnectionReuseCount |
プーリングされたデータベース接続がクローズされて再オープンされる前に処理する必要のある最大リクエスト数を指定します。 デフォルト値は1000です。 ORDSとmod_plsqlは同等です。 |
PlsqlInfoLogging |
N/A | 構成可能なパラメータを理解するを参照してください。 |
PlsqlLogDirectory |
N/A | 構成可能なパラメータを理解するを参照してください。 |
PlsqlLogEnable |
N/A | 構成可能なパラメータを理解するを参照してください。 |
PlsqlSessionStateManagement |
N/A |
各リクエストの終了時に、パッケージとセッションの状態をクリーン・アップする方法を指定します。 ORDSは、各リクエストの最後にdbms_session.modify_package_state (dbms_session.reinitialize )を常に実行します。
|
PlsqlAlwaysDescribeProcedure |
N/A |
mod_plsqlアプリケーションでプロシージャを実行する前に記述する必要があるかどうかを指定します。 ORDSでは、常に最初のアクセスでプロシージャが記述され、その定義がキャッシュされます。シグネチャの変更が検出され、再度キャッシュされます。 |
PlsqlConnectionValidation |
N/A |
mod_plsqlモジュールが接続プールで終了済接続を検出するために使用するメカニズムを指定します。 ORDSは常に借用時に接続を検証します。 |
PlsqlFetchBufferSize |
N/A |
結果が32Kを超える場合、ORDSは結果を32K VARCHARまたはCLOBとして生成するため、該当するものはありません。 |
PlsqlNLSLanguage |
N/A |
NLS_LANG変数を指定します。 ORDS、JavaおよびJDBCではUnicodeが使用されます。 |
PlsqlTransferMode |
N/A |
|
PlsqlBindBucketLengths |
N/A |
コレクション・バインド内の要素数のバインド中に使用する丸めサイズを指定します。 mod_plsqlではほとんど使用されず、JDBCには同等の概念がありません。 |
PlsqlBindBucketWidths |
N/A |
コレクション・バインド内の要素数のバインド中に使用する丸めサイズを指定します。 mod_plsqlではほとんど使用されず、JDBCには同等の概念がありません。 |
PlsqlCacheCleanupTime |
N/A | ORDSには同等のものはありません。 |
PlsqlDMSEnable |
N/A | ORDSはDMSをサポートしていません。 |
PlsqlSessionCookieName |
N/A | ORDSでは、PL/SQLゲートウェイ・コールのセッション管理は提供されません。 |
PlsqlCacheDirectory |
N/A | ORDSには同等のものはありません。 |
PlsqlCacheEnable |
N/A | ORDSには同等のものはありません。 |
PlsqlCacheMaxAge |
N/A | ORDSには同等のものはありません。 |
PlsqlCacheMaxSize |
N/A | ORDSには同等のものはありません。 |
PlsqlCacheTotalSize |
N/A | ORDSには同等のものはありません。 |
PlsqlCGIEnvironmentList |
N/A | ORDSには同等のものはありません。 |
PlsqlConnectionTimeout |
N/A | ORDSには同等のものはありません。 |
PlsqlPathAlias |
N/A | ORDSには同等のものはありません。 |
PlsqlPathAliasProcedure |
N/A | ORDSには同等のものはありません。 |
PlsqlUploadAsLongRaw |
N/A | ORDSには同等のものはありません。 |
6.4 ORDS構成ファイルの例
次の項では、サンプルのmod_plsqlアプリケーションをORDSに移行する方法を示します。
6.4.1 基本認証の構成ファイルの例
例6-2 ords_conf/ords/conf/basic_auth.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>
<entry key="db.username">PRIVILEGED_USER</entry>
<entry key="db.password">!passwordF0R$0RD5Example</entry>
<!-- Example url -->
<!-- See url-mapping.xml -->
<!-- http://localhost:8086/ords/pls/basic_auth/sample_plsql_app.sample_public_proc-->
<!-- http://localhost:8086/ords/pls/basic_auth/sample_plsql_app.privileged_public_proc-->
<entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
<entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
<entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
<entry key="owa.docTable">sample_plsql_app.doc_table</entry>
</properties>
6.4.2 基本動的認証の構成ファイルの例
例6-3 ords_conf/ords/conf/basic_dynamic_auth.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>
<!-- NOTE THAT IF THIS USER HAS EXECUTE PRIVILEGE ON THE RESOURCE THEN jdbc.auth.enabled IS IGNORED -->
<!-- IF THIS USER DOES NOT HAVE EXECUTE PRIVILEGE ON THE RESOURCE THEN jdbc.auth.enabled IS INVOKED AND THE CREDENTIALS OF A PRIVILEGED USER HAS TO BE PROVIDED-->
<entry key="db.username">NON_PRIVILEGED_USER</entry>
<entry key="db.password">!passwordF0R$0RD5Example</entry>
<entry key="jdbc.auth.enabled">true</entry>
<!-- Example url -->
<!-- See url-mapping.xml -->
<!-- INVOKE jdbc.auth.enabled : http://localhost:8086/ords/pls/basic_dynamic_auth/sample_plsql_app.sample_privileged_proc -->
<!-- IGNORE jdbc.auth.enabled : http://localhost:8086/ords/pls/basic_dynamic_auth/sample_plsql_app.sample_public_proc -->
<!-- Because jdbc.auth.enabled is ignored when referencing the sample_public_app, the beforeProc,afterProc and validationFunc must be accessible by NON_PRIVILEGED_USER -->
<!-- The following objects are executed by the same credentials used to access the resource -->
<!-- If the resource can be accessed by the db.username then that connection is used to access these methods -->
<!-- If the resource cannot be accessed by the db.username then jdbc.auth.enabled is invoked and those credentials as used to access these methods -->
<entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
<entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
<entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
</properties>
6.4.3 カスタム認証の構成ファイルの例
例6-4 ords_confs/ords/conf/custom_auth.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>
<entry key="db.username">PRIVILEGED_USER</entry>
<entry key="db.password">!passwordF0R$0RD5Example</entry>
<!-- Example url -->
<!-- See url-mapping.xml -->
<!-- http://localhost:8086/ords/pls/custom_auth/sample_plsql_app.sample_proc -->
<!-- privileged_user.owa_custom.authorize requires the following as the custom login -->
<entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
<entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
<entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
<entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry>
</properties>
6.5 ORDSとURLのマッピングの例
この項では、ベースパスURLと構成ファイルのマッピングの例を示します。
例6-5 ords_conf/ords/url-mapping.xml
<?xml version="1.0" encoding="UTF-8"?>
<pool-config xmlns="http://xmlns.oracle.com/apex/pool-config">
<pool name="basic_auth" base-path="/pls/basic_auth" updated="2018-07-17T20:52:29.045Z" />
<pool name="basic_dynamic_auth" base-path="/pls/basic_dynamic_auth" updated="2018-07-17T20:52:29.045Z" />
<pool name="custom_auth" base-path="/pls/custom_auth" updated="2018-07-17T20:52:29.045Z" />
</pool-config>
6.6 ORDSのデフォルト構成の例
この項では、ORDSのデフォルト構成設定の例を示します。
default.xml
ファイルには、すべての構成で使用されるデータベース接続の詳細が含まれています。
注意:
プロシージャ検証キャッシュをオフにするには、security.maxEntries
値を0に設定します。これはOracle HTTP Serverのmod_plsqlをエミュレートするために必要となります。
例6-6 ords_conf/ords/default.xml
<?xml version = '1.0' encoding = 'UTF-8'?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<!-- by default security.maxEntries = 2000 which means 2000 procedures validity will be cached-->
<!-- this is fine for applications like apex where the validation of a procedure does not change -->
<!-- for applications migrating from mod_plsql the cache should be disabled so that procedures validity is determined for each request -->
<!-- this is done by setting security.maxentries to 0 -->
<entry key="security.maxEntries">0</entry>
<entry key="db.hostname">oracle-ee</entry>
<entry key="db.port">1521</entry>
<entry key="db.servicename">orclpdb1</entry>
</properties>
6.7 ORDS認証
ORDSでは、mod_plsqlからの1対1のマッピングを提供することで、HTTP基本認証を実行できます。ORDSでは、よりセキュアな認証方法を使用できます。
6.7.1 基本認証
この項では、ORDSを使用して実装される基本認証について説明します。
db.username
には、リソースへのアクセスに必要な権限が必要となります。
注意:
エントリsecurity.requestAuthenticationFunction
は指定しません。
6.7.2 基本動的認証
この項では、ORDSを使用して基本動的認証を実装する方法について説明します。
リソースへのアクセスに基本動的認証を指定する場合は、ORDS構成ファイルにデフォルトのdb.username
およびdb.password
を指定する必要があります。
<entry key="jdbc.auth.enabled">true</entry>
エントリの値がtrue
である。security.requestAuthenticationFunction
エントリが指定されていない。- ORDSレスポンスによってブラウザの「基本HTTP認証」ダイアログ・ボックスが表示され、ユーザーが入力する資格証明に必要な権限があり、リソースが使用可能になる。
注意:
資格証明をブラウザの「HTTP認証」ダイアログ・ボックスで入力する場合、ログアウトする唯一の方法は、ブラウザのすべてのインスタンスを閉じることです。
6.7.3 カスタム認証
この項では、ORDSを使用してカスタム認証を実装する方法について説明します。
カスタム認証を実行するファンクションを指定します。このファンクションはowa変数にアクセスできます。リソースは、次のファンクションがTRUE
値を返す場合にのみ使用できます。
<entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry>
/**
* OWA_CUSTOM used in mod_plsql when the following is used in the dad configuration file
PlsqlAuthenticationMode Custom
In ORDS environment this can reside in any schema as long as the connection has execute privileges
In mod_plsql this has to reside in the connections schema as you cannot specify the name of the schema,package or function
ex: PlsqlAuthenticationMode CustomOwa
*/
CREATE OR REPLACE PACKAGE OWA_CUSTOM AS
/**
* Response:
>IF Failed
WWW-Authenticate in response header
Authorization Required
You are not authorized to access the requested resource. Check the supplied credentials (e.g., username and password).
*/
FUNCTION authorize RETURN BOOLEAN;
END OWA_CUSTOM ;
/
6.8 ORDSの機能
この項では、mod_plsqlアプリケーションからORDSに移行するときに便利なORDS機能について説明します。
トピック:
6.8.1 検証機能のリクエスト
この項では、リクエスト検証ファンクションの使用について説明します。
リクエスト検証ファンクションは、リソースへのアクセスを制限します。リクエスト検証ファンクションはリクエストされているリソースの名前とともに指定し、レスポンスではTRUE
値またはFALSE
値が返されます。
リクエスト検証ファンクションがFALSE
値を返した場合、ORDSはリクエストを終了します。
例6-7 security.requestValidationFunction
<entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
検証ファンクションには任意の名前を選択できます。ただし、シグネチャは次の形式にする必要があります。
CREATE OR REPLACE FUNCTION validationfunc(procedure_name VARCHAR2) RETURN BOOLEAN IS
。
6.8.2 事前処理機能
この項では、procedure.preProcess
ORDS構成パラメータについて説明します。
procedure.preProcess
ORDS構成パラメータには、リクエストされたリソースの前に実行されるプロシージャのカンマ区切りリストを指定できます。
例6-8 procedure.preProcess
次のコード・スニペットの例は、ログインのユースケースを示しています。
<entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
6.8.3 事後処理機能
この項では、procedure.postProcess
ORDS構成パラメータについて説明します。
procedure.postProcess
ORDS構成パラメータには、リクエストされたリソースの後に実行されるプロシージャのカンマ区切りリストを指定できます。
例6-9 procedure.postProcess
次のコード・スニペットの例は、ログアウトのユースケースを示しています。
<entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
6.8.4 ファイル・アップロード機能
この項では、ORDSのファイル・アップロード機能について説明します。
ORDS構成パラメータowa.docTable
は、アップロードされたファイルを保持する表名を定義します。
例6-10 表のアップロード
CREATE TABLE DOC_TABLE (
NAME VARCHAR(256) UNIQUE NOT NULL,
MIME_TYPE VARCHAR(128),
DOC_SIZE NUMBER,
DAD_CHARSET VARCHAR(128),
LAST_UPDATED DATE,
CONTENT_TYPE VARCHAR(128),
CONTENT LONG RAW,
BLOB_CONTENT BLOB );
例6-11 プロシージャのアップロード
アップロード・ファンクションには任意の名前を選択できます。ただし、シグネチャは次のPOSTリクエストと一致している必要があります。
--The parameters of the procedure should match the parameters of the request
--The procedure is called after ORDS performs the file upload/insert.
--This procedure can rollback the file INSERT as it is in the same transaction as the INSERT
CREATE OR REPLACE PROCEDURE upload (filename VARCHAR2 DEFAULT NULL)
例6-12 ファイル・アップロードのためのCurlコマンド
curl -i -X POST -F 'filename=@helloworld.txt' "http://localhost:8086/ords/pls/basic_auth/example_user1.upload