External key vault naming conventions
- Updated: 2024/10/14
External key vault naming conventions
Specific authentication credentials and external key vaults have restrictions on the use of certain characters in usernames, phrases, and other text. Also, there are different naming conventions to follow based on the external key vault and the credential use cases: Agent auto-login or Agent automation.
Agent auto-login naming conventions
For CyberArk, all Agent auto-login credentials are retrieved from the specified safe name and assumed to exist within the Auto-login Credential Safe. For AWS Secrets Manager, Microsoft Azure Key Vault, and HashiCorp Vault, the Agent auto-login credentials must adhere to the required naming conventions detailed on this page.
If the Control Room performs an auto-login credential retrieval but no credential exists in the Auto-login Credential Safe that matches that user name, then the auto-login will fail. For any unattended automations, all robotic or digital worker user IDs must have an auto-login credential configured for each Control Room user within the external key vault.
The Control Room retrieves auto-login credentials based on the object naming convention within the external key vault. The Control Room searches for an object where the object name (the credential name in the external key vault) matches the Control Room username for which it is performing auto-login.
The prefix autologin_ is required as part of the naming convention for auto-login credentials for all the supported external key vaults. The name of the auto-login credential in the external key vault must contain autologin_ followed by the Control Room username. In some cases, certain key vaults have restrictions on the characters that can be used in credential object names. Additionally, to support how different use cases encode credentials, Automation 360 requires that certain characters be reserved or encoded.
The following table lists examples of the object naming conventions expected in the Control Room:
| Control Room username | Expected object name format |
|---|---|
| ABCD\user123 | autologin_ABCD--user123 |
| user123@rpa.abcd.com | autologin_user123-40-rpa-2e-abcd-2e-com |
| ABCD\user123 | autologin_ABCD\user123 |
| user123@rpa.abcd.com | autologin_user123@rpa.abcd.com |
| john | autologin_john |
For auto-login credentials, keep these in mind:
- The object name in the external key vault must contain autologin_ as a prefix.
- The auto-login credential names must map to the Control Room username
(login ID) for the credential being retrieved.
Some external key vaults have usage restrictions of certain characters, such as backslash (\) and ampersand (@) in the secret name (object name), and restrictions on how special characters are interpreted within API calls. If the user ID contains special characters, then you must encode the secret name (object name) in the external key vault using ASCII code character substitutions, as listed in the following table.
| This character | Changes to this ASCII code character substitution |
|---|---|
| \ (backslash) | -- |
| - (dash) | -2d- |
| _ (underscore) | -5f- |
| @ (ampersand) | -40- |
| . (period) | -2e- |
Automation 360 allows you to configure the custom naming of secret used for auto-login into client devices, where you run the automations (bots).
You can set up credentials in your vault according to your organization's standards and naming format. Then, you can map these secret names to Control Room usernames.
When mapping external key vaults to the Control Room for auto-login, a custom naming format allows you to create specific names for the secrets used by Bot Runners. This improves usability by ensuring the names match your organization’s standards.
- You can create a naming format that suits your operational needs, departing from the default format (example: autologin_<bot-runner_username>).
- You can map each secret stored in the external key vault to its corresponding Control Room username, which is used for autologin purposes.
Defining your own secret names enhances usability by aligning with your organizational standards. See Custom secrets mapping.
Agent automation naming conventions
Agent automation credentials are credentials retrieved by the automation during runtime and used by the automation bot to authenticate with applications. Automation credentials retrieved from external key vaults are mapped in the Automation Anywhere Credential Vault using the External Key Vault option when configuring lockers and credentials.
The Automation Anywhere locker is mapped to either of the following:
- Safe Name (CyberArk)
- Secret Name Prefix (AWS, Azure, and HashiCorp)
A credential is mapped to either of the following:
- An Object Name (CyberArk)
- A Secret Name body (AWS, Azure, and HashiCorp)
To support the Automation Anywhere user-defined credentials functionality, you can create credentials using a Control Room_username postfix because these credentials are retrieved based on the user context of the running bot. If you do not create user-defined credentials, then the automation bot credential retrieval process retrieves the system credential.
External key vaults prohibit different special characters in secret names. As a result, you must encode some characters in the credential (secret) name in the external key vault based the type of external key vault (CyberArk, AWS, and Azure) you are using and its specific requirements.
HashiCorp secret naming convention
- Uppercase characters (A–Z)
- Lowercase characters (a–z)
- Numerals (0–9)
- Special characters (+=)
For other special character, the secret name should have the ASCII encoded value for the special character. For example, an underscore character (_) must be used as -5f-.
On-Premises deployments: To override the default characters encoded by the Control Room, add the following property and regex value in the keyvault.properties file located in the Automation Anywhere configuration directory. For example, use the following expression if you do not want to encode special characters:name.encoding.characters.allowed.regex.hashicorp=^[A-Za-z0-9/_+=.@-]+$.
CyberArk Password Vault automation example
The following table shows CyberArk external key vault examples using naming conventions for automation.
- The Safe Name maps to the locker for the Control Room, and the Object Name maps to the credential for the Control Room.
- The Object Name field in the Control Room maps to Account Name in CyberArk. Also, the object name should not contain any spaces. For example, if the Account Name in CyberArk is automation360-engsafe-example.com-john.smith, the Object Name field in the Control Room must be set to automation360-engsafe-example.com-john.smith.
| Automation credential example | Control Room username | Safe Name | Object in locker |
|---|---|---|---|
| System credential in locker mapped to Safe Name | None - system credential | finance | glaccess |
| User-defined credential in locker mapped to Safe Name | ABCD\RPA\user123 | finance | glaccess_ABCD--RPA--user123 |
| User-defined credential in locker mapped to Safe Name where username is encoded with ASCII mapping | ABCD\RPA.user123 | finance | glaccess_ABCD--RPA-2e-user123 |
Configure username for different Automation 360 services using the CyberArk secret response
When configuring CyberArk settings for some of the Automation 360 services such as auto-login, Lightweight Directory Access Protocol (LDAP), and service credentials, you can optionally configure the username for the Enter property set to your CyberArk username option. Usernames can be a combination of values from the secret response or string literals. The CyberArk secret response contains field values that you must enclose within dollar signs ($) to construct the username. For example, to configure the username in the format domain\username, you must enter: $domain$\$username$. The domain and username values in this expression will be replaced with the corresponding values from the secret response.
AWS Secrets Manager automation example
The following table shows AWS Secrets Manager external key vault examples using naming conventions for automation.
| Automation credential example | Control Room username | AWS Prefix | AWS Secret Body | Secret in AWS |
|---|---|---|---|---|
|
accounting_pdf System credential in locker mapped to AWS Secret Name prefix accounting |
None - system credential | accounting | accounting_pdf (system) | |
|
accounting_pdf_ABCD--user123 User-defined credential in locker mapped to AWS Secret Name prefix accounting |
ABCD\user123 | accounting | accounting_pdf_ABCD--user123 |
Azure Key Vault automation example
The following table shows Azure Key Vault external key vault examples using naming conventions for automation.
| Automation credential example | Control Room username | Azure Prefix | Azure Secret Body | Secret in Azure |
|---|---|---|---|---|
|
accounting_cv1 System credential in locker mapped to Azure Secret name prefix accounting |
None - system credential | accounting | cv1 | pdf-5f-cv1 (system) |
|
accounting_cv1_ABCD\user123 User-defined credential in locker mapped to Azure prefix |
ABCD\user123 | accounting | cv1 | pdf-5f-cv1-5f-ABCD--user123 |
When deploying Azure credentials, the Azure Key Vault character underscore (_) is a reserved character and cannot be used in credential names. You must substitute any underscore (_) usage with the ASCII code value 5f bracketed by dashes:
| This character | Changes to this ASCII code character substitution |
|---|---|
| \ (slash) | -- |
| - (dash) | -2d- |
| _ (underscore) | -5f- |
| @ (ampersand) | -40- |
| . (period) | -2e- |
HashiCorp Vault automation example
The following table shows HashiCorp Vault automation examples using external key vault naming conventions.
| Automation credential example | Control Room username | Locker prefix | Credential secret name | Secret name in HashiCorp |
|---|---|---|---|---|
|
accounting_cred01 System credential in locker mapped to HashiCorp secret name prefix accounting |
None - system credential | accounting | cred01 | accounting-5f-cred01(system) |
|
accounting_cred01_ABCD\user123 User-defined credential in locker mapped to HashiCorp prefix |
ABCD\user123 | accounting | cred01 | accounting-5f-cred01-5f-ABCD--user123 |
|
accounting_cred01_john User-defined credential in locker mapped to HashiCorp prefix Note: This example shows values without
encoding.
|
john | accounting | cred01 | accounting_cred01_john |