Manage Secrets

This is a guide for Administrators about to how to create and use secrets for Skill properties.

Example use case

When a Skill or Connection has a property for which users must provide authentication credentials to call out to an external service, a secret must be created and stored to prevent exposing the credentials within the agent definition.

How Secrets Work in Fabric Overview

1. Identify any secrets that are needed during skill execution such as: API tokens, database passwords, or S3 credentials.
2. In the CLI or Console configure and save a secret reference key (string) (e.g. ref-key) and the value (password or token) for each secure variable your Skills require.
3. For each secure variable the Skill uses, add a property to the Skill definition (skill.yaml) that names the property (e.g. mydbpassword), marks it as a secret - secure: true, and specifies a defaultValue for the secret key prefixed with #SECURE. (#SECURE.ref-key in a secure property notifies the Agent or Skill runtime that it must lookup the values from the Fabric secrets API.)

- name: mypassword
  title: My password
  type: string
  secure: true
  defaultValue: '#SECURE.ref-key'

4. When you invoke the Skill or Agent (that uses the Skill), the property name and reference key are specified as --params {"properties":{}}.

   They are fetched from the skill.yaml, populated by the Fabric runtime, and passed to the Skill through the properties key in the Skills/action input message.

   cortex agents invoke my-agent my-service \
     --params '{"payload": {"text": "test"}, \
     "properties": {"secret-property-name": "ref-key"}}' \
     --project my-project

The sections below detail the steps above.

Configure Secrets using the CLI

For additional CLI options go to the CLI Reference Guide.

NOTE: Use options --project projectId or --profile profileName if you are not authenticated to a specific project or profile context.

• Only Administrators can configure secrets unless custom permissions for this component are setup.
• The administrator must know both the key and value to set secrets.
• Secrets created using the CLI are displayed (and selectable) in the Fabric Console.

note

• Secret key names must be unique in the SENSA Fabric instance. If you attempt to duplicate a name, an error is displayed.
• Secret key names must be alphanumeric, beginning with a letter and ending with a letter or number. In between dashes and underscores are allowed; no other special characters can be used.

Use the following commands to create different types of secrets:

Save a secrets with a String value

cortex secrets save mySecretKeyName simpleStringSecretValue --project projectName

Save a secret with a JSON value

cortex secrets save mySecretKeyName --data '{ "password": "secretValue123" }' --project projectName

Save a new key with JSON (or YAML) file path

cortex secrets save mySecretKeyName --data-file ./secret.json --project projectName

View a list of Secrets

View a list of secret keys saved for a project. Values are NOT displayed.

cortex secrets list --project projectName

Manage Secrets in the Console

Console displays and creates key-value pairs defined in the Secrets section for use with connections. The key-value pairs defined the Secrets section can be selected as secrets for Cortex component properties.

Only Administrators have access to Secrets in the Fabric Console.

View secret keys

Secret key-value pairs are displayed in the Secrets list in the Console Secrets section.

1. Log in to the Console
2. In the left menu panel select Secrets.

A list of secrets keys that have been created are displayed.

From the list view you can:

• Create a new Key/Value secrets pair
• Navigate to the detail page for a key by clicking the key name

On the key details page, you can edit the key and/or value.

Create Secrets

To create new key-value pairs in the Fabric Console:

1. Click Add Secret at the top right on the Secrets list page.

2. Enter information for the following values:

• Key: Enter a name for your key.

  note

  • Secret key names must be unique in the SENSA Fabric instance. If you attempt to duplicate a name, an error is displayed.
  • Secret key names must be alphanumeric, beginning with a letter and ending with a letter or number. In between dashes and underscores are allowed; no other special characters can be used.

• Value: Enter the secret value associated with your key.

  • String value type: Enter only lowercase characters when entering a value as a string.

  • JSON value type: Enter a JSON formatted value [{ "password": "value" }].

    The value is not displayed.

3. Click Save.

   Your new key is added to the Skill properties so a Developer can select it during Agent authoring.

Edit Secrets

caution

When Secrets values are changed, there are NO alerts or warnings provided to other users in Cortex. Administrators who set Secret key-value pairs are responsible for notifying collaborators using those Secrets.

To edit the details of a key in Admin Console Secrets:

1. From the Variable list click the name of a key.
2. On the detail page for the key you can:

• Edit the Key name.

• Edit the Value of the key.

  note

  The original value is not displayed (for security). Entering a new value changes the stored secret value. Agents or Skills using the original Secret value are affected by the change.

3. If you make changes to the key or value, click Save before exiting the page.

Delete Secrets using the CLI

Deleting Secrets is a protected action in Cortex. When you run the delete command an Impact Assessment is run, and if downstream dependencies are found, the deletion is not allowed, and the resources using that Secret are listed. You must remove dependencies to unblock the delete action.

To delete Secrets using the CLI.

1. Get a list of Secrets created for your project.

   cortex secrets list --project myProject

   Response:

   ┌─────────────────┐
   │ Secret Key Name │
   ├─────────────────┤
   │ aws-secret      │
   ├─────────────────┤
   │ other-secret    │
   └─────────────────┘

2. Delete a Secret.

   cortex secrets delete other-secret --project myProject

   Response: (When there are no downstream impacts)

   {
     "success": true,
     "message": "Secret other-secret deleted"
   }

note

Secrets cannot be deleted via the Fabric Console.

Apply Secrets to Agents and Skills

If your Skill requires sensitive information, such as a database password or AWS S3 key, it is best practice to have the Skill reference a Secret rather than accept a cleartext string.

Enter the Secret key in the skills.yaml file when you build the Skill.

- name: mypassword
  title: My password
  type: string
  secure: true
  defaultValue: '#SECURE.ref-key'

You can then apply Secrets to Skills in Agent Composer by selecting the key.

1. Click a Skill and go to the Properties panel at the far right.
2. In the Secrets dropdown, select the Secret Key to apply the value at runtime.
3. Click the check mark to save the selection.

Make sure the skill.yaml has a property that has a name, secure:true, and defaultValue: '#SECURE.ref-key'

Reference the secure property at runtime

Upon invoking and Agent or Skill reference the property name and reference key as a param property.

Example invoke with params:

cortex skills invoke my-skill my-service --params '{"payload": {"text":"test"}, "properties": {"secret-property-name":
"ref-key"}}' --project my-project

You can also save the params, including the secret property name and reference key, as a JSON file and point to the file location in the invoke command. See Invoke Agents.