What You See Is What You Get Element

Oracle REST Data Services 18.4.0.354.1002


Release Notes


Date: January 2019

Oracle REST Data Services on OTN | Downloads | Forum


Support

  • You are supported by Oracle Support under your current Oracle Database Support license for Oracle REST Data Services production releases .
  • Log Oracle REST Data Services bugs and issues using My Oracle Support.

    • For problems specific to SODA for REST, file a service request using "Oracle XML Developers Kit" as the product.
    • For all other problems, use "Oracle REST Data Services" as the product.

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

  • None

JDK Support

  • ORDS will run and is supported on JDK 9 however the only supported way to use ORDS on JDK 9 is by running it in standalone mode, as currently neither Oracle WebLogic or Glassfish are certified for use with JDK 9, and ORDS has not yet been certified on Apache Tomcat on JDK 9.
  • From ORDS 18.1.0 and later you can launch ORDS on JDK 9 by just typing:

    java -jar ords.war <command-name>
    • The requirement in 17.4 to use the --add-modules java.xml.bind command line argument has been eliminated

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.