External secrets overview

Gateway 5.5+

Itential Gateway can retrieve credentials directly from external secrets managers at runtime. Instead of storing credentials in the gateway, you configure a secret provider that connects to your secrets manager and create secret aliases that give each secret a stable name in your automation.

How it works

A secret provider stores the connection and authentication settings for your external secrets manager. A secret alias maps a name you choose to a specific secret path within that provider.

Your automation references the alias name. If you change secrets managers or move a secret to a new path, you update the alias. Nothing else in your automation changes.

Reference syntax

Use the following syntax to reference a secret alias in your automation:

$gateway_secret_(alias-name)

Example: Reference a database password stored in Vault:

postgresql://user:$gateway_secret_(db-password)@db.example.com/myapp

Supported providers

Provider	Authentication method
HashiCorp Vault (KV Secrets Engine v2), token auth	Static token file on the gateway server
HashiCorp Vault (KV Secrets Engine v2), AppRole auth	Role ID and secret ID files with automatic token refresh
CyberArk Central Credential Provider (CCP)	Mutual TLS with certificate and private key files
Custom plugin	Any external source; you supply the retrieval logic

Where you can use secrets

You can use secret aliases in two ways depending on how your automation runs.

Running automation directly on Gateway — Use $gateway_secret_(alias-name) anywhere the gateway accepts a secret:

Context	How to reference
Code on Canvas	Add `$gateway_secret_(alias)` inline; the gateway retrieves the secret when the canvas runs
Task decorators	Pass the alias name as the secret value; the gateway injects it as an environment variable at execution time

Running automation from Itential Platform — When Platform initiates automation on a connected gateway, Platform can send a $GATEWAYSECRET_(alias-name) variable instead of a resolved credential. The gateway retrieves the credential locally from its configured provider and uses it for the task. The credential is never sent back to Platform.

This lets you use an on-premises secrets manager with a SaaS Platform deployment without requiring a VPN connection between Platform and your secrets manager.

Context	How to reference
Inventory Manager device credentials	Set the credential to `$GATEWAYSECRET_(alias-name)`; the gateway resolves it each time a workflow runs against the device
Gateway-executed integrations	Include `$GATEWAYSECRET_(alias-name)` in the integration payload; the gateway resolves it before executing
Built-in gateway services	Device broker, send config, and send command support `$GATEWAYSECRET_(alias-name)` credentials

External secrets configuration is available via the iagctl CLI or via Gateway database import/export. Gateway Manager UI-based configuration will be available in a future release.

Logging

Gateway logs the alias name, provider name, and success or failure for each secret retrieval. Secret values are never written to logs.