Simplified SSL Configuration for Oracle REST Data Services (ORDS) : A How-To Guide

July 19, 2023 | 4 minute read
Tanya Heise
Sr Principal Technical Support Engineer
Text Size 100%:

Simplified SSL Configuration for Oracle REST Data Services (ORDS) : A How-To Guide

Thank you to Mohammed Anwar Pasha for providing the information for this blog.

Introduction:

Starting with ORDS 3.0.5, it is now possible to configure ORDS with SSL in standalone mode, enhancing the security of your deployments. This guide will walk you through the steps required to configure SSL with ORDS, providing you with two options:

1. Using a self-signed certificate.
2. Obtaining a certificate from a Certification Authority (CA).


1. Configure SSL with Self-Signed Certificate:

This section will take you through the process of generating a self-signed certificate using OpenSSL and configuring ORDS to use it.

Steps:

Generate a self-signed SSL certificate using OpenSSL.

1. Open a command prompt and navigate to the directory where you installed OpenSSL.(OpenSSL version used here is: 1.0.2x)

openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048

 

2. Generate a certificate signing request (CSR):

openssl req -new -key private.key -out csr.csr

 

During the CSR generation process, you will be prompted to provide information such as your country, organization, common name (CN), etc. Fill in the appropriate details as required.

3. Generate a self-signed certificate using the private key and CSR:

openssl x509 -req -in csr.csr -signkey private.key -out certificate.crt -days 365

 

The -days parameter sets the validity period for the certificate. In this example, it's set to 365 days (1 year), but you can adjust it as needed.

The generated files are:

  • private.key: The private key file.
  • certificate.crt: The self-signed certificate file.

With the self-signed certificate generated, you can proceed with configuring SSL for ORDS using the private.key and certificate.crt files.

How to update ORDS configuration files for SSL:

For ORDS 21.4 and earlier versions, you need to edit standalone.properties file

jetty.secure.port=xxxx

ssl.cert.key=<DIRECTORY>/private.key

ssl.cert=<DIRECTORY>/certificate.crt

ssl.host=<DOMAINNAME>.com

"DOMAINNAME" should be replaced with the actual domain name or hostname associated with your server.


For ORDS 22.x and later versions, you need to edit settings.xml file.

<entry key="standalone.https.port">xxxx</entry>

<entry key="ssl.cert">/path/certificate.crt/</entry>

<entry key="ssl.cert.key">/path/private.key/</entry>

NOTE: Self-Signed certificates are intended for Development environments only and not for Production environments.

2. Steps to Configure SSL with Certificate from a Certification Authority (CA):

If you have purchased a certificate from a valid CA like DigiCert, the process for configuring SSL with that certificate for ORDS is slightly different. Here is a general outline of the steps you will need to follow:

This option is recommended for production environments, as it ensures the trustworthiness of your SSL certificates.

Obtain the SSL certificate: After purchasing the certificate from CA, they will provide you with the necessary files. Typically, these files include the SSL certificate itself, an intermediate certificate, and a private key.

If you have a private key which is in a format other than PKCS8 (e.g., PKCS12), you may need to convert it to PKCS8 format ( ORDS understand) using the OpenSSL utility.

To determine the format of your private key file, you can use the OpenSSL utility to inspect the file and check its format.

openssl rsa -in privatekey.key -noout -text

 

Replace privatekey.key with the path and filename of your private key file.

If you receive an error message or the command does not provide any output, it is possible that the file is not in a recognizable format.

In such cases, you may need to confirm the format with the source that provided the private key file

Let us assume if you receive private key file in PKCS12 format, you first need to convert the PKCS12 file to PEM format and then convert PEM to PKCS8 format

openssl pkcs12 -in certificate.p12 -out certificate.pem -nodes

certificate.p12 is the PKCS12 file you received from the CA, which usually contains both the SSL certificate and the private key bundled together.

certificate.pem is the desired output file name and can be changed to a name of your choice.

The above command will convert the entire PKCS12 file to PEM format and extract the SSL certificate and private key into the resulting PEM file (certificate.pem). The -nodes option is used to prevent OpenSSL from encrypting the private key with a passphrase, making it easier to use in configurations that require an unencrypted private key.

Convert PEM to PKCS8 format: Next, you can convert the PEM file to PKCS8 format using the following OpenSSL command:

openssl pkcs8 -in certificate.pem -out private.key -topk8 -nocrypt

 

The conversion to PKCS8 format-using OpenSSL is only necessary if the private key is provided in a different format (such as PKCS12) and needs to be converted to a format that ORDS understands (PKCS8).

Obtain the intermediate certificate: The CA should have provided you with the intermediate certificate file along with the SSL certificate.

The intermediate certificate helps establish a chain of trust between the root certificate authority (CA) and your SSL certificate.

You then need to open the intermediate certificate file in a text editor and copy its contents. Paste the copied contents at the end of the SSL certificate file. Save the updated SSL certificate file, which now contains both the SSL certificate and the intermediate certificate.(save the resulting file with a .crt extension for eg: certificate.crt)

Configure ORDS with the combined certificate:
Now you have certificate.crt and a private key.Refer to above section “How to update ORDS configuration files for SSL”

 

 

 

Tanya Heise

Sr Principal Technical Support Engineer

Tanya Heise is part of the Oracle Proactive Support team. During my years at Oracle, I have worked in both Technical Support and Consulting Services.


Previous Post

Advisor Webcast: Oracle SOA Suite JCA Adapters (JMS, AQ, MQ)

Tanya Heise | 2 min read

Next Post


July 2023 Oracle Access Management 12.2.1.4 Proactive Patch Released

Leah Thompson | 2 min read