Configure a Vault for a Custom Endpoint

To create a custom endpoint for your Visual Builder instance, you can use the Key Management Service in OCI to create a vault to store the master encryption keys and secrets used to protect access to your custom endpoint.

In the OCI Console, you create an OCI vault in the compartment where you want to create your custom endpoint. For more details on working with vaults, see Working with Compartments, Overview of Vault, and Create a New Vault.

Note:

If you are using a WAF and load balancer to protect your custom endpoint, you don't need to create a vault.

After you create and configure a vault in the OCI Console, you can configure your instance's first (primary) custom endpoint in the Visual Builder Instance details page. If your instance already has a primary endpoint and you want to add another, you need to create an alternate endpoint from the command line. Similarly, if your instance already has multiple custom endpoints and you want to edit any of them, you also need to do that from the command line. For details, see Create and Update Alternate Endpoints.

When creating the secret in your vault, you'll need to provide a secret certificate that contains:

• the hostname's SSL certificate,
• the matching private key, and
• all intermediate certificates in the SSL chain.

You'll also need to provide a passphrase if the SSL certificate requires one. You can obtain these from your SSL certificate provider.

Note:

You can use openssl to validate the SSL certificate and private key.

To create and configure an OCI vault in the OCI Console:

1. In the OCI Console, click Navigation Menu , select Identity & Security, and then select Vault to open the Vaults page.
   
   

   
   Description of the illustration vault-oci-console.png

   
   
2. On the Vaults page, click Create Vault to open the Create Vault panel.

   In the Create Vault panel, confirm you are creating the vault in the correct compartment. If you are not in the correct compartment, select the compartment in the Create in Compartment dropdown list.

3. Enter a name for the vault. Click Create Vault to return to the Vaults page.
   
   

   
   Description of the illustration vault-create-vault.png

   
   

   After you click Create Vault, it can take a few minutes for the new vault to appear in the table on the Vaults page.

4. In the table on the Vaults page, click the name of the vault you created to open the vault's details page.
5. Create a master encryption key for the vault.
   1. Open the vault's Master Encryption Keys tab.
   2. Click Create Key to open the Create Key panel.
      
      

      
      Description of the illustration vault-create-key.png

      
      
   3. Enter a name for the key in the Name field.

      To create the key, you only need to enter a name. Use the default settings for the other options.

   4. Click Create Key to return to the Master Encryption Keys tab.
      
      

      
      Description of the illustration vault-masterkeys-tab.png

      
      
6. Create the secret.

   Store the certificate as a secret in the OCI Vault. For more about secrets, see Create a New Secret.

   1. Open the vault's Secrets tab.
   2. Click Create Secret to open the Create Secret panel.
   3. Enter a name and description for the secret.
   4. In the Encryption Key dropdown list, select the key you created in the Master Encryption Keys tab.
   5. Select Manual secret generation.

      Make sure you explicitly select Manual secret generation. The default is Automatic secret generation.

      
      

      
      Description of the illustration vault-create-secret.png

      
      
   6. Generate the secret certificate and paste it into the Secret Contents field.

      Use the following format for the certificate:

      {
        "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>"
      }

      When generating the certificate, note the following certificate requirements:

      • The key and cert elements are required.
      • Each intermediate certificate must be specified as a separate element in an intermediates array. In most cases there will only be one intermediate. The intermediate is provided by the SSL provider.
      • 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 only required if the private key is encrypted with a passphrase. Do not include the attribute if it's not required.
      • 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

      Note:

      It is strongly recommended that you generate the certificate JSON from the Linux/Unix command line, or Unix utilities, to ensure that the line endings are encoded correctly. Incorrect line endings will result in an error.

      • 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 Visual Builder trust store, you must also upload the certificate to your Visual Builder instance; otherwise, an exception is thrown in the scenarios the instance calls itself.

      Use the default settings for the other options in the Create Secret page.

   7. Click Create Secret to return to the Secrets tab.
7. Create an Identity and Access Management (IAM) policy to:
   1. Allow the Visual Builder service to read the version and contents of the secret.

      Here's the policy syntax for a Visual Builder service:

      allow group <group-name> to read secret-bundle in compartment <secrets-compartment>

      Here's an example:

      allow group VBInstanceAdmins to read secret-bundle in compartment MySecretCompartment

      If the VB instance is NOT in a default domain, then you need to include the domain prefix in front of the group name.

      Here's an example:

      Allow group mydomain/VBInstanceAdmins to read secret-bundle in compartment MySecretCompartment

   2. Allow the admin group to access the secret, key, and vault (or create a new secret, key, and vault), while creating or updating a Visual Builder instance with a custom endpoint.

      Here's the policy syntax:

      allow group <group-name> to manage secrets in compartment <secrets-compartment>

      allow group <group-name> to manage keys in compartment <secrets-compartment>

      allow group <group-name> to manage vaults in compartment <secrets-compartment>

      and here are examples:

      Allow group VBInstanceAdmins to manage secrets in compartment MySecretCompartment

      Allow group VBInstanceAdmins to manage keys in compartment MySecretCompartment

      Allow group VBInstanceAdmins to manage vaults in compartment MySecretCompartment

      If the VB instance is NOT in a default domain, then you need to include the domain prefix in front of the group name.

      Here are examples:

      Allow group mydomain/VBInstanceAdmins to manage secrets in compartment MySecretCompartment

      Allow group mydomain/VBInstanceAdmins to manage keys in compartment MySecretCompartment

      Allow group mydomain/VBInstanceAdmins to manage vaults in compartment MySecretCompartment

   Note that you should specify the resource to return in <resource-type>, as described in Details for the Vault Service.

   For the policy statement syntax, see Table 3-1 above, and CreatePolicy API Request.