Installing and Configuring Customer Managed ORDS on Autonomous Database

About Customer Managed Oracle REST Data Services on Autonomous Database

When you provision an Autonomous Database instance, by default Oracle REST Data Services (ORDS) is preconfigured and available for the instance. With the default ORDS, Oracle performs any required configuration, patching, and maintenance. Additionally, you can also configure Autonomous Database to use ORDS running in a customer managed environment.

When you use the default ORDS on Autonomous Database, you cannot modify any of the ORDS configuration options. For example, with the default configuration, the JDBC connection pools have a maximum of 100 connections and the connections for ORDS are preconfigured to use the LOW database service. Use a customer managed environment if you want manual control of the configuration and management of Oracle REST Data Services. For example, use this option when your applications require larger connection pools or if you need more control over the ORDS configuration options.

When ORDS runs in a customer managed environment, you are responsible for configuration, patching, and maintenance of ORDS in the customer managed environment. After you configure Autonomous Database to use your customer managed ORDS in addition to the existing autonomously managed ORDS, you can route ORDS HTTPS traffic through your environment. The default Autonomous Database web server and ORDS are still running and ORDS traffic goes to the ORDS running in the customer managed environment. This provides an additional and alternative HTTPS solution for Autonomous Database.

Installing and configuring a customer managed environment for ORDS allows you to run ORDS with configuration options that are not possible using the default Oracle managed ORDS available with Autonomous Database.

Installing and configuring a customer managed environment for ORDS is only supported with Autonomous Database on Shared Exadata Infrastructure.

Note:

Oracle REST Data Services 19.4.6 or higher is required to use a customer managed environment for ORDS with Autonomous Database.
Installing and configuring a customer managed environment for ORDS is only supported with Autonomous Database on Shared Exadata Infrastructure.

Downloading Wallet and Verifying Connection to Autonomous Database

You need to configure ORDS to connect to the Autonomous Database. With Oracle REST Data Services (ORDS) running in a customer managed environment, you need to obtain the Autonomous Database wallet on the system that runs the customer managed ORDS. Perform the following steps to download the wallet and verify the connection to the Autonomous Database:

Download the wallet for the Autonomous Database instance. Alternatively you can use the OCI CLI to generate the wallet. See generate-wallet for information on using the CLI.
Verify that you can connect from the customer managed environment where you are installing and configuring ORDS to your Autonomous Database. For example, using SQLcl and the wallet you download in Step 1, verify the connection as follows:
1. Connect with SQLcl.
  See Also:
  - Connect with Oracle SQLcl Cloud Connection for Autonomous Data Warehouse environment.
  - Connect with Oracle SQLcl Cloud Connection for Autonomous Transaction Processing environment.
2. View the database services and connect to your Autonomous Database from the customer managed environment.
```
SQL> show tns
TNS_ADMIN set to: /var/folders/4r/path/T/oracle_cloud_config_path

Available TNS Entries
---------------------
dbname_high
dbname_low
dbname_medium


SQL> conn admin@dbname_low
Password? (**********?) *****************
Connected.
SQL>
```

Creating an Oracle REST Data Services Runtime Database User

To use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment, you must create an ORDS runtime database user, to which ORDS can connect.

Perform the following steps to create the ORDS runtime user. This user is used to proxy to all rest enabled users in your database.

