Skip to main content

External secrets manager

Overview​

The External Secrets Manager page helps you integrate and manage external secrets from AWS and Azure within the Cinchy platform.

Prerequisites​

To use the External Secrets Manager, it's important to have the following:

  • Working knowledge of how to configure secrets on either AWS or Azure platforms.
  • An understanding of the Cinchy secrets manager.

Supported types​

The External Secrets Manager supports the following types of authentication from AWS and Azure:

AWS​

  1. AWS access keys for IAM users
  2. IAM roles
info

The IAM role must be assigned to the web pod the same way it is done for connections.

Azure​

  1. Managed identities (when Cinchy Web is hosted on Azure)
  2. Registered applications

Table overview​

The External Secrets Manager table has the following unique columns:

Column NameDescription
NameUnique name of the external secret.
TypeLists the platform type of the secret. Options include AWS Secrets Manager or Azure Key Vault.
Parameters JSONThe JSON object that contains the mandatory information for each secret type. Refer to the JSON requirements section for more details.
Read GroupsThe Cinchy Groups that have read access to the record.
Write GroupsThe Cinchy Groups that have write access to the record.
IDThe auto-generated GUID.
ID OverrideThe value you enter into this field will override ID.
Sync GUIDThe Sync GUID is used to facilitate DXD Workflows.
DescriptionUseful to help others understand the usage/purpose of the secret.

Parameters JSON​

Each secret type has a JSON schema (Parameters JSON) that must be filled with mandatory values. Select the tabs below for a description and example of each JSON schema.

KeyDescriptionExample
authTypeMandatory. Indicates the type of authentication used. "AWS Access Key" signifies the use of an AWS Access Key for authentication."AWS Access Key"
parametersA nested JSON object containing specific configuration details.
regionMandatory. Specifies the AWS region."ca-central-1"
accessKeyMandatory. The AWS Access Key ID, part of the credentials used to authenticate and authorize AWS service requests."AKIAIOSFODNN7EXAMPLE"
secretAccessKeyMandatory. The Secret Access Key associated with the Access Key ID, used for secure AWS service requests."wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Access key example​

