This section describes how to install and deploy Oracle REST Data Services. (REST stands for Representational State Transfer.)
Note:
Oracle REST Data Services was called Oracle Application Express Listener before Release 2.0.6.
Topics:
Oracle REST Data Services is a Java EE-based alternative for Oracle HTTP Server and mod_plsql
. The Java EE implementation offers increased functionality including a command line based configuration, enhanced security, file caching, and RESTful web services. Oracle REST Data Services also provides increased flexibility by supporting deployments using Oracle WebLogic Server, GlassFish Server, Apache Tomcat, and a standalone mode.
The Oracle Application Express architecture requires some form of web server to proxy requests between a web browser and the Oracle Application Express engine. Oracle REST Data Services satisfies this need but its use goes beyond that of Oracle Application Express configurations. Oracle REST Data Services simplifies the deployment process because there is no Oracle home required, as connectivity is provided using an embedded JDBC driver.
This section offers an overview of Oracle REST Data Services and provides information about supported Java Platform, Enterprise Edition (Java EE) application servers and system requirements.
Topics:
Oracle REST Data Services system requirements are as follows:
Oracle Database (Enterprise Edition, Standard Edition or Standard Edition One) release 11.1 or later, or Oracle Database 11g Release 2 Express Edition.
Java JDK 8 or later.
Web browser requirements:
Microsoft Internet Explorer 8.0 or later.
Mozilla Firefox 3.0 or later.
Google Chrome 2.0 or later.
Note:
Oracle Application Express is not a prerequisite for using Oracle REST Data Services.
If Oracle Application Express is installed and if RESTful services have been configured during the installation (see the step "Configure RESTful Services" in Oracle Application Express Installation Guide), then Oracle REST Data Services supports it, including executing the RESTful services defined in Oracle Application Express.
Before you deploy Oracle REST Data Services, you must install and configure it using a command-line interface.
Topics:
Note:
You must have the SYS AS SYSDBA account for installing, upgrading, validating or uninstalling Oracle REST Data Services.Downloading, Configuring and Installing Oracle REST Data Services
Using SQL Developer Oracle REST Data Services Administration (Optional)
See Also:
If you plan to use Oracle REST Data Services with a NoSQL Database store, refer to NoSQL Store Installation and Registration for more information.
To use the Oracle REST API for JSON Data Persistence, you must also install the Oracle REST API. See "Oracle REST API Installation" in Oracle REST Data Services SODA for REST Developer's Guide.
Oracle REST Data Services provides several command line commands. For example, you can configure the location where Oracle REST Data Services stores configuration files, configure the database Oracle REST Data Services uses, and start Oracle REST Data Services in standalone mode.
To display a full list of available commands, go to the directory or folder containing the ords.war
file and execute the following command:
java -jar ords.war help
A list of the available commands is displayed. To see instructions on how to use each of these commands, enter help followed by the command name, for example:
java -jar ords.war help configdir
Oracle REST Data Services uses the following database users:
User Name | Required | Description |
---|---|---|
|
Only if using Oracle REST Data Services with Oracle Application Express |
If you use Oracle REST Data Services with Oracle Application Express, this is the database user used when invoking PL/SQL Gateway operations, for example, all Oracle Application Express operations. For information on unlocking the APEX_PUBLIC_USER, see "Configure APEX_PUBLIC_USER Account" in Oracle Application Express Installation Guide. |
|
Only if using RESTful Services defined in Application Express of version 5.0 or above. |
The database user used when invoking Oracle Application Express RESTful Services if RESTful Services defined in Application Express workspaces are being accessed |
|
Only if using RESTful Services defined in Application Express of version 5.0 or above. |
The database user used to query RESTful Services definitions stored in Oracle Application Express if RESTful Services defined in Application Express workspaces are being accessed |
|
Yes |
Owner of the PL/SQL packages used for implementing many Oracle REST Data Services capabilities. ORDS_METADATA is where the metadata about Oracle REST Data Services-enabled schemas is stored. It is not accessed directly by Oracle REST Data Services; the Oracle REST Data Services application never creates a connection to the ORDS_METADATA schema. The schema password is set to a random string, connect privilege is revoked, and the password is expired. |
|
Yes |
User for invoking RESTful Services in the Oracle REST Data Services-enabled schemas. |
The APEX_<xxx>
users are created during the Oracle Application Express installation process.
As part of the Oracle REST Data Services installation, privileges are granted to several users:
PUBLIC
is granted SELECT
on many ORDS_METADATA
tables and views.
PUBLIC
is granted EXECUTE
on PL/SQL packages that are available for users to invoke.
ORDS_METADATA
is granted EXECUTE
on the following:
SYS.DBMS_ASSERT
SYS.DBMS_CRYPTO
SYS.DBMS_LOB
SYS.DBMS_OUTPUT
SYS.DBMS_REGISTRY
SYS.DBMS_SESSION
SYS.DBMS_UTILITY
SYS.VALIDATE_ORDS
SYS.HTF
SYS.HTP
SYS.OWA
SYS.WPG_DOCLOAD
ORDS_METADATA
is granted SELECT
on the following:
SYS.DBA_DIRECTORIES
SYS.DBA_OBJECTS
ORDS_METADATA
is granted the following system privileges:
ALTER USER
CREATE TRIGGER
ORDS_METADATA
is granted the necessary object privileges to migrate Application Express REST data to ORDS_METADATA
tables.
The procedures in this topic apply to installing Oracle REST Data Services in a traditional (non-CDB) database.
Note:
You must complete the configuration steps in this topic before deploying to an application server.
To install and configure Oracle REST Data Services:
Download the file ords.
version.number
.zip
from the Oracle REST Data Services download page.
Note that the version.number
in the file name reflects the current release number.
Unzip the downloaded zip file into a directory (or folder) of your choice:
UNIX and Linux: unzip ords.
version.number
.zip
Windows: Double-click the file ords.
version.number
.zip
in Windows Explorer
Choose one of the following installation options:
Advanced Installation Using Command-Line Prompts
Silent Installation Using a Parameter File
You can reinstall or uninstall Oracle REST Data Services if required.
Related Topics
You can perform an advanced installation in which you are prompted for the necessary parameter values, after which your choices are stored in the params/ords_params.properties
file under the location where you installed Oracle REST Data Services.
To perform an advanced installation, enter the following command:
java -jar ords.war install advanced
During installation, Oracle REST Data Services checks if configuration files already exist in your specified configuration folder:
If configuration files do not exist in that folder, they are created (examples: defaults.xm
l, apex_pu.xml
).
If configuration files from an earlier release exist in that folder, Oracle REST Data Services checks if <name>_pu.xml
is present; and if it is not, you are prompted for the password for the ORDS_PUBLIC_USER account. If the configuration files <name>_al.xml
and <name>_rt.xml
from Release 2.0.n exist, they are preserved. (However, in Releases 2.0.n RESTful Services was optional, and therefore the files might not exist in the configuration folder.)
If multiple configuration files exist from a previous release (examples: apex.xml
, apex_al.xml
, apex_rt.xml
, sales.xml
, sales_al.xml
, sales_rt.xml
, …), and if <name>_pu.xml
does not exist, then you are prompted to select the database configuration so that the Oracle REST Data Services schema can be created in that database.
The following shows an example advanced installation. In this example, if you accepted the default value of 1 for Enter 1 if you wish to start in standalone mode or 2 to exit [1]
, the remaining prompts are displayed; and if you will be using Oracle Application Express, you must specify the APEX static resources location
.
d:\ords>java -jar ords.war install advanced This Oracle REST Data Services instance has not yet been configured. Please complete the following prompts Enter the location to store configuration data:/path/to/config Enter the name of the database server [localhost]: Enter the database listen port [1521]: Enter 1 to specify the database service name, or 2 to specify the database SID [1]: Enter the database service name:orcl Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]: Enter the database password for ORDS_PUBLIC_USER: Confirm password: Requires SYS AS SYSDBA to verify Oracle REST Data Services schema. Enter the database password for SYS AS SYSDBA: Confirm password: Enter the default tablespace for ORDS_METADATA [SYSAUX]: Enter the temporary tablespace for ORDS_METADATA [TEMP]: Enter the default tablespace for ORDS_PUBLIC_USER [USERS]: Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]: Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step. If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]: Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]: Enter the database password for APEX_PUBLIC_USER: Confirm password: Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]: Enter the database password for APEX_LISTENER: Confirm password: Enter the database password for APEX_REST_PUBLIC_USER: Confirm password: Enter 1 if you wish to start in standalone mode or 2 to exit [1]: Enter the APEX static resources location:/path/to/apex/images Enter 1 if using HTTP or 2 if using HTTPS [1]: Enter the HTTP port [8080]: OR Enter 1 if using HTTP or 2 if using HTTPS [1]:2 Enter the HTTPS port [8443]: Enter the SSL hostname:mysslhost Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certificate [1]:
This section describes the options you can choose while performing advanced installation of Oracle REST Data Services schema.
Table 1-1 Advanced Installation Prompts for Installing in Standalone Mode
Options | Description |
---|---|
This Oracle REST Data Services instance has not yet been configured. Please complete the following prompts Enter the location to store configuration data:/path/to/config |
Specify the location for the ORDS configuration files. If the location does not exist, then it will be created. |
Enter the name of the database server [localhost]: |
Specify the Oracle database hostname. |
Enter the database listen port [1521]: |
Specify the Oracle database port. |
Enter 1 to specify the database service name, or 2 to specify the database SID [1]: Enter the database service name:orcl |
Specify the Oracle database service name, if you choose option 1. Otherwise, if you choose option 2 then, specify the Oracle database SID. |
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]: Enter the database password for ORDS_PUBLIC_USER: Confirm password: |
Specify 1 to install the Oracle REST Data Services schema and create the Oracle REST Data Services proxy user, Specify the proxy user, |
Requires SYS AS SYSDBA to verify Oracle REST Data Services schema. Enter the database password for SYS AS SYSDBA: Confirm password: |
Specify the Note: To install the Oracle REST Data Services schema, |
Enter the default tablespace for ORDS_METADATA [SYSAUX]: Enter the temporary tablespace for ORDS_METADATA [TEMP]: |
Specify the default tablespace and temporary tablespace for the Oracle REST Data Services schema, |
Enter the default tablespace for ORDS_PUBLIC_USER [USERS]: Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP] |
Specify the default tablespace and temporary tablespace for the Oracle REST Data Services proxy user, |
Table 1-2 Options for Configuring Application Express or Migrating from mod_plsql
Options | Description |
---|---|
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step. If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]: Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]: Confirm password: Enter the database password for APEX_PUBLIC_USER: |
You can perform one of the following:
|
Enter 1 to specify passwords for Application Express RESTful Services database user (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]: Enter the database password for APEX_LISTENER: Confirm password: Enter the database password for APEX_REST_PUBLIC_USER: Confirm password: |
If you have specified APEX_PUBLIC_USER for the PL/SQL Gateway user, then you have the option of using Application Express RESTful Services. Specify 2 if you do not want to use Application Express RESTful Services and skip this step. For Application Express 5.0 and above, option 1 is required. The database users are created using the script |
Table 1-3 Options for Running in Standalone Mode
Options | Description |
---|---|
Enter 1 if you wish to start in standalone mode or 2 to exit [1]: |
Specify 1 to start in standalone mode using the Jetty web server that is bundled with ORDS. |
Enter the APEX static resources location:/path/to/apex/images |
Specify the location of the Application Express images. This prompt will appear if you have specified |
Enter 1 if using HTTP or 2 if using HTTPS [1]: Enter the HTTP port [8080]: |
Specify the HTTP port if you choose 1. |
OR Enter 1 if using HTTP or 2 if using HTTPS [1]:2 Enter the HTTPS port [8443]: Enter the SSL hostname:mysslhost Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certifi cate [1]: |
Specify the HTTPS port and the Secure Socket Layer (SSL) hostname if you choose 2. You have the option of using the self-signed certificate which generates the self-signed certificate automatically. |
OR Enter 1 to use the self-signed certificate or 2 if you will provide the SSL certifi cate [1]:2 Enter the path for the SSL Certificate:/path/to/sslcert Enter the path for the SSL Certificates private key:/path/to/sslcertprivatekey |
Specify the path for the SSL certificate and the path for SSL certificate private key if you choose 2. |
Oracle REST Data Services can be installed in silent mode without any user interaction.
You can perform a silent installation of Oracle REST Data Services using the parameters specified in the <path-to-params-file>/ords_params.properties
file under the location where you installed Oracle REST Data Services. This is the default Oracle REST Data Services parameter file. You can edit that file to change the default values to reflect your environment and preferences. If a required parameter is missing in the file or do not contain a value, you will be prompted for that parameter. The Oracle REST Data Services parameter file consists of key or value pairs in the format key=value
.
--parameterFile
option. If the --parameterFile
option is not specified, the default Oracle REST Data Services parameter file is used.
Note:
If the default Oracle REST Data Services parameter file does not exist and the–parameterFile
option is not specified, then you will be prompted for the installation options.Example commands for installing Oracle REST Data Services in silent mode:
java -jar ords.war java -jar ords.war --parameterFile /path/to/params/myown_params.properties
java -jar ords.war install simple java -jar ords.war install simple --parameterFile /path/to/params/myown_params.properties
Note:
Refer to on-line help command to check for additional options available for the install command: java –jar ords.war help install
This section lists the parameters required for performing installation in silent mode.
This section lists the database connection parameters that must be specified in the properties file.
db.hostname
and db.port
database connection parameters. In addition, specify either db.servicename
or db.sid
parameters. If you are specifying a database connection to an Oracle 12.x PDB, then provide the db.servicename
parameter.
Note:
If bothdb.servicename
and db.sid
are present in the parameter file, then db.servicename
will be used.Table 1-4 Parameters for Database Connection
Key | Type | Description | Example |
---|---|---|---|
db.hostname |
string | Specifies the host system for the Oracle database. | myhostname |
db.port |
numeric | Specifies the database listener port. | 1521 |
db.servicename |
string | Specifies the network service name of the database. | orcl.example.com |
db.sid |
string | Specifies the name of the database. | orcl |
This section lists the parameters required for installing Oracle REST Data Services schema.
SYS username and password
ORDS_PUBLIC_USER password
Existing default and temporary tablespaces for the ORDS_METADATA schema and ORDS_PUBLIC_USER.
Note:
If all of the default and temporary tablespace parameters are omitted in the Oracle REST Data Services parameter file, then the Oracle database default and temporary tablespaces are used.
Table 1-5 Parameters for Installing Oracle REST Data Services
Key | Type | Description | Example |
---|---|---|---|
rest.services.ords.add |
boolean |
Specifies whether to install the Oracle REST Data Services schema. Set the value to true. Supported values:
|
true |
user.public.password |
string |
Specifies the password for ORDS_PUBLIC_USER. |
password |
schema.tablespace.default |
string |
Specifies the ORDS_METADATA default tablespace. Specify an existing default tablespace. |
SYSAUX |
schema.tablespace.temp |
string |
Specifies the ORDS_METADATA temporary tablespace. Specify an existing temporary tablespace. |
TEMP |
user.tablespace.default |
string |
Specifies the ORDS_PUBLIC_USER default tablespace. Specify an existing default tablespace. |
SYSAUX |
user.tablespace.temp |
string |
Specifies the ORDS_PUBLIC_USER temporary tablespace. Specify an existing temporary tablespace. |
TEMP |
bequeath.connect |
boolean |
Specifies whether to connect as bequeath. Supported values:
|
true |
This section lists the parameters for using Application Express.
Table 1-6 Parameters for Installing Application Express
Key | Type | Description | Example |
plsql.gateway.add |
boolean |
Specifies whether to configure Oracle REST Data Services for Application Express. Set this value to true. Supported values:
|
true |
db.username |
string |
Specifies the PL/SQL gateway username. For Application Express, you must specify APEX_PUBLIC_USER. |
APEX_PUBLIC_USER |
db.password |
string |
Specifies the password for APEX_PUBLIC_USER. The password must match APEX_PUBLIC_USER database password. |
password |
rest.services.apex.add |
boolean |
Specifies whether to configure Oracle REST Data Services for Application Express RESTful Services. Supported values:
Set this value to true if you want to use APEX RESTful Services. |
true |
user.apex.listener.password |
string |
Specifies the password for APEX_LISTENER. If |
password |
user.apex.restpublic.password |
string |
Specifies the password for APEX_REST_PUBLIC_USER. If |
password |
Example 1-1 Parameters to configure for Application Express and APEX RESTful Services and run in standalone mode
Following example shows parameters to install Oracle REST Data Services, configure for Application Express and APEX RESTful Services and run in standalone mode using http:
Note:
Passwords in the parameter file will be encrypted during installation. The encrypted passwords are stored in the parameter file. For example,user.public.password=@0585904F6C9B442532D5212962835D00C8
.
db.hostname=localhost db.password=password db.port=1521 db.servicename=orcl.example.com db.username=APEX_PUBLIC_USER plsql.gateway.add=true rest.services.apex.add=true rest.services.ords.add=true schema.tablespace.default=SYSAUX schema.tablespace.temp=TEMP standalone.http.port=8080 standalone.mode=true standalone.static.images=/path/to/images standalone.use.https=false user.apex.listener.password=password user.apex.restpublic.password=password user.public.password=password user.tablespace.default=SYSAUX user.tablespace.temp=TEMP
See Also:
For information on APEX_PUBLIC_USER, refer to section, Configure APEX_PUBLIC_USER Account in Oracle Application Express Installation Guide.
For information on APEX_LISTENER and APEX_REST_PUBLIC_USER, refer to section, Configuring RESTful Services with Oracle REST Data Services in Oracle Application Express Installation Guide.
This section lists parameters for running Oracle REST Data Services in standalone mode.
Table 1-7 Parameters for Installing Oracle REST Data Services in Standalone Mode
Key | Type | Description | Example |
---|---|---|---|
standalone.mode |
boolean |
Indicates whether to use the web application server (Jetty) that is included with Oracle REST Data Services. Supported values:
|
true |
standalone.http.port |
numeric |
Specifies the HTTP listener port. |
8080 |
standalone.use.https |
boolean |
Specifies whether to use https. |
true |
standalone.https.port |
numeric |
Specifies HTTPS listener port. |
8443 |
standalone.ssl.host |
string |
Specifies the Secure Socket Layer (SSL) certificate hostname. You must specify this option if you are using https. |
mysecurehost |
standalone.use.ssl.cert |
boolean |
Specifies whether you will provide the SSL certificate. If this value is set to true, you must specify the |
true |
standalone.ssl.cert.path |
string |
Specifies the SSL certificate path. If you are providing the SSL certificate, you must specify the certificate location. |
/path/to/ssl/cert |
standalone.ssl.key.path |
string |
Specifies the SSL certificate key path. If you are providing the SSL certificate, you must specify the certificate key location. |
/path/to/ssl/key |
standalone.static.images |
string |
Specifies the location of Application Express images. If you are using Application Express, specify the location of Application Express images. |
/path/to/apex/images |
Note:
On Microsoft Windows systems, if you specify an Application Express static images location forstandalone.static.images
, use the backslash character (/) before the colon, and use a forwardslash for the folder separator. For example, standalone.static.images=d\:/test/apex426/apex/images/
Example 1-2 Parameters to run in standalone mode using http
db.hostname=localhost db.port=1521 db.servicename=orcl.example.com plsql.gateway.add=false rest.services.apex.add=false rest.services.ords.add=true schema.tablespace.default=SYSAUX schema.tablespace.temp=TEMP standalone.http.port=8080 standalone.mode=true standalone.use.https=false user.public.password=password user.tablespace.default=SYSAUX user.tablespace.temp=TEMP
Example 1-3 Parameters to run in standalone mode using https and providing the ssl certificate paths
db.hostname=localhost db.port=1521 db.servicename=orcl.example.com plsql.gateway.add=false rest.services.apex.add=false rest.services.ords.add=true schema.tablespace.default=SYSAUX schema.tablespace.temp=TEMP standalone.https.port=8443 standalone.mode=true standalone.ssl.cert.path=/path/to/ssl/cert standalone.ssl.host=mysecurehost standalone.ssl.key.path=/path/to/ssl/key standalone.use.https=true standalone.use.ssl.cert=true user.public.password=password user.tablespace.default=SYSAUX user.tablespace.temp=TEMP
Related Topics
This section lists some miscellaneous parameters.
Table 1-8 Miscellaneous Parameters
Key | Type | Description | Example |
---|---|---|---|
migrate.apex.rest |
boolean |
Specifies whether to migrate APEX RESTful Services definitions to Oracle REST Data Services schema. Supported values:
|
true |
If you want to check that the Oracle REST Data Services installation is valid, go to the directory or folder containing the ords.war
file and enter the validate
command in the following format:
java -jar ords.war validate [--database <dbname>]
Note:
When you install Oracle REST Data Services, it attempts to find the Oracle Application Express (APEX) schema and creates a view. This view joins the relevant tables in the APEX schema to the tables in the Oracle REST Data Services schema. If you install Oracle REST Data Services before APEX, then Oracle REST Data Services cannot find the APEX schema and it creates a stub view in place of the missing APEX tables.
Oracle highly recommends that you install Oracle REST Data Services after APEX to ensure that the APEX objects, which Oracle REST Data Services needs to query, are present. If you install Oracle REST Data Services before APEX, then use the validate
command to force Oracle REST Data Services to reconstruct the queries against the APEX schema.
If --database
is specified, <dbname>
is the pool name that is stored in the Oracle REST Data Services configuration files.
You are prompted for any necessary information that cannot be obtained from the configuration of pool name, such as host, port, SID or service name, and the name and password of a user with SYSDBA privilege (such as SYS AS SYSDBA).
Note:
If the validate command is run against a CDB, then it will validate the CDB and all of its PDBs.
If you want to reinstall Oracle REST Data Services, you must first uninstall the existing Oracle REST Data Services; and before you uninstall, ensure that Oracle REST Data Services is stopped.
Uninstalling Oracle REST Data Services removes the ORDS_METADATA schema, the ORDS_PUBLIC_USER user, and Oracle REST Data Services-related database objects (including public synonyms) if they exist in the database. To uninstall (remove, or deinstall) Oracle REST Data Services, go to the directory or folder containing the ords.war
file and enter the uninstall
command as follows:
java -jar ords.war uninstall
The uninstall
command prompts you for some necessary information (host, port, SID or service name, username, password).
See Also:
To uninstall Oracle REST Data Services from a CDB, see Using the Multitenant Architecture with Oracle REST Data Services.
This section describes how to use Oracle SQL Developer to administer Oracle REST Data Services.
See Also:
"Oracle REST Data Services Administration" in Oracle SQL Developer User's Guide
Topics:
Oracle SQL Developer enables you to administer Oracle REST Data Services using a graphical user interface. To take full advantage of these administration capabilities, you must use SQL Developer Release 4.1 or later. Using SQL Developer for Oracle REST Data Services administration is optional.
Using this graphical user interface, you can update the database connections, JDBC settings, URL mappings, RESTful connections, security (allowed procedures, blocked procedures, validation function and virus scanning), Caching, Pre/Post Processing Procedures, Environment, and Excel Settings. Oracle SQL Developer also provides statistical reporting, error reporting, and logging.
See Also:
"Oracle REST Data Services Administration" in Oracle SQL Developer User's Guide
If you want to be able to administer Oracle REST Data Services using SQL Developer, then you must configure an administrator user as follows:
Execute the following command:
java -jar ords.war user adminlistener "Listener Administrator"
Enter a password for the adminlistener
user.
Confirm the password for the adminlistener
user.
If you are using Oracle REST Data Services without HTTPS, follow the steps listed under the section,Using OAuth2 in Non-HTTPS Environments.
When using SQL Developer to retrieve and/or upload an Oracle REST Data Services configuration, when prompted, enter the credentials provided in the preceding list.
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.
Edit the file named defaults.xml
.
Add the following setting to the end of this file just before the </properties>
tag.
<entry key="security.verifySSL">false</entry>
Save the file.
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.
Although Oracle REST Data Services supports the Java EE application servers, you also have the option of running in standalone mode. This section describes how to run Oracle REST Data Services in standalone mode.
Standalone mode is suitable for development use and is supported in production deployments. Standalone mode, however, has minimal management capabilities when compared to most Java EE application servers and may not have adequate management capabilities for production use in some environments.
Topics:
Related Topics
To launch Oracle REST Data Services in standalone mode:
Usually, you would have created a private key and a Certificate Signing Request before obtaining your signed certificate. The private key needs to be converted into DER in order for Oracle REST Data Services to read it properly.
For example, assume that the original private key was created using the OpenSSL tool with a command similar to either of the following:
openssl req -new -newkey rsa:2048 -nodes -keyout yourdomain.key -out yourdomain.csr
or
openssl genrsa -out private.em 2048
In this case, you must run a command similar to the following to convert it and remove the encryption: openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt
openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt
After doing this, you can include the path to yourdomain.der
when prompted by Oracle REST Data Services, or you can modify the following entries in conf/ords/standalone/standalone.properties
:
ssl.cert=<path to yourdomain.crt> ssl.cert.key=<path to yourdomain.der> ssl.host=yourdomain
Also, ensure that jetty.secure.port
is set.
To stop the Oracle REST Data Services server in standalone mode, at a command prompt press Ctrl+C.
You can configure a doc root for standalone mode to deploy static resources that are outside the /i
folder that is reserved for Application Express static resources.
To do so, specify the --doc-root
parameter with the standalone mode command, as in the following example:
java -jar ords.war standalone --doc-root /var/www/html
The preceding example makes any resource located within /var/www/html
available under http://
server:port
/
. For example, if the file /var/www/html/hello.txt
exists, it will be accessible at http://
server:port
/hello.txt
.
The value specified for --doc-roo
t is stored in ${config.dir}/ords/standalone/standalone.properties
in the standalone.doc.root
property. If a custom doc root is not specified using --doc-root
, then the default doc-root
value of ${config.dir}/ords/standalone/doc_root
is used. Any file placed within this folder will be available at the root context.
This approach has the following features and considerations:
HTML resources can be addressed without their file extension. For example, if a file named hello.html
exists in the doc root, it can be accessed at the URI http://
server:port
/hello
.
Attempts to address a HTML resource with its file extension are redirected to the location without an extension. For example, if the URI http://
server:port
/hello.html
is accessed, then the client is redirected to http://
server:port
/hello
.
The usual practice is to serve HTML resources without their file extensions, so this feature facilitates that practice, while the redirect handles the case where the resource is addressed with its file extension.
Index pages for folders are supported. If a folder contains a file named index.html
or index.htm
, then that file is used as the index page for the folder. For example, if /var/www/html
contains /abc/xyz/index.html
, then accessing http://
server:port
/abc/xyz/
displays the contents of index.html
.
Addressing a folder without a trailing slash causes a redirect to the URI with a trailing slash. For example, if a client accesses http://
server:port
/abc/xyz
, then the server issues a redirect to http://
server:port
/abc/xyz/
.
Resources are generated with weak etags based on the modification stamp of the file and with a Cache Control header that causes the resources to be cached for 1 hour.
This section describes how to deploy Oracle REST Data Services on Oracle WebLogic Server. It assumes that you have completed the installation process and are familiar with Oracle WebLogic Server. If you are unfamiliar with domains, managed servers, deployment, security, users and roles, refer to your Oracle WebLogic Server documentation.
Topics:
You can download Oracle WebLogic Server from Oracle Technology Network.
To learn more about installing Oracle WebLogic Server, see Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server and Oracle Fusion Middleware Installation Guide for Oracle WebLogic Server.
You must complete this step before deploying Oracle REST Data Services on WebLogic.
Related Topics
If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.
Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static command to create a web archive file named i.war
:
java -jar ords.war static <apex directory>\images
Where:
<apex directory>
is the directory location of Oracle Application Express.
This command runs the static
command contained in the ords.war
file. It packages the Application Express static images into an archive file named i.war
.
The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.
Tip:
Use java -jar ords.war help static
to see the full range of options for the static
command.
Use the i.war
file to deploy to WebLogic in the following steps:
Launching the Administration Server Console
Installing the Oracle WebLogic Server Deployment
Configuring WebLogic to Handle HTTP Basic Challenges Correctly
Tip:
The Oracle REST Data Services files, ords.war
and i.war
, must be available before you start this task.
To install the deployment:
Go to the WebLogic Server Home Page. Below Domain Configuration, select Deployments.
The Summary of Deployments is displayed.
Click Install.
Specify the location of the ords.war
file and click Next.
The ords.war
file is located in the folder where you unzipped the Oracle REST Data Services ZIP file.
Tip:
WebLogic Server determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war
to apex.war
before the deployment.
The Install Application assistant is displayed.
Select Install this deployment as an application and click Next.
Select the servers and/or clusters to which you want to deploy the application or module and click Next.
Tip:
If you have not created additional Managed Servers or clusters, you do not see this assistant page.
In the Optional Settings, specify the following:
Name - Enter:
ords
Security - Select the following:
Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor
Source accessibility - Select:
Use the defaults defined by the deployment's targets
Click Next.
A summary page is displayed.
Under Additional configuration, select one of the following:
Yes, take me to the deployment's configuration - Displays the Configuration page.
No I will review the configuration later - Returns you to the Summary of Deployments page.
Review the summary of configuration settings that you have specified.
Click Finish.
Repeat the previous steps to deploy the i.war
file.
In the optional settings, specify the following:
Name - Enter:
i
Security - Select:
Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor
Source Accessibility - Select:
Use the defaults defined by the deployment's targets
If your domain is in Production Mode, then on the Change Center click Activate Changes.
By default WebLogic Server attempts to intercept all HTTP Basic Authentication challenges. This default behavior needs to be disabled for Oracle REST Data Services to function correctly. This is achieved by updating the enforce-valid-basic-auth-credentials
flag. The WebLogic Server Administration Console does not display the enforce-valid-basic-auth-credentials
setting. You can use WebLogic Scripting Tool (WLST) commands to check, and edit the value in a running server.
The following WLST commands display the domain settings:
connect('weblogic','weblogic','t3://localhost:7001') cd('SecurityConfiguration') cd('mydomain') ls()
If the domain settings displayed, contains the following entry:
-r-- EnforceValidBasicAuthCredentials true
Then you must set this entry to false
.
To set the entry to false
, use the WLST commands as follows:
connect('weblogic', 'weblogic', 't3://localhost:7001') edit() startEdit() cd('SecurityConfiguration') cd('mydomain') set('EnforceValidBasicAuthCredentials','false') save() activate() disconnect() exit()
Note:
WebLogic Server must be restarted for the new settings to take effect.weblogic
is the WebLogic user having administrative privileges
weblogic
is the password
mydomain
is the domain
The AdminServer is running on the localhost
and on port 7001
Related Topics
In the Summary of Deployments, select the Control tab and verify that both the ords
and i
State are Active and the Health status is OK.
If ords
and/or i
are not Active, then enable them. In the Deployments table, select the check box next to ords
and/or i
. Click Start and select Servicing all requests to make them active.
This section describes how to deploy Oracle REST Data Services on GlassFish Server.
Topics:
Note:
GlassFish Server support will be desupported in a future release. Oracle recommends that you use the following alternatives instead:Oracle WebLogic Server
Oracle REST Data Services standalone mode
Apache Tomcat
Tip:
This section assumes that you have completed the installation process and are familiar with GlassFish Server. If you are unfamiliar with domains, servers, applications, security, users and roles, see your GlassFish Server documentation.
You can install Oracle REST Data Services with GlassFish Server. GlassFish Server is available for download from the Oracle Technology Network.
You must complete this step before deploying Oracle REST Data Services on GlassFish.
If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.
Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static
command to create a web archive file named i.war
:
java -jar ords.war static <apex directory>\images
Where:
<apex directory>
is the directory location of Oracle Application Express.
The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.
Tip:
Use java -jar ords.war help static
to see the full range of options for the static
command.
Use the i.war
file to deploy to GlassFish in the following steps:
Launching the Administration Server Console
Installing the GlassFish Server Deployment
At least one GlassFish server domain must be started before you start the Administration Console.
To launch the Administration Console:
Tip:
The Oracle REST Data Services files, ords.war
and i.war
must be available before you start this task.
To install the deployment:
On the navigation tree, click the Application node.
The Applications page is displayed.
Click the Deploy button.
The Deploy Applications or Modules page is displayed.
Select Packaged File to be Uploaded to the Server and click Browse.
Navigate to the location of the ords.war
file, select the file, and click Open.
The Deploy Applications or Modules page is displayed.
On the Deploy Applications or Modules page, specify the following:
Type: Web Application
Context Root: ords
Tip:
The Context Root value defaults to ords. However you can change it to apex if you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/....
Application Name: ords
Status: Enabled
Description: Oracle REST Data Services
Accept all other default settings and click OK.
Repeat the previous steps to deploy the i.war
file. Clear the Context Root field so that the context root set in the sun-web.xml
is used.
The Applications page is displayed. A check mark should appear in the Enabled field for ords
Tip:
If a check mark does not appear in the Enabled column for ords, then select the check box next to ords and click Enable.
This section describes how to deploy Oracle REST Data Services on Apache Tomcat.
Topics:
Tip:
This section assumes that you have completed the installation process and are familiar with Apache Tomcat. If you are unfamiliar with domains, servers, applications, security, users and roles, see your Apache Tomcat documentation.
You can download Apache Tomcat from:
You must complete this step before deploying Oracle REST Data Services on Apache Tomcat.
Related Topics
If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.
To configure Oracle Application Express Images on Apache Tomcat:
Copy the contents of the <apex directory>
/images
folder to <Tomcat directory>
/webapps/i/
.
Where:
<apex directory>
is the directory location of the Oracle Application Express distribution.
<Tomcat directory>
is the folder where Apache Tomcat is installed.
If you want to upgrade to a new release of Oracle REST Data Services, you must do the following:
Stop the Oracle REST Data Services instance.
If you are running Oracle REST Data Services on your application server (such as Oracle WebLogic Server, GlassFish Server, or Apache Tomcat), stop Oracle REST Data Services.
If you are running Oracle REST Data Services in standalone mode, refer to section, Stopping the Server in Standalone Mode.
Go to the folder where you unzipped the new Oracle REST Data Services release distribution.
Enter the following on the command line:
java -jar ords.war install advanced
or
java -jar ords.war
When prompted for the configuration folder, use the configuration folder where the Oracle REST Data Services configuration files are stored. (The configuration location will be stored in the ords.war
file.)
If you specified an existing Oracle REST Data Services configuration folder that contains the configuration files, Oracle REST Data Services will attempt to connect to each database defined in the configuration folder and check the installed version.
If you specified an Oracle REST Data Services configuration folder that does not exist, you will be prompted for the database connection information, the ORDS_PUBLIC_USER credentials, and additional configuration information. Oracle REST Data Services will attempt to connect to this database and check the installed version.
When Oracle REST Data Services checks the installed version, it does the following, depending on whether an earlier 3.0.n version is already installed in the database.
If the installed version is an earlier 3.0.n version of Oracle REST Data Services, you are prompted for the SYS credentials to enable Oracle REST Data Services to apply the in-place upgrade. The in-place upgrade will modify the existing installation to add the updated schema objects and packages. The existing metadata stored in the Oracle REST Data Services schema will remain intact.
If Oracle REST Data Services is not already installed in the database (or if you are upgrading from Release 2.0.n), you are prompted for the SYS credentials to enable Oracle REST Data Services to perform the installation, and you will also be prompted for the default and temporary tablespaces for the ORDS_METADATA schema and ORDS_PUBLIC_USER.
When the upgrade or installation completes, you can re-deploy the ords.war
file to your application server or start Oracle REST Data Services in standalone mode.
You can use the bequeath connection to install, upgrade, validate, or uninstall Oracle REST Data Services. The installer will not prompt you for the SYS username and password for the operation
In the parameter file, add the property: bequeath.connect=true
Using a bequeath connection for installing, validating, or uninstalling Oracle REST Data Services is supported on Linux and Windows systems for Oracle Database Release 12, but only on Linux systems for Oracle Database Release 11.
The command used must be run by an operating system user that is a member of the DBA group. Example of installing Oracle REST Data Services:
java -jar ords.war
Bequeath Connection Using Linux
On a Linux system, you must set the following environment variables to use the bequeath connection:
ORACLE_HOME
ORACLE_SID
LD_LIBRARY_PATH (to point to ORACLE_HOME/lib
)
For Oracle Database Release 11 (but not for Release 12), you must specify the option -DuseOracleHome=true
. Examples of installing Oracle REST Data Services on a Linux system:
For Oracle Database Release 11: java -DuseOracleHome=true -jar ords.war
For Oracle Database Release 12: java -jar ords.war
Related Topics