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 name	Value
`DisplayName`	`token-with-display-name`
`RoleName`	`my_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}}

Username:

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 "-" "_"}}

Username:

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}}

Username:

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.

Learn

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