Configure Vault Agent Authentication for HashiCorp Vault¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Available on the Deluxe, Enterprise, and Enterprise+ plans only for Alation Cloud Service

Applies from version 2026.4.1.0

Overview¶

The Vault Agent authentication type lets Alation delegate authentication to the HashiCorp Vault Agent when connecting to your HashiCorp Vault. With this authentication type, you authenticate with Vault using AWS-based credentials and do not need to store long-lived Vault credentials (such as LDAP passwords or AppRole secret IDs) in Alation.

Important

Vault Agent authentication is available only on Alation Cloud Service and only when you connect to your data source through an Alation Agent. It is not supported on customer-managed Alation deployments, and it is not available for authentication configurations created directly for Alation Cloud Service (without an Alation Agent).

Alation supports only AWS IAM and AWS EC2 auth methods with Vault Agent. HashiCorp Vault Agent itself supports additional auth methods (for example, Kubernetes, TLS certificates, OIDC, and AppRole), but those methods are not supported by Alation and will not work if you paste the corresponding JSON into the Alation UI. Choose AWS IAM or AWS EC2 auth to proceed.

This topic covers how to configure Vault Agent authentication using AWS IAM or AWS EC2 through an Alation Agent.

How Vault Agent Authentication Works¶

In the Alation UI, you provide the Vault auto_auth method configuration as JSON. You include only the method block — the type, mount_path, and config fields. The Authentication Service assembles the complete Vault Agent configuration (including the Vault address, namespace, token sink, and exit settings) automatically.

When Alation needs to read a secret from your Vault:

The Authentication Service on the Alation Agent spawns a short-lived Vault Agent process using the assembled configuration.
Vault Agent authenticates with your Vault using the method you configured and writes a token to a temporary location on the Agent host.
The Authentication Service reads the token, verifies it with Vault, and caches it in memory for the duration of the token’s time-to-live.
Subsequent secret reads within the token’s lifetime use the cached token. When the cached token expires, the Authentication Service spawns Vault Agent again to obtain a fresh token.

No long-running Vault Agent processes are required. No Vault credentials are stored in Alation.

Prepare the Method JSON from HCL¶

HashiCorp’s official documentation and examples for Vault Agent typically show the auto_auth method block in HCL format. The Alation UI accepts the same method block in JSON format. The following rules map HCL to JSON:

HCL concept	JSON equivalent	Notes
Block label: `method "aws" { ... }`	`"type"` field: `"type": "aws"`	The block label becomes the value of the `type` property.
Attribute: `mount_path = "auth/aws"`	Property: `"mount_path": "auth/aws"`	Direct key-value mapping.
Nested block: `config = { ... }`	Nested object: `"config": { ... }`	Curly braces become JSON objects.
String value: `"iam"`	String value: `"iam"`	Identical.
Boolean value: `true`	Boolean value: `true`	Identical.

For example, here is the same AWS IAM method block in each format:

HCL (for reference):

method "aws" {
  mount_path = "auth/aws"
  config = {
    type         = "iam"
    role         = "alation-agent-role"
    header_value = "vault.example.com"
  }
}

JSON (paste this in the Alation UI):

{
  "type": "aws",
  "mount_path": "auth/aws",
  "config": {
    "type": "iam",
    "role": "alation-agent-role",
    "header_value": "vault.example.com"
  }
}

AWS IAM Auth vs AWS EC2 Auth¶

If you plan to use an AWS-based Vault auth method, choose between AWS IAM and AWS EC2 based on your deployment:

Aspect	AWS IAM Auth	AWS EC2 Auth
Identity source	Signed `sts:GetCallerIdentity` request using the caller’s IAM role or user credentials	PKCS7-signed EC2 instance identity document
Works from an Alation Agent on Amazon EC2	Yes. The Agent’s attached IAM role authenticates with your Vault.	Yes. The Agent’s EC2 instance identity authenticates with your Vault.
Works from an Alation Agent not on Amazon EC2	Yes, if AWS access keys are available on the Agent host.	No. EC2 auth requires an EC2 instance identity document.
Re-authentication	Stateless — no nonce needed.	Uses a nonce that Alation manages automatically across Vault Agent spawns.
Binding granularity	IAM principal ARN	EC2 instance attributes (AMI, VPC, subnet, account, region, instance profile, and so on)

