Using Secrets in Workflow Services

This guide explains how to securely pass secrets to orchestrated services within your workflow, ensuring sensitive information like API tokens and credentials are handled safely.

Overview

When orchestrating services that require secret inputs, workflow services provide a special mechanism to securely pass these sensitive values without exposing them in logs or workflow variables.

How Secrets Work in Workflows

In workflow services, you can orchestrate services that require SecretValue parameters by:

1. Defining a $secrets input variable in your orchestration configuration
2. Mapping workflow input fields to orchestrated service secret parameters
3. The platform automatically handles the secure injection of secret values

This approach maintains security while allowing workflows to coordinate services that need sensitive credentials.

Basic Secret Mapping Syntax

To pass secrets to an orchestrated service, define a $secrets input variable with a mapping structure:

{
    "ibm_token": secret_value("field_name_in_json_input")
}

Structure Explanation:

• Key (ibm_token): The secret parameter name expected by the orchestrated service
• Value (secret_value("field_name_in_json_input")): Maps to a field in the workflow's JSON input where the secret value will be provided

Example: Orchestrating a Service with Secrets

Scenario

You have a workflow that orchestrates a quantum service requiring an IBM Quantum token for authentication.

Orchestrated Service

The target service expects a secret parameter:

from planqk.commons.secret import SecretValue

def run(circuit_data: dict, ibm_token: SecretValue) -> dict:
    """
    Executes a quantum circuit on IBM Quantum hardware.
    """
    token = ibm_token.unwrap()
    # Use token for IBM Quantum API authentication
    ...

Workflow Service

Let's imagine we just use a workflow service to orchestrate the service from above, simply like so:

○ → [Orchestrated Service] → ●

Workflow Input JSON

As the Orchestrated Service requires a circuit_data dictionary and an ibm_token secret, we could define to expose those parameters in the workflow input JSON like this:

{
  "circuit_data": {
    "qubits": 5,
    "gates": ["H", "CNOT"]
  },
  "$secrets": {
    "ibm_api_token": "your-secret-ibm-token-here"
  }
}

Input Mapping

Go to the input mapping of the Orchestrated Service in the workflow editor.

Click + for each input mapping:

Local variable name	Variable assignment value	Description
circuit_data	circuit_data	Direct mapping of the workflow input to the orchestrated service.
$secrets	{ "ibm_token": secret_value("ibm_api_token") }	Map secret ibm_api_token from workflow input to ibm_token of the orchestrated service.

How It Works Under the Hood

1. Workflow receives input with secret values in designated JSON field ($secrets)
2. Platform extracts secret values from the specified input fields (secret_value("field_name_in_json_input"))
3. During execution, the actual secret values are stored securely in a secure storage system designed for sensitive data
4. Secrets are injected as environment variables into the orchestrated service runtime
5. Orchestrated service receives SecretValue objects that wrap the sensitive data
6. After execution, secret values are purged from the secure storage system
7. Security is maintained throughout the orchestration chain