4 Miscellaneous Configuration Options of Oracle REST Data Services
This section explains how to configure Oracle REST Data Services for connecting to multiple databases for routing requests, and it refers to other documentation sources for other configuration information.
Note:
You must restart Oracle REST Data Services after making any configuration changes. For ensuring High Availability, Oracle recommends that you use a load balancer in front of multiple ORDS instances, so that rolling restarts can be achieved.Topics:
Support for Oracle RAC Fast Connection Failover
Oracle REST Data Services support the Fast Connection Failover (FCF) feature of Oracle Real Application Clusters (Oracle RAC).
Oracle REST Data Services runs with the Universal Connection Pool (UCP) in all the
Application Server environments that it supports, such as
WebLogic, Tomcat. UCP in turn supports Fast Connection
Failover . To enable FCF, Oracle Notification Service (ONS) must
to be enabled. To enable ONS, add entries to the list of
properties in the Oracle REST Data Services
settings.xml
configuration file as
shown in the following code snippet:
<entry key="jdbc.enableONS">true</entry>
<entry key= "jdbc.ONSConfig">nodes=racnode1:4200,racnode2:4200\nwalletfile=/oracle11/onswalletfile</entry>
<entry key="db.connectionType">customurl</entry>
<entry key="db.customURL">jdbc:oracle:thin:@(DESCRIPTION=(FAILOVER=ON)(ADDRESS_LIST=
(LOAD_BALANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=prod_scan.example.com)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=ISPRD)))|</entry>
After updating the defaults.xml
configuration file, Oracle REST Data Services need to be restarted for the changes to take effect.
-
Unplanned outages: When RAC detects an instance failure, it generates a FAN Down event which FCF picks up. FCF then terminates all connections to the failed instance and directs all future requests to the surviving RAC instances.
-
Planned outages: For instance, when a Database Administrator (DBA) wants to gracefully shut down a RAC instance for performing some maintenance activity. The instance shutdown generates a FAN Planned Down event which FCF picks up. FCF then directs all new requests to other RAC instances and drains or allows currently active transactions to complete.
Note:
Long running transactions may need to be terminated forcefully.Configuring ORDS with Kerberos Setup
This section explains how ORDS can be configured to reference a Kerberos file-based ticket cache and make a connection to an Oracle Database Kerberos authenticated user with the ORDS Runtime Privilege.
- Create a new user using external authentication
- Set up the environment variables
- Provide a valid ticket
- Add ORDS pool settings
Authorizing Oracle REST Data Services to Access Oracle Data Guard Protected Users
To access the database schema objects that are protected by an Oracle Data Vault Realm, it is necessary to grant a proxy user authorization to the Oracle REST Data Services Public User.
ORDS_PUBLIC_USER
to proxy the database HR
user:begin
DBMS_MACADM.AUTHORIZE_PROXY_USER('ORDS_PUBLIC_USER','HR');
end;
/
Configuring REST-Enabled SQL Service Settings
This section explains how to configure the REST- Enabled SQL service.
Note:
Enabling the REST- Enabled SQL service enables authentication against the Oracle REST Data Service enabled database schemas. This makes the database schemas accessible over HTTPS, using the database password. Oracle highly recommends that you provide strong secure database passwords- Run the following command:
ords --config <configuration_folder> config [--db-pool <pool_name>] set restEnabledSql.active true
- Restart Oracle REST Data Services.
Configuring the Maximum Number of Rows Returned from a Query
- Run the following command:
ords --config <configuration_folder> config set [--db-pool <pool_name>] misc.pagination.maxRows <number>
Note:
The default value formisc.pagination.maxRows
is 10000. - Restart Oracle REST Data Services.
Configuring ICAP Server Integration for Virus Scan
This section explains how to configure ORDS to integrate with ICAP server for virus scan.
ORDS PL/SQL gateway supports the offloading of virus scanning responsibilities to an
Internet Content Adaptation Protocol (ICAP) compliant virus scan server when the files
are uploaded. The hostname and port of the virus scan server is specified in the
icap.server
, icap.port
, and
icap.secure.port
global configuration properties.
APEX uses ORDS PL/SQL gateway. Once configured, this ICAP integration is also applied to file uploads in APEX.
- Run the following command:
ords --config <configuration_folder> config [--db-pool <pool_name>] set icap.port <number> ords --config <configuration_folder> config [--db-pool <pool_name>] set icap.server <name_or_ip>
- Restart Oracle REST Data Services.
- ICAP version 1.0
- Antivirus service named AVSCAN
- Antivirus service that supports action=SCAN
- Previews of at least 4 bytes
- Return header named X-Infection
RESPMOD icap://<icap_server>:<icap_port>/AVSCAN?action=SCAN ICAP/1.0
Host: <icap_server>:<icap_port>
Preview: 4
Allow: 204
Encapsulated: req-hdr=0 res-hdr=153 res-body=200
Configuring the Custom Error Pages
This section explains how to configure a custom error page instead of the error page generated by Oracle REST Data Services.
-
Run the following command:
ords --config /path/to/conf config set error.externalPath /path/to/error/pages/folder/
Where:
/path/to/error/pages/folder
is the path to a folder containing files that define the error pages. The files are stored in{status}.html
format. Where,{status}
is the HTTP status code for which you want to create a custom error page. -
Restart Oracle REST Data Services
Example 4-1 Configuring custom error page for “HTTP 404” status code
To configure a custom error page for the “HTTP 404 – Not Found” status, perform the following steps:
-
Create a file named
404.html
. -
Save it under
/usr/local/share/ords/error-pages/
folder. -
Configure the
error.externalPath
parameter to point to/usr/local/share/ords/errro-pages/
folder. -
Restart Oracle REST Data Services.
Managing ORDS Administrator Privilege
Access to the ORDS_ADMIN
PL/SQL package is provisioned through the
ORDS_ADMINISTRATOR_ROLE
. This role can be
provisioned through the ORDS_ADMIN
package to create
additional ORDS administrators.
Provisioning ORDS_ADMINISTRATOR_ROLE to a User
This section describes how to provision
ORDS_ADMINISTRATOR_ROLE
role to a user.
You can provision ORDS_ADMINISTRATOR_ROLE
role to a user by using
either the database GRANT
command or through the
ORDS_ADMIN.PROVISION_ADMIN_ROLE
PL/SQL method (as
an ORDS Administrator).
Example 4-2 Using Grant command
GRANT ORDS_ADMINISTRATOR_ROLE TO HR_ADMIN;
Example 4-3 Using ORDS_ADMIN package method
BEGIN
ORDS_ADMIN.PROVISION_ADMIN_ROLE(
p_user => 'HR_ADMIN');
END;
/
Unprovisioning ORDS_ADMINISTRATOR_ROLE from a User
This section describes how to unprovision
ORDS_ADMINISTRATOR_ROLE
from a user.
As an ORDS administrator, you can unprovision
ORDS_ADMINISTRATOR_ROLE
from a user by either using
the database REVOKE
command or through the
ORDS_ADMIN.UNPROVISION_ROLES
PL/SQL method.
Example 4-4 Using REVOKE command
REVOKE ORDS_ADMINSTRATOR_ROLE FROM HR_ADMIN;
Example 4-5 Using ORDS_ADMIN package method
BEGIN
ORDS_ADMIN.UNPROVISION_ROLES(
p_user => 'HR_ADMIN',
p_administrator_role => TRUE);
END;
/
Managing ORDS Runtime Privilege
The ORDS_RUNTIME_ROLE
database role allows a user to
act as a runtime user. A runtime user can manage and configure the runtime
connection resources required by an ORDS service instance. The
ORDS_PUBLIC_USER
is one such database user. When
additional runtime users are provisioned, it is possible to configure
discrete ORDS service instances with different destination addresses and
connection pools but hosted on the same Oracle database container.
It is recommended not to re-use a runtime user for any other purpose
as it accumulates the grants necessary to proxy to other users. A runtime
user only requires the CREATE SESSION
privilege in addition
to the ORDS_RUNTIME_ROLE
role.
Provisioning ORDS_RUNTIME_ROLE to a User
This section describes how to provision
ORDS_RUNTIME_ROLE
role to a user.
As an ORDS administrator, you can provision ORDS_RUNTIME_ROLE
role
to a user by using either the database GRANT
command or
through the ORDS_ADMIN.PROVISION_ADMIN_ROLE
PL/SQL
method.
Example 4-6 Using Grant command
GRANT ORDS_RUNTIME_ROLE TO ORDS_PUBLIC_USER_2;
Example 4-7 Using ORDS_ADMIN package method
BEGIN
ORDS_ADMIN.PROVISION_RUNTIME_ROLE(
p_user => 'ORDS_PUBLIC_USER_2');
END;
/
Unprovisioning ORDS_RUNTIME_ROLE from a User
This section describes how to unprovision the
ORDS_RUNTIME_ROLE
role from a user
As an administrator, you can unprovision the ORDS_RUNTIME_ROLE
from
a user, by either using the database REVOKE
command or
through the ORDS_ADMIN.UNPROVISION_ROLES
PL/SQL method.
Example 4-8 Using REVOKE command
REVOKE ORDS_RUNTIME_ROLE FROM ORDS_RUNTIME_USER_2;
Example 4-9 Using ORDS_ADMIN package method
BEGIN
ORDS_ADMIN.UNPROVISION_ROLES(
p_user => 'ORDS_RUNTIME_USER_2',
p_runtime_role => TRUE);
END;
/
Using OAuth2 in Non-HTTPS Environments
RESTful Services can be protected with the OAuth2 protocol to control access to nonpublic data. To prevent data snooping, OAuth2 requires all requests involved in the OAuth2 authentication process to be transported using HTTPS. The default behavior of Oracle REST Data Services is to verify that all OAuth2 related requests have been received using HTTPS. It will refuse to service any such requests received over HTTP, returning an HTTP status code of 403 Forbidden.
This default behavior can be disabled in environments where HTTPS is not available as follows:
-
Locate the folder where the Oracle REST Data Services configuration is stored, for example:
/path/to/conf
- Execute the following command:
ords --config /path/to/conf config set security.verifySSL false
-
Restart Oracle REST Data Services if it is running.
Note that it is only appropriate to use this setting in development or test environments. It is never appropriate to use this setting in production environments because it will result in user credentials being passed in clear text.
Note:
Oracle REST Data Services must be restarted after making configuration changes. See your application server documentation for information on how to restart applications.
Configuring ORDS Metadata Cache
This section explains how to configure the ORDS Metadata Cache.
As the number of REST services grow, the overhead of querying the database for
corresponding metadata can have a negative impact on the overall service performance and
throughput. Overtime, the queries for ORDS_METADATA
views take longer
time to complete. These queries are executed for every request. The ORDS metadata cache
can help improve the overall response time for REST services when the number of services
grow to an extent that querying the ORDS_METADATA
views for every
request becomes expensive. The ORDS metadata cache can temporarily hold a copy of
privilege and module metadata in memory to reduce the number of database queries
performed when a REST service request is received. The cache is disabled by default so
that the changes made to the metadata are applied immediately for any subsequent
request.
Table 4-1 Configuration Properties for ORDS Metadata Cache
Property | Data Type | Default Value | Description |
---|---|---|---|
cache.metadata.enabled |
Boolean | false |
Specifies a setting to enable or disable metadata caching. |
cache.metadata.timeout |
Duration | 30s |
Specifies a setting that determines for how long the metadata record remains in the cache. Longer the duration, it takes longer to view the applied changes. |