Introduction

Workflows often make use of sensitive data such as credentials, private keys, etc (collectively referred to as secrets). for access to specific resources. If these are passed as part of input, then the sensitive data would be exposed externally. To avoid this, Workflow Hub supports secret manager integration. Instead of passing sensitive data as input, these secrets could be stored in a secure location such as AWS secret Manager (which is a secure key/value store). Then the workflows can refer to the sensitive data using the "key", which would be internally used to fetch the secret data, by invoking the appropriate APIs. The secret data would replace the "key" in the jq expression and the expressions would then be evaluated.

In this document, we discuss the capabilities of this service and the usage guidelines.

Supported Secret Managers

In Workflow Hub 3.0, the support is enabled for AWS Secret Manager. Every tenant can configure one secret manager to be used with their workflow executions.

How does it work

  1. User would pre-configure the access credentials to access AWS Secret Manager.
  2. User would invoke the sensitive data in the workflow by using the keyword $SECRETS. Whatever key follows $SECRETS would be interpreted by the workflow to be fetched from AWS Secret Manager. Suppose the user has stored tca_password with the key tca_password_in_regionx. The user can use this password in the workflow by invoking $SECRETS.tca_password_in_regionx.
  3. Once Workflow identifies the key, it will invoke a call to AWS Secret Manager. The Secret Manager will respond with the value.
  4. The Workflow Hub replaces the $SECRETS.key from the workflow expression with the value obtained from AWS Secret Manager. Subsequently the workflow expression gets evaluated and the results of the evaluation are propagated as before.

Prerequisites

The Secret Manager must be accessible to Workflow Hub.

Configuring the Secret Manager

Introduction

To access AWS Secret Manager from the workflows, the Workflow hub needs to be aware of the credentials to access AWS Secret Manager. This section describes the method to configure AWS Secret Manager credentials in Workflow Hub

Permissions and Privileges

By default the system and tenant administrators would have access to the configuration of the secret manager. The Secret Manager management is also available to the roles with the following privileges

  • Workflow Hub Secret Manager Write
  • Workflow Hub Secret Manager Read

If you do not see the administration tab in workflow-hub, then you do not possess the required privileges. If this is the case, kindly reach out to the system administrator to elevate your privileges

Click on Tenant Administration tab

Click on Tenant Administration tab

Here we see the Secret Manager expansion panel. Click the Secret Manager expansion panel to expand.

CUD Operations of Secret Manager Credentials

If you do not have any Secret Managers configured, then you will see Add button.

Clicking ADD opens up a text panel where you can provide the credential details

The Credentials are provided as a Json. The details of the parameters that go into the Credentials are discussed in the subsequent section.

If secret manager is already configured, you would see an edit (for update) and delete button (to delete credentials).

The Edit view is similar to Add view. Clicking on Delete unregisters the secret manager from the tenant and the credentials are deleted.

Parameters of Secret Manager Credentials

AWS Secret Manager Credential Parameters

AWS Secret Manager 
{
    "aws_access_key_id": "ASIAR4IKXIWTIZVMORVZ",
    "aws_region_name": "us-east-1",
    "aws_secret_access_key": "K0/3kNYo0y1S94hz/0Ks/0EGNvSHaMqhmVg5AoWp",
    "aws_session_token": "IQoJb3JpZ2luX2VjEG0aCXVzLWVhc..",
    "variable_prefix": "orgId/location/usw2"
}
AWS Secret Manager Credential Parameter Default Comment
variable_prefix None

This tells Workflow Hub the structure/hierarchy in the Amazon secret manager for fetching the variables.

In the example snippet configuration provided above, the value of this field is set to "orgId/location/usw2"

This means that if the Workflow requires the value of the Secret with "Password", then Workflow hub would search in the Amazon secret manager the value of the key "orgId/location/usw2/Password" If a value is found, it is presented to the Workflow Hub. Else an error is raised.

This means, when the secrets are stored in AWS Secret Manager they need to be stored with a Key that has the prefix as defined in the "variable_prefix" variable.

