Vaultx.Auth.AliCloud (Vaultx v0.7.0)

View Source

Alibaba Cloud (AliCloud) authentication method for HashiCorp Vault.

This module implements the AliCloud authentication method for Vault, providing secure authentication using Alibaba Cloud's Resource Access Management (RAM) service with comprehensive support for role-based authentication and identity verification through signed STS GetCallerIdentity requests.

Features

  • RAM Role Authentication: Authenticate using Alibaba Cloud RAM roles
  • STS Integration: Uses Alibaba Cloud Security Token Service
  • Request Signing: Validates signed GetCallerIdentity requests
  • Identity Verification: Comprehensive identity and permission validation
  • Cross-Account Support: Works with cross-account role assumptions
  • Enterprise Ready: Production-grade security and reliability

API Compliance

Fully implements HashiCorp Vault AliCloud authentication:

Usage Examples

Basic Authentication

{:ok, auth_response} = Vaultx.Auth.AliCloud.authenticate(%{
  role: "dev-role",
  identity_request_url: "aWRlbnRpdHlfcmVxdWVzdF91cmw=",
  identity_request_headers: "aWRlbnRpdHlfcmVxdWVzdF9oZWFkZXJz"
})

Authentication with Custom Mount Path

{:ok, auth_response} = Vaultx.Auth.AliCloud.authenticate(%{
  role: "prod-role",
  identity_request_url: "aWRlbnRpdHlfcmVxdWVzdF91cmw=",
  identity_request_headers: "aWRlbnRpdHlfcmVxdWVzdF9oZWFkZXJz"
}, mount_path: "custom-alicloud")

Authentication with Additional Options

{:ok, auth_response} = Vaultx.Auth.AliCloud.authenticate(%{
  role: "my-role",
  identity_request_url: "aWRlbnRpdHlfcmVxdWVzdF91cmw=",
  identity_request_headers: "aWRlbnRpdHlfcmVxdWVzdF9oZWFkZXJz"
}, [
  mount_path: "alicloud",
  timeout: 30_000,
  retry_attempts: 3
])

Vault Configuration

Before using this authentication method, configure it in Vault:

# Enable AliCloud auth method
vault auth enable alicloud

# Create a role
vault write auth/alicloud/role/dev-role \
  arn="acs:ram::5138828231865461:role/dev-role" \
  policies="dev,default"

# Create another role with token configuration
vault write auth/alicloud/role/prod-role \
  arn="acs:ram::5138828231865461:role/prod-role" \
  token_policies="prod,default" \
  token_ttl=1h \
  token_max_ttl=4h

Authentication Process

The AliCloud authentication process involves:

  1. Request Preparation: Client prepares a signed STS GetCallerIdentity request
  2. Base64 Encoding: URL and headers are base64 encoded
  3. Vault Submission: Encoded request data is sent to Vault
  4. Signature Verification: Vault verifies the request signature
  5. Identity Validation: Vault validates the caller identity
  6. Token Issuance: Vault issues a token with appropriate policies

Security Considerations

  • Use appropriate RAM policies with minimal required permissions
  • Regularly rotate access keys and credentials
  • Monitor authentication events in Vault audit logs
  • Configure appropriate role bindings and policies
  • Use least privilege principle for policy assignments
  • Consider request replay protection mechanisms
  • Validate identity request signatures properly

Required Permissions

The authenticating RAM role/user must have the following permissions:

  • sts:GetCallerIdentity - To retrieve caller identity information
  • Appropriate permissions for the intended Vault operations

Error Handling

Common authentication errors include:

  • Invalid or expired credentials
  • Insufficient RAM permissions
  • Malformed request signatures
  • Role not found or not configured
  • Network connectivity issues