Skip to main content

Workflow Secrets

Many applications require the use of sensitive values that should be protected from exposure. Items like usernames, passwords, API keys etc. are all sensitive values that should not be kept in a workflow (that might end up on GitHub or another public site.)

Just as programming languages and GitHub have the concept of secrets, so does Orkes Conductor. You can define your variables in a secure and safe way knowing that they will not be exposed in the workflow, or shared with other teammates.

Using a Secret​

To use a secret in a workflow, you must first create a secret.

Let's assume your secret is called GitHub_Token To reference that secret, use the variable ${workflow.secrets.GitHub_Token}.

Example​

The US Postal Service offers APIs to help automate the shipping process with the post office. Each API call requires a UserId to be submitted. This UserId can be used to buy postage, so it needs to be kept secure. WE've created a secret called post_office_username that we can now use in all API calls. (This workflow can be found is the Conductor Examples github repository.):

https://production.shippingapis.com/ShippingAPI.dll?API=RateV4&XML=<RateV4Request \
USERID=${workflow.secrets.post_office_username}> \
<Revision>2</Revision> \
<Package ID="0"><Service>priority</Service> \
<ZipOrigination>04046</ZipOrigination> \
<ZipDestination>98260</ZipDestination> \
<Pounds>20</Pounds> \
<Ounces>0</Ounces> \
<Container>variable</Container> \
<Width>12</Width> \
<Length>12</Length> \
<Height>12</Height> \
<Girth></Girth> \
<Machinable>TRUE</Machinable> \
</Package></RateV4Request>

By using ${workflow.secrets.post_office_username}, we obfuscate this sensitive value, and it never appears in the workflow execution, or in any output files of Conductor, yet we are able to connect with the USPS, and obtain the postage price for our package ($82.10, in case you're wondering).

Creating a secret​

We'll walk through a few approaches to create a secret, and then examples of implementing a secret. To create a secret, you can use the API or you can use the Orkes Dashboard.

Each secret must have a unique key for your Conductor instance. The first step in creating a secret key:value pair is to ensure that the key is not in use.

Check key usage​

The endpoint to check for key existence is api/secrets/{key}/exists.

Note: Here's how to quickly get an Orkes Access Token, and here's the programmatic way to get an Access Token

If the key for the secret is to be pinetree, you could use curl to do the following:

curl -X GET "https://play.orkes.io/api/secrets/pinetree/exists" \
-H  "accept: application/json" \
-H  "X-Authorization: <access_token>"

In this case, the response comes back 

false

As this key is not in use, we can now create a secret with the key pinetree. This uses a PUT to the endpoint api/secrets/{key}

curl -X PUT "https://play.orkes.io/api/secrets/pinetree" \
-H  "accept: application/json" \
-H  "X-Authorization: <access_token>" \
-H  "Content-Type: application/json" \
-d "needles"

This creates the secret key:value pair of pinetree:needle. The only response to the API is HTTP 200.

Permissions​

If a workflow uses a Secret, we need to add access control permissions for the application to access the secret (just as an application gives access to a workflow or task).

There are 3 access parameters used with Secrets:

  • READ: Allows the application to read (and therefore use) the secret.
  • UPDATE: Provides access to share the secret with others.
  • CREATE: Create or overwrite an existing secret.

In general, READ is the permission to be shared in most cases.

The endpoint is /api/auth/authorization.

Using the Playground and Curl, the command looks like:

curl -X POST "https://play.orkes.io/api/auth/authorization" \
-H  "accept: application/json" \
-H  "X-Authorization: <access_token>" \
-H  "Content-Type: application/json" \
-d '{"subject":
        {"type":"user",
        "id":"app:orkes-workers"},
    "target":
        {"type":"SECRET_NAME",
        "id":"post_office_username"},
    "access":["READ"]}'

Note that the type is SECRET_NAME.

In this call, we are give the application orkes-workers READ access to our post_office_username secret.