HashiCorp recommends AWS IAM auth as the preferred approach. It is more flexible, covers a broader range of AWS identities (IAM roles, IAM users, Lambda functions, and cross-account roles), and aligns with AWS best practices for access control. Use AWS EC2 auth only when you need EC2 instance-attribute binding (AMI, VPC, subnet, and so on). For details, see the HashiCorp Vault AWS auth method documentation.

Workflow¶

Prerequisites
Step 1: Configure the AWS Auth Method in HashiCorp Vault
Step 2: Prepare the Alation Agent’s AWS Identity
Step 3: Install the Authentication Service Add-on on the Alation Agent
Step 4: Prepare the Vault Agent Method JSON

If you do not have access to the Vault CLI, see API-Based Setup for Vault Agent Authentication (Without Vault CLI) for equivalent curl commands that cover Step 1.

Prerequisites¶

You must be on Alation Cloud Service version 2026.4.1.0 or later.
You must connect to your data source through an Alation Agent. Vault Agent authentication is not available for authentication configurations created directly for Alation Cloud Service.
Use the latest available version of the Alation Agent.
You must install Authentication Service Add-on version 5.14.0.2519 or later on the Alation Agent.

You must have the Server Admin role to set up the integration in Alation.
You must have admin access to your HashiCorp Vault server and permissions to enable auth methods, create policies, and create roles.
If you plan to use AWS EC2 auth, the Alation Agent must be installed on an Amazon EC2 instance.
If you plan to use AWS IAM auth with an instance role, the Alation Agent must be installed on an Amazon EC2 instance with an IAM role attached.

Step 1: Configure the AWS Auth Method in HashiCorp Vault¶

This step is performed on the HashiCorp Vault server by a Vault admin

Configure Vault to accept AWS-based authentication from the Alation Agent. The subsections below use the Vault CLI. If you do not have CLI access, see API-Based Setup for Vault Agent Authentication (Without Vault CLI) for equivalent curl commands.

Enable the AWS Auth Method¶

If the AWS auth method is not already enabled on your Vault, enable it:

vault auth enable aws

Both AWS IAM and AWS EC2 auth types share the same aws/ auth mount, so you only need to enable the method once.

Verify that the AWS auth method is enabled:

vault auth list

You should see aws/ in the output.

Configure the AWS Client for Vault¶

Vault verifies incoming auth requests against AWS. Configure the AWS client for Vault based on how your Vault server is deployed.

If Vault runs on an AWS compute service (Amazon EC2, Amazon ECS, or Amazon EKS) with an IAM role attached, Vault can use the instance profile automatically. Configure the optional replay-attack protection header:

vault write auth/aws/config/client \
  iam_server_id_header_value="vault.example.com"

If Vault runs outside AWS or needs explicit AWS credentials, provide an access key and secret key:

vault write auth/aws/config/client \
  access_key="<AWS_ACCESS_KEY>" \
  secret_key="<AWS_SECRET_KEY>" \
  iam_server_id_header_value="vault.example.com"

Note

Save the value of iam_server_id_header_value for future reference. If you configure it here, you must specify it as header_value in the JSON configuration you provide in the Alation UI in Step 4.

The IAM role attached to the Vault server (or the AWS credentials you configure) must include specific AWS permissions depending on the auth types you plan to use:

Permission	Required For	Purpose
`iam:GetRole`	AWS IAM auth	Lets Vault resolve IAM role ARNs for principal binding and wildcard matching.
`iam:GetUser`	AWS IAM auth, only if IAM users (not roles) authenticate	Lets Vault resolve IAM user ARNs.
`ec2:DescribeInstances`	AWS EC2 auth	Lets Vault verify the instance exists and fetch instance attributes.
`iam:GetInstanceProfile`	AWS EC2 auth	Lets Vault resolve the instance’s IAM instance profile and role ARN.

