HashiCorp credential retrieval use cases

You can retrieve HashiCorp credentials for these use cases: bootstrap, system, auto-login, and automations.

Retrieve Control Room bootstrap credentials

Note: This use case applies to On-Premises deployments only.

The Automation 360 Control Room uses bootstrap credentials to access supporting services such as database, service account, and Active Directory (AD). You configure these credentials during the initial On-Premises installation or post-installation (using the key vault utility) by specifying the secret name.

The following image shows the process of retrieving the Control Room bootstrap credentials with HashiCorp:

HashiCorp control-room bootstrap credential retrieval

When required during the bootup sequence or normal operations (such as refreshing a service authentication), the Control Room uses the key vault connection to retrieve the credential and perform the required authentication.

Note: You must select the Microsoft SQL Server Authentication for this use case; other database authentication methods are not supported for bootstrap.

Retrieve Control Room system credentials

Note: This use case applies to On-Premises deployments only, and you can configure the service account only during the initial installation.

If you configured an external key vault during the initial installation, you can then use the Automation 360 user interface (post-installation) to configure SMTP and Active Directory (AD) credentials.

To configure SMTP:
  1. Log in to the Automation 360 Control Room as the Administrator.
  2. From the Control Room, navigate to: Administration > Settings > Email Settings.

To configure Active Directory credentials:

  1. Log in to the Automation 360 Control Room as the Administrator.
  2. From the Control Room, navigate to: Administration > Settings > Active Directory Settings.
  3. You can map the AD primary account credential from the external key vault, configure external credentials, or set to manual (switch modes of AD primary account credential retrieval).

Retrieve auto-login credentials

Note: This use case applies to both On-Premises and Cloud deployments.

Auto-login credentials are used to authenticate to an Automation 360 Bot Agent device and start an active Windows session. Robotic Process Automation (RPA) requires an active Windows session to function. Auto-login occurs prior to the automation running when automations are launched from a remote Bot Agent device.

The following image shows the process of retrieving the auto-login credentials with HashiCorp:

HashiCorp retrieve auto-login credentials

A Control Room administrator can manually launch or schedule a job to launch an automation on a Bot Agent device by specifying these details:

  • Automation (bot) name
  • Device name
  • User context

The system performs auto-login to the specified device with the user name and password associated with the user context, and then runs the automation on the device.

You must have a secret for each Control Room user for whom the auto-login credentials will be retrieved from the external key vault, and the secret name in the HashiCorp vault must match the Control Room username.

To configure retrieval of auto-login credentials from the external key vault, perform these steps:

  1. Log in to the Automation 360 Control Room as the Administrator.
  2. From the Control Room, navigate to Administration > Settings > External key vault > Device auto login.
  3. Click Edit.
  4. If you previously configured HashiCorp vault as the external key vault connection, click Enabled to retrieve the auto-login credentials from that external key vault.

    If this option is disabled, then the external key vault connection was not configured.

    Note: If you disable auto-login from the external key vault, then credentials are retrieved using the AAI Credential Vault and its stored credentials instead.
    Note: When you integrate the Automation 360 server with an external key vault for auto-login, you can now configure the mapping of user name and the key vault’s object names using the Control Room settings, instead of following the Automation 360 naming conventions. See Custom secrets mapping.
  5. The HashiCorp vault has a flat name space without any organizational containers, so you do not need to enter a Safe name. Click Save changes.

If successful, then the auto-login settings successfully saved message displays.

Auto-login naming conventions

The Control Room retrieves auto-login credentials based on the secret naming convention within the external key vault. The Control Room searches for an object where the secret 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, HashiCorp, and Azure. 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 secret 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 secret naming conventions expected in the Control Room:

Control Room username Expected secret name format
ABCD\user123 autologin_ABCD--user123
user123@rpa.abcd.com autologin_user123-40-rpa-2e-abcd-2e-com
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 secret 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, 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 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.

HashiCorp auto-login credential example

