Release Notes
Date: April 2019
Log Oracle REST Data Services bugs and issues using My Oracle Support.
This release sees the introduction of the Database Management REST API. Please consult the ORDS documentation library for instructions on how to enable this feature, which is disabled by default.
The installer has been enhanced to enable installation of ORDS to a pluggable database, or a non container database without requiring use of the SYS user or a user with the SYSDBA role. Note that installation to a CDB still requires use of the SYS as SYSDBA user. Also note that installation as a non SYS user requires the user to have a number of database privilege grants, please consult the ORDS documentation library for information on how to provision a database user to be able to install ORDS.
DBMS_SCHEDULER job CLEAN_OLD_ORDS_SESSIONS has been replaced by ORDS_HOUSEKEEPING_JOB which will perform the same action of deleting expired sessions that are older than one day.
During upgrade to this ORDS release, the CLEAN_OLD_ORDS_SESSIONS job will be replaced by ORDS_HOUSEKEEPING_JOB, if the old job already exists, otherwise the new job will be created when the first schema is enabled via calls to ORDS.ENABLE_SCHEMA or ORDS_ADMIN.ENABLE_SCHEMA PL/SQL methods.
Support for generating PDF responses for PL/SQL Gateway calls will be removed in ORDS 19.2.0. This will impact the features in Oracle Application Express relating to generating PDF documents. Future versions of Oracle Application Express will move to a new mechanism to generate PDF resources.
Support for defining ORDS based REST Services using the original URI Template syntax (as used in APEX based REST Services) will be removed in ORDS 19.4.0. Customers are strongly encouraged to modify Resource Module definitions to use the more robust and expressive Route Patterns Syntax.
Support for defining URL mappings using the java -jar ords.war map-url --type regex is deprecated. It is recommended that customers use --type base-path or --type base-url instead. Support for --type regex will be removed in ORDS 19.4.0.
Oracle REST Data Services is compatible with Oracle WebLogic 12.2.1.3 and later. It is not compatible with older versions of Oracle WebLogic.
In ORDS 18.2.0 support was introduced for authenticating database users via HTTP Basic authentication (see below). In ORDS 18.3.0 the following changes have been made aimed at faciliating customers migrating from Oracle mod_plsql:
Custom Authentication Stored Function Support
With mod_plsql customers enabled custom authentication by implementing a stored function named: OWA_CUSTOM.AUTHORIZE. Oracle REST Data Services provides equivalent functionality via the security.requestAuthenticationFunction stored function. This setting names a stored function that takes zero arguments and returns a boolean indicating if authentication was succesful or not. The function should use the Oracle Web Agent (OWA) PL/SQL APIs to examine any or all of the following package level variables: owa.user_id, owa.password, owa.ip_address and owa.hostname and/or the OWA APIs to examine the request's headers and parameters.
Note that this facility is provided to assist customers migrating from existing mod_plsql installations. Its use is not recommended outside of these scenarios, as it uses HTTP Basic authentication only.
Per Request Validation
One difference in behaviour between Oracle REST Data Services and mod_plsql is that out of the box ORDS caches the result of validating a procedure name. The intent is that the set of whitelisted procedure names is fixed, and thus validation outcomes can be cached. However mod_plsql does not behave this way, the request validation function is invoked on every request. In addition the request validation function is executed after the OWA (Oracle Web Agent) environment has been initialized for the request, so the validation function can examine the headers and parameters of the request, and thus can make decisions about whether to authorize the request based on the contents of the request in addition to the name of the procedure being invoked.
Some mod_plsql customers have come to rely on this behaviour to perform application specific validation, user authentication and authorization, thus to facilitate those customers, ORDS 18.3.0 provides the capability to replicate this behaviour of mod_plsql. This done by setting the configuration property named: security.maxEntries to zero. This can be done in defaults.xml (if it should apply across all pools) or in a specific pools configuration file. Setting this value to zero disables caching of procedure validations, leading to behaviour equivalent to mod_plsql.
HTTP Basic dynamic authentication for PL/SQL Gateway requests
To facilitate customers migrating from Oracle mod_plsql to Oracle REST Data Services, this release introduces support for authentication of database users using HTTP Basic Authentication. This functionality is equivalent to the Basic authentication mode in mod_plsql where the database user name and password are omitted from the mod_plsql DAD.
For performance and security reasons we strongly advise customers not to use database authentication in general. The only way to validate a database password is by creating a connection to the database, which is very expensive. Database passwords are often weak and poorly chosen on the assumption that they are not accessible from the web. The HTTP Basic Authentication scheme lacks a mechanism for terminating (logging out) a user session. The only way to end the session is to close the Browser.
The only scenario where using database authentication is acceptable is for migrating existing applications from mod_plsql that are reliant on database authentication, and the database is appropriately configured with a strong password strength and expiration policy.
ORDS 18.3.0 introduces the ability for a stored function to be invoked prior to the dispatching of an ORDS based RESTful Service. This facility enables customers to perform additional request validation and authorization and/or configure the database session as required. In addition this facility provides a means for the pre-hook to assert the identity and roles of the user making the request, thus facilitating integration with custom authentication mechanisms.
As of release 18.2.0, ORDS no longer installs its ORDS_METADATA schema into the CDB$ROOT container. Now only the ORDS_PUBLIC_USER common user is installed in the CDB$ROOT (and ALL PDBs connected to the CDB). The ORDS_METADATA schema is installed in each PDB connected to the CDB. This aids future upgrades of ORDS, minimizing downtime as the CDB and PDBs will no longer need to be all taken offline at the same time for an ORDS upgrade.
The installation changes are supported for Oracle database 12.1.0.2 and later in this release.
For Oracle database 12.2.0.1 or later, the installer will check if the PDB initialization parameter PDB_LOCKDOWN contains a PDB lockdown profile. If a PDB lockdown profile exists, then it will disable the PDB lockdown profile during ORDS install or upgrade, and will enable it when the install or upgrade completes.
If you do not want the ORDS installer disabling the PDB lockdown profile during ORDS install or upgrade, then you can set the pdb.disable.lockdown property to false in the ORDS parameter file:
pdb.disable.lockdown=false
Oracle REST Data Services requires Java 8 or later. Java 7 is no longer supported. Please consult the documentation for the minimum supported Application Server versions for ORDS.
X-DB-Content-Length response header produced by OWAurl-mapping.xml based mapping that uses --workspace-idsecurity.requestValidationFunction setting configurable per database poolexamples/soda/getting-started/ for the SODA featureords-scripts commanddb.password values prefixed with ! being encryptedNone
From ORDS 18.1.0 and later you can launch ORDS on JDK 9 by just typing:
java -jar ords.war <command-name>
--add-modules java.xml.bind command line argument has been eliminatedORDS passes array values to the Oracle Database in a number of cases, for example arrays are used to pass the request headers and form fields during PL/SQL Gateway calls. Oracle JDBC Driver 18.3 and later supports an improved mechanism for passing array values, however this feature is only supported on Oracle Database 12c and later. Thus ORDS uses existing deprecated and less efficient APIs for passing array values when connecting to 11G databases, and the improved mechanism when connected to 12c and later. Customers experiencing problems with passing large array sets (for example OutOfMemory exceptions) are encouraged to upgrade from 11G to a newer database version to mitigate these issues.
/sign-in/ interactive sign in form. Accessing /sign-in/ in APEX workspaces will produce a 404 status.The typical manner to start ORDS in standalone mode, once ORDS has been configured is:
java -jar ords.war
ORDS will detect that it is fully configured and proceed to launching standalone mode. Since 18.2 the ORDS_METADATA schema is not installed in the CDB, which means that when the default pool is connected to a CDB there is no way for ORDS to automatically verify the version of the ORDS schema installed in the database, thus ORDS prompts for the SYS AS SYSDBA password so it can connect to each PDB and verify the ORDS version installed in each PDB. This means that when connected to a CDB the above command is not sufficient to start standalone mode automatically. To work around this issue, use the following command to start ORDS (only after the ORDS instance has been configured) in standalone mode automatically:
java -jar ords.war standalone