You can scope each permission’s Resource element to limit which AWS resources the Vault server can inspect. The ability to scope differs by action:

Permission	Can it be scoped?	Recommended `Resource` value and reason
`ec2:DescribeInstances`	No	Must be `"*"`. `DescribeInstances` is a list/describe action and AWS does not support resource-level permissions for it.
`iam:GetInstanceProfile`	Yes	`arn:aws:iam::<ACCOUNT_ID>:instance-profile/<ALATION_AGENT_INSTANCE_PROFILE>`, which limits Vault to inspecting only the Alation Agent’s instance profile.
`iam:GetRole`	Yes	`arn:aws:iam::<ACCOUNT_ID>:role/<ALATION_AGENT_ROLE>` for a single role, or `arn:aws:iam::<ACCOUNT_ID>:role/alation-*` if your Vault role uses wildcard matching in `bound_iam_principal_arn`.
`iam:GetUser`	Yes	`arn:aws:iam::<ACCOUNT_ID>:user/*`. Include this entry only if IAM users authenticate to Vault through this auth mount.

Using "Resource": "*" for all permissions is the simplest setup. For tighter security, apply the scoped values above.

Important

If you use wildcard patterns in bound_iam_principal_arn on the Vault role (for example, arn:aws:iam::*:role/alation-*), the iam:GetRole Resource must also use a wildcard that covers all potentially matched roles. Overly restrictive resource scoping causes AccessDenied errors during authentication.

For more details, see the HashiCorp Vault AWS auth method documentation.

Configure Cross-Account Access (Optional)¶

Skip this subsection if the Alation Agent and your HashiCorp Vault server run in the same AWS account.

If the Alation Agent’s AWS identity (the IAM role attached to the Agent’s EC2 instance) lives in a different AWS account from your Vault server, configure an STS role that Vault can assume to verify callers in that account:

vault write auth/aws/config/sts/<OTHER_AWS_ACCOUNT_ID> \
  sts_role="arn:aws:iam::<OTHER_AWS_ACCOUNT_ID>:role/vault-verify-role"

Replace <OTHER_AWS_ACCOUNT_ID> with the AWS account ID where the Alation Agent runs. Replace vault-verify-role with the name of an IAM role in that account that Vault is allowed to assume.

When you create the Vault role in the next subsection, the bound_iam_principal_arn value is the Alation Agent’s IAM role ARN in its own AWS account, regardless of where your Vault server runs.

For details, see the cross-account authentication section of the HashiCorp Vault AWS auth method documentation.

Create a Vault Policy (Optional)¶

Skip this subsection if you already have a Vault policy that grants read access to the secrets Alation needs. You can reuse an existing policy when you create the Vault role in the next subsection.

If you do not have a suitable policy, create one. For example, save the following policy definition as alation-agent-policy.hcl:

# Read application secrets
path "secret/data/alation/*" {
  capabilities = ["read", "list"]
}

# Read database credentials from a database secrets engine
path "database/creds/alation" {
  capabilities = ["read"]
}

Apply the policy:

vault policy write alation-agent-policy alation-agent-policy.hcl

Adjust the paths to match the secrets engines and secret locations you want Alation to read from.

Create a Vault Role¶

Create a Vault role that maps the Alation Agent’s AWS identity to one or more Vault policies. The role name you pass to auth/aws/role/ in this command is the same value you specify as role in the JSON configuration in Step 4.

For AWS IAM auth:

vault write auth/aws/role/alation-agent-role \
  auth_type=iam \
  bound_iam_principal_arn="arn:aws:iam::<CUSTOMER_AWS_ACCOUNT_ID>:role/<ALATION_AGENT_IAM_ROLE>" \
  policies=alation-agent-policy \
  token_ttl=1h \
  token_max_ttl=4h