For this auto-login credential retrieval example, consider a Control Room user who wants to deploy a bot on a device as a specific user. This example uses the following details:

  • Automation (bot) name run on a device = ProcureToPayGeoEast
  • Agent device name = WinVDI1138
  • Agent user context = autologin-5f-rpauserCR1-40-abcd-2e-com

The following image shows this an example of retrieving auto-login credentials with HashiCorp vault:hashicorp_auto_login-credentials

Before starting the automation, ensure the following:

  1. The Control Room connection details have been successfully configured, and the Control Room uses these connection details to connect to HashiCorp and performs authentication.
  2. The Control Room queries the Bot Agent device running on device WinVDI1138 to check if there is an active Windows (operating system) session currently on device WinVDI1138, and if that session belongs to Agent user rpauserCR1.

    If there is an existing session on the device for user rpauserCR1, then there is no need to perform auto-login and the bot continues with the deployment.

  3. However, if there is an no active session or if there is an active session that does not belong to rpauserCR1, then the Control Room retrieves the auto-login credential from the HashiCorp vault.
  4. The Control Room passes the credential (password) to theBot Agent. The Bot Agent performs a Windows login on device WinVDI1138 as rpauserCR1 (first, logging off any other user login session) using the auto-login credential for rpauserCR1. The automation (Bot) ProcureToPayGeoEast then starts to run on device WinVDI1138 as rpauserCR1.

Retrieve automation credentials

Note: This use case applies to both On-Premises and Cloud deployments.

Automation credentials are variables used by bot developers within automation (bot) actions that define and retrieve data from encrypted storage. The automation uses the credentials to authenticate to applications (for example: finance application). Automation credentials are retrieved by the Automation 360 Bot Agent during runtime.

The following image shows the process of retrieving automation credentials with HashiCorp:

hashicorp_retrieve_automation_credentials

Automation credentials retrieved from the HashiCorp vault are mapped in the Automation Anywhere Credential Vault. The Credential Vault supports these two types of automation credentials:

System credentials
Credentials where the value returned by the credential variable is the same for any automation that uses that variable.
User-defined credentials
Credentials where the value returned by the credential variable is distinct based on the user context in which the automation is running.

For both system credentials and user-defined credentials, the bot developer specifies the same credential variable within the bot code. Then, the system determines which credential to retrieve during bot runtime.

User-defined credentials simplify automation development by enabling bot developers to write code using a single credential variable where the RPA platform substitutes the value returned during runtime with a unique user-specific value. Developers can avoid writing duplicate code with different user-specific credential variables.

The following image shows the expected naming convention for HashiCorp credentials:

HashiCorp expected credentials

The diagram shows six secrets in the HashiCorp vault which can be mapped to two credentials within the Control Room Credential Vault

  • Object3
  • Object4

For example, you can map a locker in the Control Room to either prefixID3 or prefixID4. Then, you map the secret to a credential. For each credential, the secrets will be consumed (retrieved by the Control Room) as a system-defined credential (without username postfix) and two user-defined credentials (one each for the Control Room users whose usernames are User1ID1 and User1ID2).

Note: Within the Control Room Credential Vault, the name of the locker and the name of the credential are arbitrary and local to the Control Room. You map these names to specific secrets in the external key vault.

Within HashiCorp vault, each automation credential is stored with a name that contains specific identifiers including: a prefix, object identifier, and an optional postfix which identifies a username. This is a required naming convention that assures retrieval of the correct credential. The name of the secret (the credential) in HashiCorp vault encodes information about the mapping within the Automation Anywhere Credential Vault.

As an administrator, to map a Control Room to HashiCorp vault, you create and configure a locker and a credential using the external key vault option within the Create Locker and Create Credential features in the Automation 360 Control Room:

  • You configure lockers in the Credential Vault that map to an HashiCorp vault name prefix.
  • You configure credentials in the Credential Vault that map to an HashiCorp vault object identifier (optional postfix for user-defined credential).

During runtime, the RPA platform retrieves the secret that is named with a postfix that matches the user context (user-defined credential) in which the automation is running. If there is no user-defined credential, then the RPA platform retrieves the secret without a username postfix (system credential).

