Introduction

Fo this blog i partenerd with Ati and the following post is the fruit of this collaboration.
Oracle Integration cloud is a PaaS service part of Oracle Cloud Infrastructure.
By default, when you provision the service, your service console will be part of the domain integration.ocp.oraclecloud.com.
This blog is showing how to configure a custom endpoint for the service.

As a prerequisite, you need to have access to an OCI instance, have the required credentials to edit the service, create a vault, create a DNS records and access to a TLS certificate for the custom endpoint.

I will not cover the provisioning of the service and the acquisition of a public domain or a TLS certificate.

Upload the TLS certificate to OCI

The OIC service is not storing the TLS certificate, it is only accessing it from an OCI vault.
Before following the steps described in the official documentation found here, let's understand how the TLS certificate looks like.

Understand the TLS certificate chain structure

When you generate a TLS certificate, typically, you will have the following files: the certificate, the full chain and the private key.
The full chain contains the path between the certificate and the root CA. In my blog i am using a certificate issued by Let'sEncrypt. You can see bellow that if we open the certificate with an editor we can observe multiple individual certificate delimited by "BEGIN CERTIFICATE" and "END CERTIFICATE".

You can observe that this chain has three certificates.
I will decrypt bellow the content of the chain to see the order in which the certificates are stored.

openssl crl2pkcs7 -nocrl -certfile star.ateam-oracle.cloud.fullchain.crt | openssl pkcs7 -print_certs -noout

You can observe the following:

  • The first is the certificate itself which in this case is a wildcard certificate for *.ateam-oracle.cloud. The certificate is issued by R3;
  • The second certificate is the intermediate certificate authority R3. This certificate is issued by ISRG Root X1;
  • The third certificate is the root CA. The certificate is issued by the root CA.

Create the TLS certificate in JSON format

The JSON format that is accepted by the OCI vault looks like the below sample.

{
  "key": "-----BEGIN PRIVATE KEY-----\n…..-----END PRIVATE KEY-----\n",
  "cert": "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n",
  "intermediates": [
    "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n",
    "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n"
  ],
  "passphrase": "<private key password if encrypted key is provided>"
}
{
  "key": "-----BEGIN PRIVATE KEY-----\n…..-----END PRIVATE KEY-----\n",
  "cert": "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n",
  "intermediates": [
    "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n",
    "-----BEGIN CERTIFICATE-----\n….-----END CERTIFICATE-----\n"
  ],
  "passphrase": "<private key password if encrypted key is provided>"
}

You can observe that each certificate is in a single line.

Separate the chain file in individual certificates

We will separate the full chain with the following command which splits the file when it matches "—–BEGIN CERTIFICATE—–":
csplit -f cert- star.ateam-oracle.cloud.fullchain.crt '/-----BEGIN CERTIFICATE-----/' '{1}'
The result of the command are three files named cert-XX where XX is 00,01, and 02.

Create the certificate json file

Create a json file and paste the template shared earlier.
Format he certificate to be one line:

awk -v RS= '{gsub(/\n+/, "\\n")}1' <cert_pem_file>

Copy the result and paste it in the json. In my example, the result is showed below.

Do the same for all of the certificates. Please remember to put in the intermediates section first the intermediate CA and the root CA is always the last line in the intermediates array. In my example it will be the cert-01 and after that cert-02.
In the end the json will look like this (i do not have a password for the key file and my key is not encrypted ).
In my example, the JSON looks li this:

Inside the Vault create a Master Encryption Key

Create a Secret that will use as Master Encryption Key, they key that we just created with the Type "Plain-Text" and paste in the contents section the JSON content

Create the custom endpoint

Navigate to the Developer Services > Application Integration > Integration and edit you OIC instance.
Under the Advanced Options you will see the Custom Endpoint. Put the Hostname for the endpoint and choose the compartment and the vault where you stored your certificate.

Once the changes are done to your OCI instance, connect to the service URL. You will notice that the URL has the custom domain and the certificate that you imported in to the Vault.

Conclusion

In this blog we showed a step by step process to create a custom endpoint URL for the OCI instance.