Connect to your Autonomous Database as the ADMIN user.
Create a new database user and grant the required privileges as follows:
```
CREATE USER "ORDS_PUBLIC_USER2" IDENTIFIED BY <password>;
GRANT "CONNECT" TO "ORDS_PUBLIC_USER2";
```
ORDS_PUBLIC_USER2 is the recommended database user name although you can choose a different database user name. If you choose a different user name, then all the steps need to use the user name you choose.
Grant the ORDS runtime role to the new database user so that it can act as an ORDS runtime user.
```
BEGIN
     ORDS_ADMIN.PROVISION_RUNTIME_ROLE(
         p_user => 'ORDS_PUBLIC_USER2',
         p_proxy_enabled_schemas => TRUE);
END;
/
```
Following are the parameters:
- p_user: The name of the user to be configured.
- p_proxy_enabled_schemas: When set to true, proxy grants are added for any REST enabled schemas.
Note:
It is highly recommended not to skip the following steps. If you skip these steps, then ORDS will run APEX, OWA, PL/SQL gateway requests directly as the runtime user and warnings similar to the following will be logged for each request:
```
WARNING Running PL/SQL Gateway directly as
          ORDS_PUBLIC_USER is not advised in multi-user environments. Use proxied mode
          instead.
```
Create a new user for PL/SQL Gateway, OWA, and APEX and allow connections through the runtime user created in step 2:
```
CREATE USER "ORDS_PLSQL_GATEWAY2" IDENTIFIED BY <password>;
GRANT "CONNECT" TO "ORDS_PLSQL_GATEWAY2";
 
ALTER USER ORDS_PLSQL_GATEWAY2 GRANT CONNECT THROUGH ORDS_PUBLIC_USER2;
```
The new user name ORDS_PLSQL_GATEWAY2 is the recommended user name. If you choose a different user name, then specify that user name in all the steps.

Configure the new ORDS runtime user to use the new gateway user.

BEGIN
  ORDS_ADMIN.CONFIG_PLSQL_GATEWAY(
        p_runtime_user => 'ORDS_PUBLIC_USER2',         /* when using this user */
        p_plsql_gateway_user => 'ORDS_PLSQL_GATEWAY2'  /* run OWA things as this user */
  );
END;
/

Downloading and Configuring Oracle REST Data Services

To use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment , you must perform the following steps to install and configure ORDS:

Note:

Oracle REST Data Services 19.4.6 or higher is required for a customer managed environment with Autonomous Database.

Depending on where you install Oracle REST Data Services for your customer managed environment, do the following:

If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then use an Oracle YUM repository and perform a YUM install of ORDS.
If your customer managed environment for Oracle REST Data Services runs in some other environment, then download ORDS from the Oracle REST Data Services Download page.

Configure ords

ords --config <configuration_directory> config set db.username ORDS_PUBLIC_USER2

ords --config <configuration_directory> config secret db.password 
<provide the password for ORDS_PUBLIC_USER2 when prompted>

ords --config <configuration_directory> config set  db.wallet.zip.service <dbname_low>

ords --config <configuration_directory> config set  db.wallet.zip.path <path_to_wallet>

ords --config <configuration_directory> config set  plsql.gateway.mode proxied

Where:

<configuration_directory> is the directory in which you want to persist the ORDS configuration.
<dbname_low> is the alias of the TNS entry you want ORDS to use when connecting to the database.
<path_to_wallet> specifies the path to the wallet archive that was created in the preceding step.

Preparing and Starting ORDS

To use customer managed Oracle REST Data Services (ORDS) on Autonomous Database, on the system where ORDS runs, you need to perform additional configuration steps and then start ORDS.

For ORDS running with APEX, perform all the steps starting from Step 1. For ORDS running without APEX, perform the steps starting from Step 3.

In the location where ORDS is installed, install the APEX images.
```
unzip apex_19version.zip
```
Note:
To use your customer managed ORDS environment for APEX, you must download the APEX images of the APEX release that is currently deployed in your Oracle Autonomous Database. When Oracle announces the next APEX upgrade, you must pre-deploy the images from the upgraded APEX release or defer the APEX upgrade to avoid any service interruption. You can download the APEX images from the Oracle APEX downloads page.
See Also:

Edit the standalone properties to add or edit the static images property:

ords --config <configuration_directory> config set standalone.static.path <path_to_apex_images>

Create a wallet_cache folder, so that ORDS stores the Autonomous Database wallet on this folder and uses it while connecting to JDBC. For example:
```
mkdir wallet_cache
```
Start ORDS.
- If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then start the ORDS service as follows:
```
/opt/oracle/ords start
```
- If your customer managed environment for Oracle REST Data Services runs in the directory where ORDS is installed, then start the ORDS service as follows:
```
ords serve
```