This approach enables the telco operator to have different teams in the organisation use different values for secrets, while using the same workflows (i.e., not modifying the Keys). Each team can behave as a different tenant under Workflow Hub and configure their own secret manager (with a different variable_prefix), while using the same Secret Manager account (i.e., retaining the same values for other fields)
aws_access_key_id Access Key ID from YOUR Amazon account. DO NOT USE the VALUE FROM THE EXAMPLE
aws_secret_access_key Access Secret Key from YOUR Amazon account. DO NOT USE the VALUE FROM THE EXAMPLE
region_name Region name of the ACCOUNT
aws_session_token

Session token from YOUR Amazon account. This is an optional field to cater for customers who impose a maximum time limit on their sessions.

It must be ensured that the session does not expire while Workflows are running. Otherwise, the Workflows will fail as the variables can no longer be fetched from Amazon.

DO NOT USE the VALUE FROM THE EXAMPLE.

Using Secrets in a Workflow

Sample Credentials
AWS Secret Manager 
{
    "aws_access_key_id": "ASIAR4IKXIWTIZVMORVZ",
    "aws_region_name": "us-east-1",
    "aws_secret_access_key": "K0/3kNYo0y1S94hz/0Ks/0EGNvSHaMqhmVg5AoWp",
    "aws_session_token": "IQoJb3JpZ2luX2VjEG0aCXVzLWVhc..",
    "variable_prefix": "orgId/location/usw2"
}

Assumptions

  • The Secret Manager must be configured with the credentials shown above
  • The user has stored the secrets in AWS Secret Manager as follows
Key Value
orgId/location/usw2/tca_username [email protected]
orgId/location/usw2/tca_password NotaDefaultPassword$%^&*
orgId/location/usw2/tca 10.10.10.10

Notice that the Key used by the user to store a secret is a concatenation of the field "variable_prefix" used in the configuration and the secret name used in the workflow.

Workflow Code Snippet
Sample Secret Manager Integration Example 
id: secrets-aws
name: Secret Manager Integration Example
version: 0.0.1
description: Workflow for Secret Manager Integration
specVersion: 0.7.0
start: Get_TCA_Session
secrets:
- tca
- tca_username
- tca_password
 
functions:
  - name: CreateTCASession
    operation: https://{tca}/hybridity/docs/apis/hcx_enterprise/platform.json#/paths/~1hybridity~1api~1sessions/post
    metadata:
      tlsVerify: false
      includeResponseHeaders: x-hm-authorization
 
states:
  - name: Get_TCA_Session
    type: operation
    actions:
      - functionRef:
          refName: CreateTCASession
          arguments:
            tca: "${ $SECRETS.tca }"
            username: "${ $SECRETS.tca_username }"
            password: "${ $SECRETS.tca_password }"
            Content-Type: application/json
    stateDataFilter:
      output: '${ {"x-hm-authorization"} }'
    end: true

The sample workflow makes a TCA session using the TCA IP and credentials stored in the AWS Secret Manager. Three secrets are declared (line 7-10). It is a prerequisite to declare the secrets before they are invoked in the workflow. If the secrets are NOT declared, the workflow cannot be saved in Workflow Hub as it is considered a compilation error.

  • tca
  • tca_username
  • tca_password

The action is a function call to CreateTCASession, which invokes a REST API to the "tca" IP using the "tca_username" and "tca_password" as credentials. These are passed to the function with the keyword "$SECRETS". As explained earlier, the presence of the $SECRETS keyword indicates to Workflow Hub that AWS Secret Manager needs to be invoked. Consequently, it will invoke the call to fetch the corresponding value. If the call is successful, the corresponding value replaces the key. In the above example,

  • $SECRETS.tca resolves to 10.10.10.10
  • $SECRETS.tca_username resolves to [email protected]
  • $SECRETS.tca_password resolves to NotaDefaultPassword$%^&*

Once these are resolved, the function call is made to TCA with these parameters. If the credentials are correct, the TCA would return the x-hm-authorization key which can be used for accessing other TCA resources. If the credentials are not correct, the call would fail resulting in the workflow failure.