• Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.11.x (latest)
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
      • Overview
      • K/V Version 1
      • K/V Version 2
    • KMIP ENTERPRISE
    • Kubernetes
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
      • Overview
      • Setup and Usage
      • Quick Start - Root CA Setup
      • Quick Start - Intermediate CA Setup
      • Considerations
      • Rotation Primitives
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Configuration
      • Upgrading
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.11.x
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.11.0
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Automated Upgrades
    • Redundancy Zones
    • Lease Count Quotas
    • Entropy Augmentation
      • Overview
      • FIPS 140-2 Inside Vault
      • Seal Wrap for FIPS 140-2
    • Seal Wrap
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault

The Vault website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»Username Templating

Some of the secrets engines that generate dynamic users for external systems provide the ability for Vault operators to customize how usernames are generated for said external systems. This customization feature uses the Go template language. This page describes the basics of using these templates for username generation but does not go into great depth of using the templating language for more advanced usages. See the API documentation for the given secret engine to determine if it supports username templating and for more details on using it with that engine.

When customizing how usernames are generated, take care to ensure you have enough randomness to ensure uniqueness otherwise multiple calls to create the credentials may interfere with each other.

In addition to the functionality built into the Go template language, a number of additional functions are available:

»Available Functions

»String/Character Manipulation

lowercase - Lowercases the input value.
Example: {{.FieldName | lowercase}}

replace - Find/replace on the input value.
Example: {{.FieldName | replace - _}}

truncate - truncates the input value to the specified number of characters.
Example: {{.FieldName | truncate 10}}

truncate_sha256 - Truncates the input value to the specified number of characters. The last 8 characters of the new value will be replace by the first 8 characters of the SHA256 hash of the truncated characters.
Example: {{.FieldName | truncate_sha256 20}}. If FieldName is abcdefghijklmnopqrstuvwxyz, all characters after the 12th (l) are removed and SHA256 hashed (872808ffbf...1886ca6f20). The first 8 characters of the hash (872808ff) are then appended to the end of the first 12 characters from the original value: abcdefghijkl872808ff.

uppercase - Uppercases the input value.
Example: {{.FieldName | uppercase}}

»Generating Values

random - Generates a random string from lowercase letters, uppercase letters, and numbers. Must include a number indicating how many characters to generate.
Example: {{random 20}} generates 20 random characters

timestamp - The current time. Must provide a formatting string based on Go’s time package.
Example: {{timestamp "2006-01-02T15:04:05Z"}}

unix_time - The current unix timestamp (number of seconds since Jan 1 1970).
Example: {{unix_time}}

unix_time_millis - The current unix timestamp in milliseconds.
Example: {{unix_time_millis}}

uuid - Generates a random UUID.
Example: {{uuid}}

»Hashing

base64 - Base64 encodes the input value.
Example: {{.FieldName | base64}}

sha256 - SHA256 hashes the input value.
Example: {{.FieldName | sha256}}

»Examples

Each secret engine provides a different set of data to the template. Please see the associated secret engine's documentation for details on what values are provided to the template. The examples below are modeled after the Database engine's data, however the specific fields that are provided from a given engine may differ from these examples. Additionally, the time is assumed to be 2009-02-13 11:31:30PM GMT (unix timestamp: 1234567890) and random characters are the ordered english alphabet: abcdefghijklmnopqrstuvwxyz.

Note: The space between {{/}} and the values/functions are optional. For instance: {{.DisplayName}} is equivalent to {{ .DisplayName }}

Field nameValue
DisplayNametoken-with-display-name
RoleNamemy_custom_database_role

To reference either of these fields, a . must be put in front of the field name: {{.DisplayName}}. Custom functions do not include a . in front of them: {{random 20}}.

»Basic Example

Template:

{{.DisplayName}}_{{.RoleName}}
{{.DisplayName}}_{{.RoleName}}

Username:

token-with-display-name_my_custom_database_role
token-with-display-name_my_custom_database_role

This is a basic example that references the two fields that are provided to the template. In simplest terms, this is a simple string substitution.

This example does not have any randomness and should not be used when generating dynamic usernames. The purpose is to demonstrate referencing data within the Go template language.

»Custom Functions

Template:

FOO_{{.DisplayName | replace "-" "_" | uppercase}}_{{.RoleName | replace "-" "_" | uppercase}}_{{timestamp "2006_01_02T15_04_05Z" | replace "-" "_"}}
FOO_{{.DisplayName | replace "-" "_" | uppercase}}_{{.RoleName | replace "-" "_" | uppercase}}_{{timestamp "2006_01_02T15_04_05Z" | replace "-" "_"}}

Username:

FOO_TOKEN_WITH_DISPLAY_NAME_MY_CUSTOM_DATABASE_ROLE_2009_02_13T11_31_30Z_0700
FOO_TOKEN_WITH_DISPLAY_NAME_MY_CUSTOM_DATABASE_ROLE_2009_02_13T11_31_30Z_0700

{{.DisplayName | replace "-" "_" | uppercase}} - Replaces all dashes with underscores and then uppercases the display name.
{{.RoleName | replace "-" "_" | uppercase}} - Replaces all dashes with underscores and then uppercases the role name.
{{timestamp "2006_01_02T15_04_05Z" | replace "-" "_"}} - Generates the current timestamp using the provided format and replaces all dashes with underscores.

»Truncating to Maximum Length

Template:

{{printf "v_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 45}}
{{printf "v_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 45}}

Username:

v_token-wi_my_custo_abcdefghijklmnopqrst_1234
v_token-wi_my_custo_abcdefghijklmnopqrst_1234

.DisplayName | truncate 8 truncates the display name to 8 characters (token-wi).
.RoleName | truncate 8 truncates the role name to 8 characters (my_custo).
random 20 generates 20 random characters abcdefghijklmnopqrst.
unix_time generates the current timestamp as the number of seconds since January 1, 1970 (1234567890).

Each of these values are passed to printf "v_%s_%s_%s_%s" which prepends them with v_ and puts an underscore between each field. This results in v_token-wi_my_custo_abcdefghijklmnopqrst_1234567890. This value is then passed to truncate 45 where the last 6 characters are removed which results in v_token-wi_my_custo_abcdefghijklmnopqrst_1234.

»Tutorial

Refer to the following tutorials for step-by-step instructions.

  • Database Secrets Engine with MongoDB
  • Dynamic Secrets: Database Secrets Engine
github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager