Configure a Custom Endpoint for an Instance

You can create a custom hostname with your chosen domain (for example, mycustom.example.org) for your Oracle Integration instance.

Note

Associating a custom endpoint with your Oracle Integration instance doesn't affect the original instance URL. You'll be able to access your instance using the custom endpoint URL as well as the original instance URL.

Perform the following configuration tasks to successfully use a custom endpoint URL for your Oracle Integration instance:

Note

These instructions assume you have direct access to an Oracle Integration instance. If you are using the instance behind a WAF or an API Gateway, skip the certificate-related instructions provided here (from Step 3 onwards) and follow the WAF or API gateway certificate instructions instead. See WAF Certificates or Setting Up Custom Domains and TLS Certificates for API Gateways.

Choose a custom hostname for your instance and register it at a DNS provider.
Obtain an SSL certificate from a certificate authority (CA) for your hostname.
In your OCI tenancy, select a compartment and create an OCI Vault to store the certificate. See Working with Compartments, Overview of Vault, and Create a New Vault.
Store the certificate as a secret in the OCI Vault. See Create a New Secret. Use the following certificate format:
```
{
  "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>"
}
```
Note
- To avoid manual errors, you can also convert your PEM certificate into a single line containing "\n", as expected, with the following awk commands.
  For the leaf certificate:
```
awk -v RS= '{gsub(/\n+/, "\\n")}1' <cert_pem_file>
```
  For each intermediate/root certificate:
```
awk -v RS= '{gsub(/\n+/, "\\n")}1' <each_intermediate_cert_pem_file>
```
  For the private key:
```
awk -v RS= '{gsub(/\n+/, "\\n")}1' <private_key_pem_file>
```
- The latest version of the secret is used when you associate a custom endpoint with your instance either through the create instance or edit instance operation. For information on secret versions, see Secret Versions and Rotation States.
- If you use a hostname certificate whose certificate authority (CA) is not in the Oracle Integration trust store, you must also upload the certificate to your Oracle Integration instance; otherwise, an exception is thrown in the scenarios the instance calls itself.
Note the following certificate requirements:
- If the certificate has more than one root/intermediate certificate, each certificate must be specified as a separate element in an intermediates array.
- Always ensure that the final root CA is specified as the last element in the array. For example, if there are three intermediate certificates for the leaf certificate, the certificate that issued the leaf certificate should go as the intermediates[0] element, the certificate that issued the intermediates[0] certificate should go in the intermediates[1] element, and the certificate that issued the intermediates[1] certificate should go in the intermediates[2] element.
- The passphrase attribute is optional and does not need to be specified if the private key is not encrypted.
- If using an encrypted private key, the following format is required (PKCS1 is supported):
```
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
-----END RSA PRIVATE KEY-----
```
  A JSON file with an encrypted private key looks as follows:
```
{
  "key": "-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\n....\n-----END RSA PRIVATE KEY-----",
..
..
  "passphrase": "<passphrase to decrypt the key>"
}
```
  A JSON file with an unencrypted private key looks as follows:
```
{
  "key": "-----BEGIN RSA PRIVATE KEY-----\nvRXUK08v31bw2rnDLw+vjuX2i8ujHWs\n....\n-----END RSA PRIVATE KEY-----",
..
..
}
```
- If your private key is in PKCS8 format, you must convert it to PKCS1 format:
```
openssl rsa -in <input_pkcs8_encrypted_private_key> -out <converted_encrypted_private_key_file_name> -aes256
```
Create an Identity and Access Management (IAM) policy to:
- Allow the integration service to read the version and contents of the secret.
- Allow the admin group to access the secret (or create a new secret), while creating or updating an Oracle Integration instance with a custom endpoint.
For the policy statement syntax, see The OCI Policy to Manage Secrets and CreatePolicy API Request.
Create an integration instance and map the custom endpoint details to it. See Create an Oracle Integration Instance.
You can also edit an existing Oracle Integration instance and map a custom endpoint to it. See Edit the Edition, License Type, Message Packs, and Custom Endpoint of an Instance.
Finally, update the custom endpoint DNS record to the original instance hostname. As a best practice, update the CNAME of the DNS record with the hostname of the original instance endpoint.

If you are using three-legged OAuth with third-party identity providers (such as Google, Facebook, etc.), update the redirect URL with the custom hostname in your identity provider (IdP) application. If the custom hostname for your Oracle Integration instance is mycustom.example.org, your redirect URL must be, for example, https://mycustom.example.org/icsapis/agent/oauth/callback.
After updating the redirect URL in the IdP application, you must reacquire the access token by providing consent on the connection page.
If you had created integration flows prior to mapping a custom endpoint to your instance, you must deactivate and re-activate all those integrations to regenerate the WSDLs.

Note

If you're using the Oracle NetSuite Adapter, note that the adapter's TBA Authorization Flow security policy won't work with custom endpoints for Oracle Integration.

Oracle Cloud Infrastructure Documentation