Replace <CUSTOMER_AWS_ACCOUNT_ID> with your AWS account ID and <ALATION_AGENT_IAM_ROLE> with the name of the IAM role attached to the Alation Agent’s EC2 instance.

For AWS EC2 auth:

vault write auth/aws/role/alation-agent-ec2-role \
  auth_type=ec2 \
  bound_account_id="<CUSTOMER_AWS_ACCOUNT_ID>" \
  bound_vpc_id="<VPC_ID>" \
  bound_iam_instance_profile_arn="arn:aws:iam::<CUSTOMER_AWS_ACCOUNT_ID>:instance-profile/<ALATION_AGENT_INSTANCE_PROFILE>" \
  policies=alation-agent-policy \
  token_ttl=1h \
  token_max_ttl=4h

Replace the placeholder values with your AWS account ID, the VPC ID where the Alation Agent runs, and the name of the Agent EC2 instance’s IAM instance profile.

Note

Replace policies=alation-agent-policy with the name of the policy (or comma-separated policies) that grants access to the secrets Alation needs to read. Use the policy you created in the previous subsection, or any existing policy of your choice.

Important

None of the bound_* parameters are required by Vault. However, a role with no bindings allows any AWS principal that can reach your Vault to authenticate and obtain a token. Configure at least bound_account_id, bound_vpc_id, and bound_iam_instance_profile_arn (for EC2 auth) or bound_iam_principal_arn (for IAM auth) to scope authentication to the Alation Agent.

Note

Choose token_ttl and token_max_ttl values appropriate for your environment. Alation caches each obtained token in memory for the duration of the token’s time-to-live, minus a two-minute buffer. When the cached token expires, Alation respawns Vault Agent to obtain a fresh token. Very short token TTLs (for example, under five minutes) increase the frequency of Vault Agent spawns and auth requests to your Vault server.

For additional role parameters, such as bound_ami_id, bound_region, and bound_ec2_instance_id, see the HashiCorp Vault AWS auth method API reference.

Verify the Role¶

Verify the Vault role is configured correctly. Replace <ROLE_NAME> with the role name you used when you created the role — for example, alation-agent-role (AWS IAM auth) or alation-agent-ec2-role (AWS EC2 auth):

vault read auth/aws/role/<ROLE_NAME>

Step 2: Prepare the Alation Agent’s AWS Identity¶

This step is performed on the Amazon EC2 instance where the Alation Agent is installed

The Alation Agent’s EC2 instance must have an AWS identity that matches the Vault role’s bound_* parameters.

AWS IAM Auth¶

Attach an IAM role to the Alation Agent’s EC2 instance. The ARN of this role must match the bound_iam_principal_arn value you configured in the Vault role.

For information about attaching an IAM role to an EC2 instance, see IAM roles for Amazon EC2 in the AWS documentation.

Verify the attached IAM role from the Alation Agent host:

TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/info

The output includes the attached IAM role ARN.

AWS EC2 Auth¶

The Alation Agent’s EC2 instance must have attributes that match the bound_* parameters configured in the Vault role. Verify the instance identity document from the Alation Agent host:

TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/document

Confirm that the instance attributes in the document (for example, accountId, region, and instanceId) match the bound_* parameters on the Vault role.

Note

For EC2 machines using IMDSv2, ensure that the hop limit has been increased to 2, as recommended by AWS.

Step 3: Install the Authentication Service Add-on on the Alation Agent¶

This step is performed in Alation or on the Alation Agent machine

Install or upgrade the Authentication Service add-on to version 5.14.0.2519 or later on the Alation Agent. The Vault Agent binary is bundled with this version of the add-on.

See Install the Authentication Service Add-on for help installing the Authentication Service add-on.

Step 4: Prepare the Vault Agent Method JSON¶

Use the following JSON as the value of the Vault Agent Auth Method (JSON) field when you reach Step 4: Create an Authentication Profile on the Integrate with HashiCorp Vault page. The field appears after you select Vault Agent under Authentication Type.

Include only the method block — the type, mount_path, and config fields — based on the Vault role you created in Step 1.

For AWS IAM auth:

