159 lines
6.5 KiB
Plaintext
159 lines
6.5 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Username Templating
|
||
description: >-
|
||
Username templating are used in some secret engines to allow operators to define
|
||
how dynamic usernames are generated.
|
||
---
|
||
|
||
# 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](https://golang.org/pkg/text/template/). 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.<br/>
|
||
**Example**: `{{.FieldName | lowercase}}`
|
||
|
||
`replace` - Find/replace on the input value.<br/>
|
||
**Example**: `{{.FieldName | replace - _}}`
|
||
|
||
`truncate` - truncates the input value to the specified number of characters.<br/>
|
||
**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.<br/>
|
||
**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.<br/>
|
||
**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.<br/>
|
||
**Example**: `{{random 20}}` generates 20 random characters
|
||
|
||
`timestamp` - The current time. Must provide a formatting string based on Go’s [time package](https://golang.org/pkg/time/).<br/>
|
||
**Example**: `{{timestamp "2006-01-02T15:04:05Z"}}`
|
||
|
||
`unix_time` - The current unix timestamp (number of seconds since Jan 1 1970).<br/>
|
||
**Example**: `{{unix_time}}`
|
||
|
||
`unix_time_millis` - The current unix timestamp in milliseconds.<br/>
|
||
**Example**: `{{unix_time_millis}}`
|
||
|
||
`uuid` - Generates a random UUID.<br/>
|
||
**Example**: `{{uuid}}`
|
||
|
||
### Hashing
|
||
|
||
`base64` - Base64 encodes the input value.<br/>
|
||
**Example**: `{{.FieldName | base64}}`
|
||
|
||
`sha256` - SHA256 hashes the input value.<br/>
|
||
**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](/vault/docs/secrets/databases) 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.<br/>
|
||
`{{.RoleName | replace "-" "_" | uppercase}}` - Replaces all dashes with underscores and then uppercases the role name.<br/>
|
||
`{{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`).<br/>
|
||
`.RoleName | truncate 8` truncates the role name to 8 characters (`my_custo`).<br/>
|
||
`random 20` generates 20 random characters `abcdefghijklmnopqrst`.<br/>
|
||
`unix_time` generates the current timestamp as the number of seconds since January 1, 1970 (`1234567890`).<br/>
|
||
|
||
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](/vault/tutorials/db-credentials/database-mongodb#customize-the-generated-username-schema)
|
||
- [Dynamic Secrets: Database Secrets Engine](/vault/tutorials/db-credentials/database-secrets#define-a-username-template)
|