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, 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 external key vaults: CyberArk, AWS, Azure, and HashiCorp. 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
Note: For On-Premises customers using AD authentication, you must format auto-login usernames using the UPN format or domain\username postfix.

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-
Note: Except for the backslash being mapped to double dashes, the dash, period, underscore, and ampersand are mapped using their ASCII code bracketed in dashes.

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)
Note: You can map any Automation Anywhere locker to any CyberArk Safe Name. The Safe Names used to map Automation Credentials should be distinct from the Safe Name used for auto-login.

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.

Note: For On-Premises customers using AD authentication, you must format Agent automation usernames using the UPN format or domain\username postfix.

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

By default, the Control Room integration with HashiCorp allows the following characters without encoding:
  • 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.

Note:
  • The Safe Name maps to the locker for the Control Room, and the Object Name maps to the credential for the Control Room.
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.

Note: The AWS Secret Name Prefix maps to the locker for the Control Room, and the AWS Secret Body maps to the credential for the Control Room.
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 pdf accounting_pdf (system)

accounting_pdf_ABCD--user123

User-defined credential in locker mapped to AWS Secret Name prefix accounting

ABCD\user123 accounting pdf 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.

Note: The Azure Prefix maps to the locker for the Control Room, and the Azure Secret Body maps to the credential for the Control Room.
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.

Note: The HashiCorp prefix maps to the Control Room locker and the HashiCorp secret name maps to the Control Room credential.
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