{
  "type": "aws",
  "mount_path": "auth/aws",
  "config": {
    "type": "iam",
    "role": "alation-agent-role",
    "header_value": "vault.example.com"
  }
}

For AWS EC2 auth:

{
  "type": "aws",
  "mount_path": "auth/aws",
  "config": {
    "type": "ec2",
    "role": "alation-agent-ec2-role"
  }
}

The role value must match the name of the Vault role you created in Step 1. The header_value value (for AWS IAM auth) must match the iam_server_id_header_value you configured on the Vault server in Step 1.

Note

Alation assembles the full Vault Agent configuration automatically, including the Vault address, namespace, token sink, and exit settings. Do not include the following fields in your JSON:

vault block. Alation uses the Vault URL and Namespace (Optional) fields you enter on the configuration page.
sink. Alation adds the token sink automatically.
exit_after_auth and top-level exit_on_err. Alation adds these automatically.
nonce for AWS EC2 auth. Alation generates and manages the nonce automatically.

Troubleshooting¶

Logs¶

When you need to review Authentication Service logs for a Vault Agent configuration, collect the logs from the Alation Agent host. Log-path access is managed on the Alation Agent machine, not on Alation Cloud Service, so this command must be run on the Agent.

To export the current auth container logs to a file on the Agent host, run:

sudo docker logs auth > authservice.log

For symptom-based troubleshooting, see Common Errors below.

Common Errors¶

Error or symptom	Resolution
Test connection fails with a timeout	Vault Agent could not authenticate with Vault within the allowed time. Check that your Vault server is reachable from the Alation Agent host, that the Vault role exists, and that the AWS identity on the Agent matches the `bound_*` parameters on the Vault role.
`entry for role X not found`	The `role` value in the JSON does not match the name of any Vault role on the `auth/aws` mount. Verify the role name by running `vault list auth/aws/role/`.
`IAM principal not authorized` or a similar AWS auth failure	The IAM role ARN on the Alation Agent’s EC2 instance does not match the `bound_iam_principal_arn` value on the Vault role. Verify the ARN from the Agent host and update the Vault role if needed.
`header mismatch`	The `header_value` in your JSON does not match the `iam_server_id_header_value` configured on the Vault server. Update one or the other so they match.
`client nonce mismatch` (EC2 auth)	Vault’s nonce for the instance is out of sync, typically after an instance stop or restart. Clear the nonce on the Vault side by running `vault delete auth/aws/identity-accesslist/<INSTANCE_ID>`, and then retry.
`instance not found` or `DescribeInstances` error (EC2 auth)	The Vault server’s IAM role is missing the `ec2:DescribeInstances` permission. Grant the permission and retry.
Authentication succeeds for test connection but fails at runtime	The Vault policy attached to the role does not grant access to the secret path specified in Secret Path for test connection, or to the secrets Alation reads during MDE, QLI, or profiling. Review the policy and grant the required `read` and `list` capabilities.

For additional troubleshooting guidance, see the HashiCorp Vault AWS auth method documentation and the HashiCorp Vault Agent Auto-Auth documentation.

Configure Vault Agent Authentication for HashiCorp Vault¶

Overview¶

How Vault Agent Authentication Works¶

Prepare the Method JSON from HCL¶

AWS IAM Auth vs AWS EC2 Auth¶

Workflow¶

Prerequisites¶

Step 1: Configure the AWS Auth Method in HashiCorp Vault¶

Enable the AWS Auth Method¶

Configure the AWS Client for Vault¶

Configure Cross-Account Access (Optional)¶

Create a Vault Policy (Optional)¶

Create a Vault Role¶

Verify the Role¶

Step 2: Prepare the Alation Agent’s AWS Identity¶

AWS IAM Auth¶

AWS EC2 Auth¶

Step 3: Install the Authentication Service Add-on on the Alation Agent¶

Step 4: Prepare the Vault Agent Method JSON¶

Troubleshooting¶

Logs¶

Common Errors¶

Alation User Documentation PDFs