# Dynamic Tokens

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FR9QbF5sQ4VJap4pPeDah%2FDynamic-Tokens.jpg?alt=media&#x26;token=a12960b2-266b-4706-9ba9-c7306eb890b5" alt=""><figcaption></figcaption></figure>

## Dynamic Tokens

When using the vault integration, specific tokens are replaced by the corresponding value from a Keeper record.

There are dynamic and static tokens. **Dynamic tokens** will search the Keeper vault for a matching record to extract the necessary secret fields. **Static tokens** can also be created that explicitly reference a particular Keeper record and field.

### Hostname Matching

Keeper Records can be assigned to connections by the "Hostname" field in the connection and the "Hostname or IP Address" field in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with values from the record, such as Username, Password, Domain, etc...

![Example of Linux Connection Matching](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FOnMCzIG3a2eEEV1aROua%2Fconnection%20hostname%20ssh%20record%20compare.png?alt=media\&token=c3022205-91fb-4bcf-9f9f-fb994af1936f)

![SSH Connection with Secrets Manager Integration](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FHNH3zPmSpy7p0RHWBXQX%2FScreen%20Shot%202022-01-29%20at%202.51.47%20PM.png?alt=media\&token=efb4315b-b017-40bc-88db-8f06f26e67f5)

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2Ffq3HqCcn5l6bfnSxRSMF%2FScreen%20Shot%202022-08-23%20at%202.38.58%20PM.png?alt=media&#x26;token=d1dda84e-64db-4e98-9e9b-019b9581d5a5" alt=""><figcaption><p>Example of Windows Login</p></figcaption></figure>

### **User Matching**

Keeper Records can be assigned to connections by the "Username" field in the connection and the "Login" field in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with secrets from the record.

As one example, this is useful for mapping a single SSH key to multiple servers. This way, you don't need to store one record per host in the vault. A single Keeper vault record can be used to authenticate any number of connections. Below is a Connection that is set up to match on Username.

![Example Connection with User Matching](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2F98oZN7CdH71ARW2wquNR%2FScreen%20Shot%202022-04-26%20at%206.26.41%20AM.png?alt=media\&token=3e9fa016-23f5-43e8-97d0-bda52047e564)

The corresponding vault record is seen below. No hostname is specified in the vault record, so the match will occur based on the login field.

![Vault Record match on User](https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2F1XykLW5S9X2UDcoM3dmu%2FScreen%20Shot%202022-04-26%20at%206.29.10%20AM.png?alt=media\&token=43c15c75-8189-4bb3-9861-26853ab0d920)

{% hint style="info" %}
For user-based matching, ensure that the Keeper record does not have a Hostname/Port. It should simply contain the username and password (or private key).
{% endhint %}

### **Domain Matching**

Keeper Records can be retrieved for connections by matching on the "Domain" field in the connection and a custom field called "Domain" in the vault record.

If these two values match, Connection Manager will fetch and replace tokens in other connection fields with values from the record, such as Username, Password, etc...

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FCPvsDwabCLmBf8oDyol3%2FScreenshot%202023-04-10%20at%205.01.46%20PM.jpg?alt=media&#x26;token=f18b5315-5eca-40a6-b50f-b5224e2d3cc0" alt=""><figcaption><p>Domain Matching</p></figcaption></figure>

