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. 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
Workflow Hub supports the registration of AWS secret manager. Every tenant can configure one secret manager to be used with their workflow executions.
How does it work
- User would pre-configure the access credentials to access AWS Secret Manager.
- 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 keytca_password_in_regionx
. The user can use this password in the workflow by invoking$SECRETS.tca_password_in_regionx
. - Once Workflow identifies the key, it will invoke a call to AWS Secret Manager. The Secret Manager will respond with the value.
- 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
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
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.
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.