Version: 6.3.3

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'
  1. 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.

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.

  • 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.

  1. Click Save.

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

Edit 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.

  1. 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.

dependency-check on secrets delete

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

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.