# Secrets management for connection credentials

FEATURE AVAILABILITY

External secrets management is included in specific pricing plans for direct customers and is available to Embedded partners and their end customers for an additional fee. Refer to your pricing plan and contract to learn more.

To simplify the management of your connection credentials, you can use an external secrets manager to securely store and retrieve sensitive information like passwords and API tokens.

The External secrets management feature in Workato lets you use secrets in place of hardcoded connection credentials. Centralizing credential management can help you adopt security best practices, like password rotation, without manually updating credentials wherever they're in use.

In this guide, we discuss these topics:

How secrets management works
The secrets managers that Workato supports
Using secrets to configure connections
Workspace vs. Project level secrets management

# How secret management works

With a secrets manager, you can use a secret instead of directly entering information into Workato. Secrets contain sensitive info like a password.

When you set up a connection, you need to manually retrieve and enter your credentials. Any time those credentials change - for example, when you reset your password - you'll need to update the password in every application that uses it.

However, if you use an external secrets manager instead, you'll only need to update the password in the secrets manager and refresh the connection in Workato. Applications using the reference will retrieve the secret's updated value, thus minimizing manual work, interruptions, and most importantly, security risk.

REFRESH THE CONNECTION IN WORKATO

Refresh the connection by sending a request to the Workato API to clear the secrets management cache. This updates the connection with the latest credentials in your secrets manager. You do not need to disconnect and reconnect the connection.

At a high level, here's how using a secrets manager works with Workato for connection credential management:

You create a vault and secret in your external secrets manager. The secrets manager encrypts the credentials.

You grant Workato access to the secrets manager.

In Workato, you configure connections using the secrets instead of credentials.

The following image demonstrates a Jira connection configured with a secret from Amazon Web Services (AWS) Secrets Manager:

Jira connection in Workato configured with an AWS secret

When Workato uses the connection, it performs the following tasks, in order:

Request secret: Workato requests the secret from the secrets manager.
Retrieve and decrypt: The secrets manager retrieves the secret and returns the decrypted secret value to Workato.
Authentication: Workato uses the decrypted value to authenticate to the application.
Access: If authentication is successful, the application grants access to Workato.

# Supported secrets managers

Workato's feature currently supports the following secrets managers:

# Using secrets to configure connections

How secrets are used in Workato connections depends on the type of secrets manager you're using. Refer to the guide for your secrets manager for more information:

# Workspace vs. Project secrets management

Typically, we configure secrets management for the entire workspace. If your organization requires more granular access control, you can configure it at the level of the individual projects. This enables you to specify the secrets inside the project, so that the connections in the projects can assume the role specified in the project settings.

For example, if your organization is configuring an S3 connection only for the use in your DevOps project, you can create a project-specific IAM role that has access to your S3 connection credentials. This replaces the generic IAM role that can be used by multiple projects.

NOTE

In Workato, secrets management can be used EITHER at the level of the Workspace, or at the level of Projects. We do not support a blended approach. For example, if you implement project-level secrets management for the DevOps project, you must change your secrets management protocol to project-level for ALL projects in the workspace.

# Formatting secrets

Certain types of secrets must be formatted correctly to be used in Workato. When adding secrets to your secrets manager, ensure you use the correct format.

# X.509 certificate

See the following X.509 certificate for an example of how to format an X.509 certificate in your secrets manager:

-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BA\nQEFAASCBKcwggSjAg\nxxxxxxxxxxxxxx\n-----END PRIVATE KEY-----\n

# Troubleshooting secrets manager connections

If you have configured a connection to use a secrets manager but the connection returns a Permission denied error, complete the following steps to troubleshoot the connection:

Check credential validity
Test retrieving secrets with provider API

# Check validity of credentials

Complete the following steps to check whether the credentials used to connect to your secrets manager are valid:

AWS SECRETS MANAGER

Navigate to IAM > Roles and select the IAM role you assigned to Workato's Secrets Management feature.

Select the Permissions tab.

Ensure that the IAM policy attached to the role has the following permissions:

ListSecrets
GetSecretValue

HASHICORP VAULT

Use the HashiCorp Vault CLI (opens new window) to run the following command (opens new window) to check the ACL policy attached to the AppRole (opens new window). Substitute your own values for {approle-name} and {role-name}:

vault read auth/{approle-name}/role/{role-name}

For example:

vault read auth/workato_approle/role/workato

The CLI output includes the name of the token policy attached to the AppRole.

Navigate to ACL Policies and select the policy name that the HashiCorp Vault CLI returned.

Ensure that the selected policy has the read and list capabilities for the appropriate secrets engine stored in your vault cluster.

Select the secrets engine in the Vault UI and navigate to the Configuration tab.

Ensure that the engine Path matches the path in the CLI output.

AZURE KEY VAULT

Navigate to Key Vault > Access control (IAM) > Role assignments.

Ensure that the Service Principal you generated the clientSecret for holds the Key Vault Secrets User role.

Navigate to Microsoft Entra ID > App Registrations and select the app that you assigned the Key Vault Secrets User role to.

Navigate to Certificates & Secrets and ensure that the secret used in your Azure Key Vault connection is not expired.

# Test retrieving secrets with provider API

If the permissions you checked in Step 1 are still valid, use an API client such as Postman or curl to make an API call to your secrets manager to retrieve any secret. This should offer more insight about why your secrets manager connection is failing.

To make an API call to your secrets manager, refer to the following documentation:

Last updated: 3/26/2025, 2:43:27 PM