The Control Room implements access controls to the external credentials through permissions within roles. You control access to credentials by assigning different Control Room users to different roles and then associating different lockers with those roles.

The following image shows the Control Room Credential Vault locker and credential mapped to an HashiCorp vault:

HashiCorpmapped credentials to Credential Vault

Important: When creating an externally mapped credential, you must place the credential in the appropriate externally mapped locker (the locker is mapped to the prefix in the secret name). The HashiCorp vault name will have a naming convention: Prefix + Secret_Name_Body + Postfix (optional for user-defined credentials).
Note: The same permissions and privileges (assigned through roles) in the Control Room apply to credentials mapped to the external key vault.

Automation naming conventions

The following table shows HashiCorp vault external key vault examples using naming conventions for automation.

Note: The HashiCorp Prefix maps to the locker for the Control Room, and the HashiCorp vault maps to the credential for the Control Room.
Automation credential example HashiCorp Prefix HashiCorp key/value secrets engine Secret in HashiCorp Control Room username

accounting_pdf

System credential in locker mapped to HashiCorp vault secrets name prefix accounting

accounting pdf accounting_pdf (system) None - system credential

accounting_pdf_ABCD--user123

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

accounting pdf accounting_pdf_ABCD--user123 ABCD\user123

HashiCorp automations credentials retrieval example

To configure automation credentials retrieval and integrate with the HashiCorp vault, you first create a locker and then create credentials.

Note: If you want to store credentials in the Control Room credential vaults and external key vaults, we recommend that you perform the following:
  • Create separate lockers in the Control Room to store credentials created in the Control Room credential vaults.
  • Create separate lockers in the Control Room to store credentials created in external key vaults.

The Control Room does not support storing credentials from the Control Room credential vaults and external key vaults in the same locker.

To create a locker to integrate with the HashiCorp vault, perform these steps:

  1. From the Automation 360 Control Room, navigate to Manage > Credential.

    A user with Manage my credentials and lockers permissions is authorized to create credentials.

  2. From the Credentials tab, select Create Locker.
  3. Enter a name for the locker (for example, Locker3).

    This name is local to the Control Room and does not have any dependency on the HashiCorp vault secret name.

  4. Click External Key Vault and enter the HashiCorp vault secrets name prefix (for example: prefixID3). You must name secrets within the HashiCorp vault using the name prefix for the configuration of the mapping to complete successfully.
  5. Click Next.
  6. Configure Owners, Managers, Participants, and Consumers for the locker.
  7. Click Create locker.

    See Create locker.

The Control Room is now ready to retrieve credentials and enforce access controls on all HashiCorp secrets with the prefix prefixID3. To continue, you now create the credentials.

To create a credential to integrate with the HashiCorp vault, perform these steps:

  1. From the Automation 360 Control Room, navigate to Manage > Credentials .

    A user with Manage my credentials and lockers permissions is authorized to create credentials.

  2. From the Credentials tab, select Create Credential.
  3. Enter the credential name in the Credential name field.

    This name is local to the Control Room and does not have any dependency on the HashiCorp vault secrets name.

  4. Click External key vault below the name field.
  5. From the list of available lockers, select the appropriate locker that was previously mapped to the secret name prefix for the secrets you are now mapping to the credential.
  6. Enter the HashiCorp Secret_Name_Body in the Secret name field (for example: Object3).
  7. Click Validate and retrieve attributes.

    The system validates the mapping by attempting to retrieve from the HashiCorp vault secret with the name Prefix_Secret_Name_Body (for example: prefixID3_Object3.

    If validation fails, then no secret exists in the HashiCorp vault with the name that matches the combination of locker (prefix) and credential (Secret_Name_Body). In this example, there is no secret in the HashiCorp vault named prefixID3_Object3.

    When the system successfully retrieves the secret, it will display the HashiCorp vault secret attributes (the fields within the secret).

  8. From the list of attributes, select attributes to map to the credential.
  9. Click Create credential.

    If successful, then the credential successfully created message displays.