If you would prefer to store the Domain as part of the username field (e.g. LUREY\Administrator), this can be activated by turning on the `KSM_STRIP_WINDOWS_DOMAINS` flag to "True" in the Docker container environmental variables for the [keeper/guacamole](https://docs.keeper.io/en/keeper-connection-manager/installation/docker-compose-install/keeper-guacamole#id-.glyptodon-guacamolev2.x-environmentvariables) image.

As another example, if you are using SSH to a Linux machine with Active Directory credentials in the format of `username@domain`, you can store this value in the Login field.

### Support for Linked Records

The Keeper Secrets Manager integration is now capable of reading secrets that involve linked records, specifically the “admin” and “launch” credentials that may be associated with a KeeperPAM record in the Vault. Similar to the established `${KEEPER_SERVER_*}` and `${KEEPER_GATEWAY_*}` tokens, the additional dynamic tokens are now available that pull secrets from linked records.

### **Available Tokens**

The built-in tokens each correspond to a record field. The table below lists each token and its corresponding record field. These tokens are applicable to all connection types.

| **Parameter Token**            | **Description**                                                                                                                                                                                                                              |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `${KEEPER_SERVER_USERNAME}`    | <p><strong>Retrieves:</strong> “Login” field of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “hostname” connection parameter</p>                                        |
| `${KEEPER_SERVER_KEY}`         | <p><strong>Retrieves:</strong> “Private Key” field (or single .pem file attachment) of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “hostname” connection parameter</p> |
| `${KEEPER_SERVER_PASSPHRASE}`  | <p><strong>Retrieves:</strong> “Passphrase” field (or “password” if no passphrase) of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “hostname” connection parameter</p>  |
| `${KEEPER_SERVER_PASSWORD}`    | <p><strong>Retrieves:</strong> “Password” field of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “hostname” connection parameter</p>                                     |
| `${KEEPER_SERVER_DOMAIN}`      | <p><strong>Retrieves:</strong> “Domain” custom field of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “hostname” connection parameter</p>                                |
| `${KEEPER_SERVER_TOTP_SECRET}` | **Retrieves:** The TOTP secret associated with the record.                                                                                                                                                                                   |
| `${KEEPER_USER_KEY}`           | <p><strong>Retrieves:</strong> “Private Key” field (or single .pem file attachment) of single matched record</p><p><strong>Matches:</strong> Record with login matching the “username” connection parameter</p>                              |
| `${KEEPER_USER_PASSPHRASE}`    | <p><strong>Retrieves:</strong> “Passphrase” field (or “password” if no passphrase) of single matched record</p><p><strong>Matches:</strong> Record with login matching the “username” connection parameter</p>                               |
| `${KEEPER_USER_PASSWORD}`      | <p><strong>Retrieves:</strong> “Password” field of single matched record</p><p><strong>Matches:</strong> Record with login matching the “username” connection parameter</p>                                                                  |
| `${KEEPER_USER_DOMAIN}`        | <p><strong>Retrieves:</strong> “Domain” custom field of single matched record</p><p><strong>Matches:</strong> Record with login matching the “username” connection parameter</p>                                                             |
| `${KEEPER_USER_TOTP_SECRET}`   | <p><strong>Retrieves:</strong> The TOTP secret associated with the record.</p><p><strong>Matches:</strong> Record with login matching the "username" connection parameter.</p>                                                               |
| `${KEEPER_DOMAIN_USERNAME}`    | <p><strong>Retrieves:</strong> “Login” field of single matched record</p><p><strong>Matches:</strong> Record with custom "Domain" field matching the value of the “domain” connection parameter</p>                                          |
| `${KEEPER_DOMAIN_PASSWORD}`    | <p><strong>Retrieves:</strong> “Password” field of single matched record</p><p><strong>Matches:</strong> Record with login matching the “domain” connection parameter</p>                                                                    |
| `${KEEPER_SERVER_ADMIN_*}`     | The requested **admin** credentials (ie: `${KEEPER_SERVER_ADMIN_PASSWORD}`) that are linked to the Keeper record matching the remote desktop server’s hostname (exactly as `${KEEPER_SERVER_*}` would match).                                |
| `${KEEPER_SERVER_LAUNCH_*}`    | The requested **launch** credentials (ie: `${KEEPER_SERVER_LAUNCH_PASSWORD}`) that are linked to the Keeper record matching the remote desktop server’s hostname (exactly as `${KEEPER_SERVER_*}` would match).                              |

#### Gateway Tokens <a href="#gateway-based-dynamic-secrets" id="gateway-based-dynamic-secrets"></a>

The tokens below are applicable only to connection types that have gateway support (RDP).

| **Parameter Token**                 | **Description**                                                                                                                                                                                                                                                                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `${KEEPER_GATEWAY_USERNAME}`        | <p><strong>Retrieves:</strong> “Login” field of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “gateway-hostname” connection parameter.</p>                                                                                                               |
| `${KEEPER_GATEWAY_KEY}`             | <p><strong>Retrieves:</strong> “Private Key” field (or single .pem file attachment) of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “gateway-hostname” connection parameter.</p>                                                                        |
| `${KEEPER_GATEWAY_PASSPHRASE}`      | <p><strong>Retrieves:</strong> “Passphrase” field (or “password” if no passphrase) of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “gateway-hostname” connection parameter.</p>                                                                         |
| `${KEEPER_GATEWAY_PASSWORD}`        | <p><strong>Retrieves:</strong> “Password” field of single matched record</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “gateway-hostname” connection parameter.</p>                                                                                                            |
| `${KEEPER_GATEWAY_USER_KEY}`        | <p><strong>Retrieves:</strong> “Private Key” field (or single .pem file attachment) of single matched record</p><p><strong>Matches:</strong> Record with login matching the “gateway-username” connection parameter.</p>                                                                                                     |
| `${KEEPER_GATEWAY_USER_PASSPHRASE}` | <p><strong>Retrieves:</strong> “Passphrase” field (or “password” if no passphrase) of single matched record</p><p><strong>Matches:</strong> Record with login matching the “gateway-username” connection parameter</p>                                                                                                       |
| `${KEEPER_GATEWAY_USER_PASSWORD}`   | <p><strong>Retrieves:</strong> “Password” field of single matched record</p><p><strong>Matches:</strong> Record with login matching the “gateway-username” connection parameter</p>                                                                                                                                          |
| `${KEEPER_GATEWAY_ADMIN_*}`         | The requested **admin** credentials (ie: `${KEEPER_GATEWAY_ADMIN_PASSWORD}`) that are linked to the Keeper record matching the remote desktop server’s “gateway-hostname” parameter (exactly as `${KEEPER_GATEWAY_*}` would match). This is specific to use of the Microsoft RD Gateway and applies only to RDP connections. |
| `${KEEPER_GATEWAY_LAUNCH_*}`        | The requested admin credentials (ie: ${KEEPER\_GATEWAY\_LAUNCH\_PASSWORD}) that are linked to the Keeper record matching the remote desktop server’s “gateway-hostname” parameter (exactly as ${KEEPER\_GATEWAY\_\*} would match). This is specific to use of the Microsoft RD Gateway and applies only to RDP connections.  |

The following tokens are technically also defined, but do not currently have any practical use (there is no TOTP code generation needed for RDP):

<table data-header-hidden><thead><tr><th width="395"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Token</strong></td><td><strong>Description</strong></td></tr><tr><td><code>${KEEPER_GATEWAY_TOTP_SECRET}</code></td><td><p><strong>Retrieves:</strong> The TOTP secret associated with the record.</p><p><strong>Matches:</strong> Record with hostname / IP address matching the value of the “gateway-hostname” connection parameter.</p></td></tr><tr><td><code>${KEEPER_GATEWAY_USER_TOTP_SECRET}</code></td><td><p><strong>Retrieves:</strong> The TOTP secret associated with the record.</p><p><strong>Matches:</strong> Record with login matching the “gateway-username” connection parameter.</p></td></tr></tbody></table>

### Active Directory Username/Domain Parsing

KCM will identify the Domain, Username and Password fields from the Keeper Vault record, as long as there is a field with the corresponding name. For example:

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FeZZlJxZJjSDWdc8whxRO%2FScreen%20Shot%202022-08-23%20at%202.46.22%20PM.png?alt=media&#x26;token=4e299550-eefc-4d33-abb1-d485a3952d1b" alt=""><figcaption><p>Domain Matching on Custom Field</p></figcaption></figure>

### Automatic Parsing of Domain from Login Field

The Active Directory "Domain" and "Username" field can be parsed if the Login value in the Keeper Vault is supplied in the format of `DOMAIN\Username` or `Username@Domain`.

To activate automatic parsing, the environmental variable `KSM_STRIP_WINDOWS_DOMAINS` must be added to the Docker Config file. This allows matching to work if the username is combined with the domain.

Another property called `KSM_MATCH_DOMAINS_FOR_USERS` will force matching to occur only if both the username and domain match exactly.

For example:

{% code title="docker-compose.yml" %}

```
            ....
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            KSM_CONFIG: "XXX"
            ....
            ....
            KSM_STRIP_WINDOWS_DOMAINS: "true"
            KSM_MATCH_DOMAINS_FOR_USERS: "true"
            ....

```

{% endcode %}

In the record, the Login field can then contain

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FramB5SZrDhOPrx32fE43%2FScreen%20Shot%202022-08-23%20at%202.50.59%20PM.png?alt=media&#x26;token=57703b19-0de9-4914-bbce-a946ac46714c" alt=""><figcaption><p>Automatic Parsing of Domain from Login Field</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/en/keeper-connection-manager/vault-integration/dynamic-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.