{
  "authType": "AWS Access Key",
  "parameters": {
    "region": "ca-central-1",
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Create AWS Secret Manager secrets​

Follow these steps to create secrets in the AWS Secret Manager.

  1. Open AWS Secret Manager.
  2. Navigate to Secrets > Store a new secret > Other type of secret.
  3. Add in your keys, values, secret name, and other other relevant fields.

Cinchy environment settings secrets

  1. Open AWS Secret Manager.
  2. Navigate to Secrets > Store a new secret > Other type of secret.
  3. Add the following keys and values:
KeyValue
encryptionkeyYour encryption key, set to random 32-byte value in a 64-character hexadecimal string format. This should only be set on initial environment creation, and cannot be rotated thereafter.
connectionspasswordThe connections@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
workerpasswordThe worker@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
eventlistenerpasswordThe eventlistener@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
maintenancepasswordThe maintenance@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
cinchyautomationspasswordThe automations@cinchy.com user account password. A unique value should be set for each environment. Password can be rotated per your password policy.
notificationpasswordThe notification@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
  1. Update the Secret Name as follows:
    • cinchy-environment-settings-<cinchy_instance_name>, for example cinchy-environment-settings-<development>.
  2. Update other fields as needed.

Additional AWS Secret Manager Secrets

Use the below to create additional secrets, using your own instance name where indicated.

  • The initial Secret Value will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations\<cluster_name>\<cinchy_instance_name>\secrets
KeySecret Name
'orchestrationautomationrunnersecretappsettings'orchestration-automationrunner-secret-appsettings-<cinchy_instance_name>
'orchestrationautomationrunnersecretconfig'orchestration-automationrunner-secret-config-<cinchy_instance_name>
'orchestrationschedulersecretconfig'orchestration-scheduler-secret-config-<cinchy_instance_name>
connectionssecretconfigconnections-secret-config-<cinchy_instance_name>
connectionssecretappsettingsconnections-secret-appsettings-<cinchy_instance_name>
eventlistenersecretappsettingsevent-listener-secret-appsettings-<cinchy_instance_name>
formssecretconfigforms-secret-config-<cinchy_instance_name>
maintenanceclisecretappsettingsmaintenance-cli-secret-appsettings-<cinchy_instance_name>
workersecretappsettingsworker-secret-appsettings-<cinchy_instance_name>
websecretappsettingsweb-secret-appsettings-<cinchy_instance_name>
mcpsecretappsettingsmcp-secret-appsettings-<cinchy_instance_name>
notificationsecretappsettingsnotification-secret-appsettings-<cinchy_instance_name>

If SSO is enabled:

KeySecret ValueSecret Name
idpsecretappsettingsThe content of the relevant JSON of cinchy.kubernetes\environment_kustomizations\<cluster_name>\<cinchy_instance_name>\secretsidp-secret-appsettings-<cinchy_instance_name>
idpsecretmetadataSSO metadata.xml contentidp-secret-appsettings-<cinchy_instance_name>

Create Azure Key Vault secrets​

Follow these steps to create secrets in Azure Key Vault.

  1. Navigate to your Key Vault in the Azure portal.
  2. Open Key Vault Objects > Secrets.
  3. Click Generate/Import.
  4. Input your secret name and value.
  5. Select Create.

Additional Azure Key Vault Cinchy secrets

  1. Navigate to your Key Vault in the Azure portal.
  2. Open Key Vault Objects > Secrets.
  3. Click Generate/Import.
  4. On the Create a Secret screen, choose the following values:
    1. Upload options: Manual.
    2. Content Type: JSON
    3. Name and Value: Choose the secret name and value from the below list, replacing 'cinchy_instance_name' where indicated:

Environment settings

KeyValue
encryptionkeyYour encryption key, set to random 32-byte value in a 64-character hexadecimal string format. This should only be set on initial environment creation, and cannot be rotated thereafter.
connectionspasswordThe connections@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
workerpasswordThe worker@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.
eventlistenerpasswordThe eventlistener@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy..
maintenancepasswordThe maintenance@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy..
cinchyautomationspasswordThe automations@cinchy.com user account password. A unique value should be set for each environment. Password can be rotated per your password policy.
notificationpasswordThe notification@cinchy.com service account user password. A unique value should be set for each environment. Password can be rotated per your password policy.

Additional secrets:

NameValue
worker-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
web-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
maintenance-cli-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
idp-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
forms-secret-config-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
event-listener-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
connections-secret-config-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
connections-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
idp-secret-metadata-<cinchy_instance_name> (Note: This is an additional secret only required when sso_enabled=true in the azure.json file)The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
orchestration-automationrunner-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
orchestration-automationrunner-secret-config-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
orchestration-scheduler-secret-config-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
mcp-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
notification-secret-appsettings-<cinchy_instance_name>The value for the secret will be the content of the relevant JSON of cinchy.kubernetes\environment_kustomizations<cluster_name><cinchy_instance_name>\secrets
  1. Leave the other values to their defaults.
  2. Select Create.

Set up an external secret​

To set up an external secret, do the following:

Configure your secret​

  1. Create your secret using the preferred platform and secret type (Create an AWS Secrets Manager secret, Create Azure Key Vault Secret).
  2. In the External Secrets Manager table, enter a unique name for your configuration.
  3. Select the platform type under the Type column.
  4. Select a JSON schema from the JSON schema section and enter the mandatory information for your secret.
  5. Copy the schema into the Parameters JSON column.

Use external secrets in Cinchy​

To use the external secrets from the External Secrets Manager table as secrets in Cinchy, such as in a data sync, do the following:

  1. In the Secrets table, select the External view.
  2. In the Secret Source column, select "External".
  3. Select a Domain and enter a Name for your secret.
  4. In the External Secret Manager column, select the ID or unique name of your external secret.
  5. In the External Secret Identifier column, enter the name of the secret as it appears in AWS or Azure.
  6. If your secret consists of multiple key value pairs, enter the name of the key for this secret in the Sub Key column.

Image 1: Example 1

Store a certificate or private key​

Cinchy passes an external secret on exactly as AWS or Azure returns it. It does not trim the value, decode it or change its line breaks. A certificate or private key used by a connection, such as the client certificate and key of a Kafka Topic destination, must therefore resolve to the full PEM block with real line breaks:

-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIUQ...
...
-----END CERTIFICATE-----

Store it as text: in AWS as the secret string (Cinchy does not read a binary secret), in Azure as a Key Vault secret. Use one of the two layouts below.

One PEM per secret​

The whole secret value is the PEM, and Sub Key is left blank. Paste the PEM with its line breaks as they are. Do not type \n in place of the line breaks: without a Sub Key, nothing decodes it, and the connection receives the two characters \ and n.

Loading the file directly avoids copy and paste altering the line breaks:

# AWS Secrets Manager
aws secretsmanager create-secret --name kafka-client-certificate --secret-string file://client.crt

# Azure Key Vault
az keyvault secret set --vault-name <vault-name> --name kafka-client-certificate --file client.crt

Several PEMs in one key/value secret​

The secret value is a flat JSON object, and each Cinchy secret names its key in Sub Key. Here each PEM is a JSON string, so its line breaks must be written as \n, which Cinchy decodes when it reads the key:

{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUQ...\n-----END CERTIFICATE-----\n",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0B...\n-----END PRIVATE KEY-----\n"
}

The object must be flat. A nested object fails with an error asking you to check the format of the secret value.

Check what a secret resolves to​

To see the value a connection receives, call the secrets API for the Cinchy secret. The response is JSON, so a correct PEM shows its line breaks as \n. A value showing \\n holds a literal backslash and n, and one with spaces between the base64 lines had its line breaks removed. Both are rejected by the connection as not being in PEM format.

Use encrypted parameters​

The External Secrets Manager table also supports encrypted versions of your field, such as a secret access key.

To use an encrypted version, do the following:

  1. Use the Worker CLI --encrypt command on your target parameter.
  2. Copy the value of into the target JSON parameter.

For more information, please see the CLI Command list