Enabling CORS support for Db2 REST services

You can enable Cross-Origin Resource Sharing (CORS) support for Db2 to permit a web page or application to access remote content from a different domain (or port) than the site that the web page was loaded from. You can enable Db2 REST services to use the HTTP Cross-Origin Resource Sharing (CORS) protocols, including support for the CORS "pre-flight" HTTP OPTIONS verb and CORS HTTP request/response header fields.

Before you begin

Apply the PTF for APAR PH59837.

If you want to use the REST CORS functionality before the availability of the RACF module ICHRRCDX update that delivers the new DSNRAUTH class definition, your z/OS® RACF security administrator can temporarily create the DSNRAUTH class using the RACF dynamic class descriptor table (CDT) support. For more information, see Creating a temporary DSNRAUTH class by using the RACF dynamic class descriptor table.

About this task

Cross-Origin Resource Sharing (CORS) is a protocol standard for permitting a web page or application to access remote content from a different domain (or port) than the site that the web page was loaded from. For example, assume that a user loads a page from the “origin” site at mynode.ibm.com. The downloaded web page includes client-side content (such as Java Script) which invokes a Db2 native REST service using site db2server.ibm.com:446. The call to the Db2 REST service triggers the CORS protocols because the Db2 REST service site is different than the “origin” site where which the web page was originally loaded.

Db2 REST services supports the HTTP Cross-Origin Resource Sharing (CORS) protocols, including support for the CORS "pre-flight" HTTP OPTIONS verb and CORS HTTP request/response header fields.

The configuration and management of the Db2 REST CORS origin authorization rules are implemented using a new z/OS RACF RESOURCE CLASS (DSNRAUTH) and associated RACF generic or discrete resource profiles to represent the allowed remote (origin) sites.

The CORS origin checking is managed as a system wide Db2 setting which is independent of the "end-user" that is driving the CORS request. So, the authorization ID associated with the DDF address space (ssnmDIST) started task is used for the CORS origin resource authorization check.

Procedure

To enable and permit Db2 REST CORS support for a specific origin, complete the following steps.

Activate the RACF resource class DSNRAUTH, with ACTIVE and RACLISTED.
Optionally, if you intend to use generic Db2 REST service CORS profiles, also enable GENERIC for the DSNRAUTH resource class.
Create one or more RACF resource profiles to represent the CORS origin hosts that are allowed by the Db2 system.
An origin host for Db2 REST service CORS uses a naming convention, where an example is DSNCORS.DB2A.COM.SOMESERVER.WWW, with the following format:
```
DSNCORS.ssid|group-attach.normalized-origin-value
```
ssid|group-attach

For Db2 non-data sharing, the Db2 subsystem name (SSID) value is used. For Db2 data sharing, the Db2-group-attachment-name value is used.

normalized-origin-value
The format and content of the normalized-origin-value portion of a RACF Db2 CORS resource check depends on the type of the input origin value that Db2 receives in the REST request. Db2 REST CORS supports the input origin values in any of the following representations, with the option to specify a port:
- Regular hostname values, with the option to include a port.
- Internet Protocol Version 4 (IPv4) addresses, with the option to include a port.
- Internet Protocol Version 6 (IPv6) addresses, with the option to include a port. If the port is included, the IP address portion is enclosed within square brackets ('[' and ']').
- Special Internet Protocol Version 4 “mapped” Internet Protocol Version 6 dual stack (Hybrid dual-stack IPv4-mapped IPv6) addresses, with the option to include a port. If a port is included, the IP address portion must be enclosed within square brackets ('[' and ']').
For more information and examples, see Db2 REST services CORS resource naming conventions.
Permit the authorization ID associated with the Db2 DDF (ssidDIST) started task address space READ access to the just created resource profile.
Refresh the DSNRAUTH RACLIST by issuing the following command:
```
SETROPTS RACLIST(DSNRAUTH) REFRESH
```

Examples

Example 1

Enable Db2 REST CORS access on stand-alone Db2 subsystem DB2A, with a DB2ADIST started task ID of SYSDSP, from host origin "www.mybank.com":

RDEFINE DSNRAUTH DSNCORS.DB2A.COM.MYBANK.WWW UACC(NONE)
PERMIT DSNCORS.DB2A.COM.MYBANK.WWW CLASS(DSNRAUTH) ACCESS(READ) ID(SYSDSP)
SETROPTS RACLIST(DSNRAUTH) REFRESH

Example 2

Enable Db2 REST CORS access on Db2 data-sharing group with group attach name DB2G, where all members use the same DDF (ssidDIST) started task ID of SYSDSP for, from any host origin with ".org” as the top level domain:

RDEFINE DSNRAUTH DSNCORS.DB2G.ORG.** UACC(NONE)
PERMIT DSNCORS.DB2G.ORG.** CLASS(DSNRAUTH) ACCESS(READ) ID(SYSDSP)
SETROPTS RACLIST(DSNRAUTH) REFRESH

Example 3

Enable Db2 REST CORS access on stand-alone Db2 subsystem DB2D, with a DB2DDIST started task ID of SYSDSP, from any host origin under the "internal.myco.com" sub-domain:

RDEFINE DSNRAUTH DSNCORS.DB2D.COM.MYCO.INTERNAL.** UACC(NONE)
PERMIT DSNCORS.DB2D.COM.MYCO.INTERNAL.** CLASS(DSNRAUTH) ACCESS(READ) ID(SYSDSP)
SETROPTS RACLIST(DSNRAUTH) REFRESH

Example 4

Enable Db2 REST CORS access on stand-alone Db2 subsystem DB2A, with a DB2ADIST started task ID of SYSDSP, from host origin value "http://192.168.1.100":

RDEFINE DSNRAUTH DSNCORS.DB2A.0000.0000.0000.0000.0000.0000.192.168.001.100 UACC(NONE)
PERMIT DSNCORS.DB2A.0000.0000.0000.0000.0000.0000.192.168.001.100 CLASS(DSNRAUTH) – ACCESS(READ) ID(SYSDSP)
SETROPTS RACLIST(DSNRAUTH) REFRESH