Azure credential retrieval use cases
- Updated: 2024/01/22
Azure credential retrieval use cases
You can retrieve Azure credentials for these use cases: bootstrap, system, auto-login, and automations.
Retrieve Control Room bootstrap credentials
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 object name.
The following image shows the process of retrieving the Control Room bootstrap credentials with Azure:
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.
Retrieve Control Room system credentials
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.
- Log in to the Automation 360 Control Room as the Administrator.
- From the Control Room, navigate to: .
- 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
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 Azure:
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 Azure Key Vault must match the Control Room username.
To configure retrieval of auto-login credentials from the external key vault, perform these steps:
- Log in to the Automation 360 Control Room as the Administrator.
- From the Control Room, navigate to .
- Scroll down to the auto-login settings section and click Edit.
- If you previously configured Azure Key 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. - The Azure Key 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 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, 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 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 |
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- |
Azure 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 = rpauserCR1@abcd.com
The following image shows this an example of retrieving auto-login credentials with Azure:
Before starting the automation, ensure the following:
- The Control Room connection details have been successfully configured, and the Control Room uses these connection details to connect to Azure and performs authentication.
- 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.
- 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 Azure Key Vault.
- 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
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 Azure:
Automation credentials retrieved from the Azure Key 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 Azure credentials:
The diagram shows six secrets in the Azure Key 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).
Within Azure Key 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 Azure Key Vault encodes information about the mapping within the Automation Anywhere Credential Vault.
As an administrator, to map a Control Room to Azure Key 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 a locker in the Credential Vault to map to an Azure secret name prefix.
- You configure credentials in the Credential Vault that map to an Azure secret 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 Azure secret:
Automation naming conventions
The following table shows Azure Key Vault external key vault examples using naming conventions for automation.
| Automation credential example | Azure Prefix | Azure Secret Body | Secret in Azure | Control Room username |
|---|---|---|---|---|
|
accounting_cv1 System credential in locker mapped to Azure Secret name prefix accounting |
accounting | cv1 | pdf-5f-cv1 (system) | None - system credential |
|
accounting_cv1_ABCD\user123 User-defined credential in locker mapped to Azure prefix |
accounting | cv1 | pdf-5f-cv1-5f-ABCD--user123 | 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- |
Azure automations credentials retrieval example
To configure automation credentials retrieval and integrate with the Azure Key Vault, you first create a locker and then create credentials.
- 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 Azure Key Vault, perform these steps:
- From the Automation 360
Control Room, navigate to .
A user with Manage my credentials and lockers permissions is authorized to create credentials.
- From the Credentials tab, select Create Locker.
- 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 Azure secret name.
- Click External Key Vault and enter the Azure secret name prefix (for example: prefixID3). You must name secrets within the Azure Key Vault using the name prefix for the configuration of the mapping to complete successfully.
- Click Next.
- Configure Owners, Managers, Participants, and Consumers for the locker.
- Click Create locker.
See Create locker.
The Control Room is now ready to retrieve credentials and enforce access controls on all Azure secrets with the prefix prefixID3. To continue, you now create the credentials.
To create a credential to integrate with the Azure Key Vault, perform these steps:
- From the Automation 360
Control Room, navigate to .
A user with Manage my credentials and lockers permissions is authorized to create credentials.
- From the Credentials tab, select Create Credential.
- 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 Azure secret name.
- Click External key vault below the name field.
- 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.
- Enter the Azure Secret_Name_Body in the Secret name field (for example: Object3).
- Click Validate and retrieve attributes.
The system validates the mapping by attempting to retrieve from the Azure Key Vault a secret with the name Prefix_Secret_Name_Body_LoggedInUser (for example: prefixID3_Object3_testuser1).
If validation fails, check for the following parameters:- Verify that no secret exists in the Azure Key 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 Azure Key Vault named prefixID3_Object3.
- Verify that there are no special characters or encoding in the username or secret name.
See: External key vault naming conventions.
When the system successfully retrieves the secret, it will display the Azure Key Vault secret attributes (the fields within the secret).
Note: The secret value must be in the following JSON format:{ "username": "dummyUserName", "password": "dummyPassword" } - From the list of attributes, select attributes to map to the credential.
- Click Create credential.
If successful, then the credential successfully created message displays.