Oracle REST Data Services 18.4.0.r3541002
Release Notes
Date: January 2019
Support
Documentation
- Documentation for this release is provided on the OTN web site. Click
here
to view the documentation.
- Documentation on using SODA for REST is provided on OTN
here.
Getting Started
- A tutorial on getting started with developing RESTful Services is included in the
product documentation
, in the book titled 'Oracle® REST Data Services Quick Start Guide'.
Feedback
- You can discuss issues on the
forums.
- Be sure to use clear subject lines to initiate a thread. Provide a complete and clear description of the issue, including
steps to reproduce the issue.
- Try to avoid using old, unrelated threads for a new issue.
Important Changes to Note
Deprecation of Apache FOP PDF Support
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.
Deprecation of URI Template Syntax for ORDS Based REST Services
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.
Deprecation of Regular Expression based URL Mappings
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.
Supported WebLogic Version
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.
Improvements to PL/SQL Gateway to aid transition from mod_plsql
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.
You can learn more about this feature in the tutorial located
here.
RESTful Services Pre-Hook Function
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.
You can learn more about this feature in the tutorial located
here.
Changes to Installation in CDB$ROOT
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.
Disabling/enabling PDB Lockdown Profile during install/upgrade
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
Supported Java Version
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.
Changes in 18.4.0
The following changes and enhancements have been made since 18.3.0:
Issues Fixed in 18.4.0
- BUG:29053557 - Determine administrative database users based on granted database role
- BUG:29049176 - Show 403 Forbidden status when REST Service fails due to database user lacking privilege to access objects referenced in the SQL statement
<
- BUG:28520359 - Show Oracle Logo in UI
<
- BUG:29011184 - Suppress unsupported and undocumented
X-DB-Content-Length
response header produced by OWA
- BUG:28877175 - Fix resolution of
url-mapping.xml
based mapping that uses --workspace-id
- BUG:28997641 - Gracefully cope with database password rotation
- BUG:28964132 - ORDS installer won't accept passwords more than 28 bytes long
- BUG:28808094 - Uptake Apache Commons Logging 1.2
- BUG:28787846 - Uptake Apache PDFBox 2.0.12
- BUG:28719460 - Uptake Javassist 3.23.1-GA
- BUG:28719440 - Uptake Jetty 9.4.12
- BUG:28719424 - Uptake Jackson 2.9.7
- BUG:28561298 - Address problem with upgrading from ORDS 17.4.1
- BUG:28518849 - Fix problem with OAuth token lifetimes not being calculated correctly
- BUG:28466581 - Fix 500 Error status on open-api-catalog resources
- BUG:27992525 - Fix access to metadata-catalog when no authorization required
- BUG:27933884 - Fix parsing of Resource Handler content to recognize parameters more precisely
- BUG:27808357 - Enhance performance of AutoREST tables/views
New Features in 18.4.0
- ENH:23666046 - Make
security.requestValidationFunction
setting configurable per database pool
- ENH:28028432 - Echo p_comments value into generated Swagger documentation
Changes in 18.3.0
The following changes and enhancements have been made since 18.2.0:
Issues Fixed in 18.3.0
- BUG:28700464 - Prevent caching of connections created via database authentication, leading to issues when database password changed
- BUG:28672484 - Fix problem that prevented PL/SQL Gateway file uploads working in non APEX environments
- BUG:28567990 - Fix regression that prevented dispatching of APEX based REST Services in CDB
- BUG:28518849 - Fix regression that caused OAuth token lifetimes to 1000 times what they should be
- BUG:23640562 - Provide means for authorized administrative database users to define ORDS REST Services in any schema
- BUG:28581365 - Fix 500 error problem that may occur when using database authentication
- BUG:28543131 - Enable a PL/SQL function to be invoked prior to dispatching ORDS RESTful Services
- BUG:26712420 - Fix issue with ORDS installer failing when using RAC
- BUG:28529274 - Fix problem during install when database auditing is enabled
- BUG:28528895 - Fix problem during install with closed PDBs using PDB lockdown
- BUG:28502103 - Deprecate legacy X-APEX-STATUS-CODE and similar headers, replace with X-ORDS-STATUS-CODE etc.
- BUG:28500353 - Uptake Jetty 9.4.11
- BUG:28500351 - Uptake Guava 26.0
- BUG:28500334 - Uptake Apache FOP 2.3
- BUG:28499759 - Fix problem with missing third party library: Javassist
- BUG:28485975 - Uptake Oracle 18.3.0.0 JDBC drivers
- BUG:28481972 - Fix problem with the casing of user chosen password
- BUG:28460781 - Fix problem with URL encoding of pound character in hyperlink values
- BUG:28445474 - Fix problem causing a query that uses manual pagination still being wrapped in an auto pagination clause
- BUG:28432949 - Enable self links in ORDS REST Services to have a trailing slash
- BUG:28407676 - Fix problem with ORDS schema alias 'hiding' APEX schema alias and preventing APEX based REST services from dispatching, causing plugin and application images to 404
- BUG:28394698 - Fix problem with performance of logging in certain cases when debug.printDebugToScreen enabled
- BUG:28394684 - Fix problem with masking of data in log files causing performance issues
- BUG:28352768 - Implement HEAD support for APEX based REST Services
New Features in 18.3.0
- ENH:28603664 - PL/SQL Gateway support for custom authentication
- ENH:28603635 - Provide means to disable caching of PL/SQL Gateway procedure validation
- ENH:28304149 - Improve PL/SQL Resource Handler usability
Changes in 18.2.0
The following changes and enhancements have been made since 18.1.1:
Issues Fixed in 18.2.0
- BUG:28225327 - Update the examples in
examples/soda/getting-started/
for the SODA feature
- BUG:28207743 - Fix resource leaks during AutoREST procedure invocation
- BUG:28094268 - Fix problem with serving of refreshed APEX static resources on Firefox & Edge
- BUG:28071398 - Address issue in ICAP functionality causing interoperability problem with McAfee virus scanner
- BUG:28207044 - Remove the previously deprecated
ords-scripts
command
- BUG:27916398 - Fix regression preventing dispatching of ORDS REST Services in APEX workspace where schema name not same as workspace name
- BUG:28000102 - Gracefully shutdown Standalone Mode, by waiting a short period to complete in flight requests when shutting down
- BUG:27992366 - Fix regression causing unintended Basic Authentication browser prompt during OAuth Token approval flow
- BUG:28000102 - Gracefully shutdown Standalone Mode, by waiting a short period to complete in flight requests when shutting down
- BUG:27994227 - Uptake version 9.4.10 of third party Jetty Library
- BUG:27994221 - Uptake version 2.9.5 of third party Jackson library
- BUG:27916570 - Handle migration of APEX based REST services with null URI prefix
- BUG:24941023 - Change what kind of URL paths are rejected by ORDS, only path traversal attacks are rejected now
- BUG:28043792 - Support RAW data type for REST Enabled SQL
- BUG:28086691 - Fix regression that prevents PL/SQL Gateway file uploads working (with NoClassDefFoundError)
- BUG:27882996 - Fix regression that prevented
db.password
values prefixed with
!
being encrypted
- BUG:28072133 - Fix issue with OAuth client icons not displaying in approval prompt
- BUG:27987547 - Fix premature removal of deprecated db.serviceNameSuffix related functionality
- BUG:28130669 - Ensure ORDS_METADATA schema password matches Oracle Database 18.1 complexity rules
- BUG:28130678 - Disable/Enable PDB lockdown profile during install
- BUG:28130669 - ORA-28003 Error during install on Oracle Database 18.1
- BUG:27832443 - Reduce size of Error Page by eliminating unused CSS
New Features in 18.2.0
- ENH:28180268 - Require Migration of ORDS_METADATA schema in CDB to PDB
- ENH:28149866 - Enable APEX workspace users to authenticate against ORDS based REST services
- ENH:28069808 - Detect when pool is pointing at a CDB service and auto enable URL mapping to each PDB connected to CDB
Changes in 18.1.1
The following changes and enhancements have been made since 18.1.0:
Issues Fixed in 18.1.1
- BUG:27165873 - Fix issue with ORDS.DELETE_CLIENT failing
- BUG:27540028 - Migrate CDB install to PDB install
- BUG:27505895 - Multithreading issue when dispatching resource modules under load
- BUG:27456593 - Issue with first part token session not expiring correctly
- BUG:27391040 - APEX OAuth Clients are forced to Token Response type when edited and saved
- BUG:26881221 - Fix regression preventing authentication of Tomcat based users
New Features in 18.1.1
- ENH:27741103 - Support HTTP Basic dynamic authentication for PL/SQL Gateway calls
Changes in 18.1.0
The following changes and enhancements have been made since 17.4.1:
Issues Fixed in 18.1.0
- BUG:27375052 - Eliminate need for --add-modules javax.xml.bind when running ORDS on JDK 9
- BUG:27374997 - Fix regression causing ORDS not to function on WebLogic 12C out of the box
New Features in 18.1.0
None
Known Issues
NoSQL Database Support
Support for Oracle NoSQL Database has been removed in ORDS 18.1.1 and later releases.
SODA
JDK Support
Autogenerated REST Endpoints
- AutoRest resources support the OAuth 2.0 Client Credentials flow only.
RESTful Services
- Application Express workspaces do not support first party authentication, and therefore do not support the
/sign-in/
interactive sign in form. Accessing
/sign-in/
in APEX workspaces will produce a 404 status.
Support For mod_plsql logmeoff
- The mod_plsql logmeoff mechanism is not supported reliably by modern browsers and it is not provided by ORDS.
The only way to end a HTTP Basic Authentication session is to close the Browser.
Starting Standalone Mode when connected to CDB
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
Support for apex.docTable
- apex.docTable (now depreciated) and owa.docTable should not be used for APEX 4.x and above as APEX provides its own document table.