Overview

Credentials are the user ID and password under which an Agent runs tasks on the machine where the Agent resides.

By default, an Agent will run tasks under the same Credentials used to install the Agent. However, via the Controller user interface, you also can define Credentials and assign them to any task or Agent.

When prompted for Credentials, the Agent looks in the following locations, in this order, for a user ID and password:

If the task specifies Credentials, the Agent uses those Credentials.
If the task does not specify Credentials, the Agent uses the Credentials specified in its Agent Details record.
If the Agent Details does not specify Credentials, the Agent uses the Credentials used to install the Agent.

Types of Credentials

There are four types of Credentials:

Standard	Runtime user name and runtime password of a user.
Resolvable	Runtime user name and runtime password of a user that you can embed into a task or script without exposing the password in clear text.
Web Service	Runtime user name and runtime password of a user running a Web Service task.
Email	Runtime user name and runtime password of a user connecting to an incoming mail server (IMAP).

Note

Unless Credentials must be embedded, we recommend defining Standard Credentials. If required, you can always convert a Standard Credential to a Resolvable Credential at a future time.

Converting Credential Types

You can convert a Credential from any type to any type.

To convert a Credential type from Standard to Resolvable, Web Service, or Email, the Resolvable Credentials Permitted, Web Service Credentials Permitted, or Email Credentials Permitted Universal Controller system property, respectively, must be set to true.

To convert a Credential, either:

Click the Convert... button in the Credential Details.
Select Convert... in the Credentials Details action menu.
Select Convert... for a specific Credential in the Credentials List action menu.

When you convert a Credential, you must provide a new password. The Controller will not convert an encrypted password of one Credential type to an encrypted password of a different Credential type.

Note

Converting a Credential type does not create a new version of the Credential. Also, you cannot restore a Credential to an older version if the Credential type of the current version is not the same Credential type as the older version.

Credentials Compatibility

As of Universal Controller 6.4.x, the Credential Runtime Passwords, along with the LDAP Settings Bind Password, Email Connection Passwords, Promotion Target Passwords, and Promotion Schedule Promotion Passwords, now are encrypted using AES with 128-bit keys.

Additionally, Standard and Resolvable Credentials are encrypted using separate keys; therefore, an encrypted password for a Standard Credential cannot be decrypted by the Resolvable Credential framework.

Under the following circumstances, conversion from the old encryption to the new encryption will be automatic. Furthermore, all pre-6.4.x credentials will be recognized as Standard credentials.

Apply maintenance to a pre-6.4.x release of Universal Controller to increase it to a 7.7.x release.
Perform a bulk import or list import from a pre-6.4.x release of Universal Controller to a 7.7.x release.
Promote from a pre-6.4.x release of Universal Controller to a 7.7.x release.

Under the following circumstance, conversion from the new encryption to the old encryption will be automatic.

Promote from a 7.7.x release of Universal Controller to a compatible pre-6.4.x release. However, any attempt to promote a Resolvable Credential from a 7.7.x release of Universal Controller to a compatible pre-6.4.x release will fail.

Pre-6.4.0.0 releases cannot decrypt anything encrypted by a 7.7.x release, with the exception of promotion (noted above), which is fully backwards compatible.

Please note the following backwards compatibility constraints with respect to List Import, Bulk Import, and the Universal Controller Start-up Properties (opswise.properties).

Any attempt to List Import or Bulk Import XML (containing a password encrypted by a 7.7.x release) into a pre-6.4.0.0 release will result in an encrypted value that cannot be decrypted by the pre-6.4.0.0 release.
Any encrypted passwords within the Universal Controller Start-up Properties will be re-encrypted using the new algorithm when the 7.7.x Controller initializes at start-up. Once converted, that Universal Controller Start-up Properties will no longer be compatible with a pre-6.4.0.0 release.

Resolvable Credentials

Resolvable Credentials are meant to be used with scripts and commands specified in tasks, and resolved when the script or command is executed. They provide the script or command with access to Credentials (user name and password) without having to hard-code the Credentials in the script, command, or parameters itself.

In order to enable the use of Resolvable Credentials, the Resolvable Credentials Permitted Universal Controller system property must be set to true (default is false).

If the Resolvable Credentials Permitted property is set to false, the following restrictions on Resolvable Credentials apply:

You cannot create a Resolvable Credential.
You cannot convert a Standard Credential to a Resolvable Credential.
Any attempt to launch a task with an embedded Resolvable Credential will result in a Start Failure status.

Using Resolvable Credentials in a Script

To use Resolvable Credentials with a script, embed the Resolvable Credentials in any of the following:

Content of a Script specified in the Script field in a Linux/Unix or Windows task.
Content of a Data Script.
Universal Template Script (Script, Linux/Unix Script, or Windows Script field).
Content of a Script specified in the Payload Script field in a Web Service task.

Using Resolvable Credentials in a Task

To use Resolvable Credentials with a task, embed the Resolvable Credentials in any of the following:

Task	Fields
Linux/Unix	Command Parameters Environment Variables
Universal Task	Text Array Script Content Environment Variables
Windows	Command Parameters Environment Variables
Web Service	URL Query Parameter Values (Not Name) Form Data Values (Not Name) Form Payload HTTP Headers Values (Not Name)

Embedding Resolvable Credentials

Five Controller Credentials Functions are available for embedding Resolvable Credentials:

Name	Description	Syntax
Return Key Location of a Credential	Used for embedding the Key Location in a script.	`${_credentialKeyLoc('<credential_name>')`}
Return Passphrase of a Credential	Used for embedding the Passphrase in a script.	`${_credentialPassphrase('<credential_name>')`}
Return Token of a Credential	Used for embedding the Token in a script.	`${_credentialToken('<credential_name>')`}
Return User Name of a Credential	Used for embedding the Runtime User in a script.	`${_credentialUser('<credential_name>')`}
Return User Password of a Credential	Used for embedding the Runtime Password in a script.	`${_credentialPwd('<credential_name>')`}

Variables are supported for these Functions.

For example:

${_credentialKeyLoc('${my_credential}')}
${_credentialPassphrase('${my_credential}')}
${_credentialToken('${my_credential}')}
${_credentialUser('${my_credential}')}
${_credentialPwd('${my_credential}')}

In the resolved script, these Functions are resolved to (for example):

$(ops_unv_cred_key_loc_08236da16c3944899aae5a874da077bb)
$(ops_unv_cred_passphrase_08236da16c3944899aae5a874da077bb)
$(ops_unv_cred_token_08236da16c3944899aae5a874da077bb)
$(ops_unv_cred_user_08236da16c3944899aae5a874da077bb)
$(ops_unv_cred_pwd_08236da16c3944899aae5a874da077bb)

Additionally, for a Universal Template, you can create a Field of Type = Credential, which lets you select or create Resolvable Credentials. The Controller will create a variable for the Resolvable Credential Field, which you can embed in the Universal Template script using the Credentials Functions. This also lets you change Credentials when you run a Universal Task based on the Universal Template.

Note

When you embed Resolvable Credentials in a script, the password is exposed in the temporary script on the Agent while the task instance is running.

Resolvable Credentials embedded in a command or parameters field of a Linux/Unix or Windows task are not exposed on the Agent system.

By default, occurrences of Resolvable Credential passwords are scrubbed from the output, reducing (but not eliminating) the risk of passwords echoed directly to the task instance output, which can be retrieved and viewed within the Universal Controller. Please note, however, you still could echo the password to a file on the Agent server.

Note

By default, occurrences of Resolvable Credential passwords and passphrases are scrubbed from Web Service task output, reducing (but not eliminating) the risk of passwords and passphrases return to the task instance output or output metadata, which can be retrieved and viewed within Universal Controller. Please note, however, you still could use the functions against some API that stores the password and passphrase somewhere that you have access to.

Restrictions on Embedding Resolvable Credentials

If an embedded Credential is not a Resolvable Credential, the task instance will transition into the Start Failure status with one of the following status descriptions:

Execution with credentials "credential-name", contained within the Universal Template Script, prohibited due to credential type constraint; only Resolvable credential type permitted.
Execution with credentials "credential-name", contained within the command field or parameters field prohibited due to credential type constraint; only Resolvable credential type permitted.
Execution with credentials "credential-name", contained within the script "script-name", prohibited due to credential type constraint; only Resolvable credential type permitted.
For Web Service tasks:
Execution with credentials "credential-name", contained within the "<URL Query Parameter/Form Data/Payload/Payload Script/HTTP Headers>" field, prohibited due to credential type constraint; only Resolvable credential type permitted.

If the Execution User for a task instance does not have Execute permission for an embedded Resolvable Credential, the task instance will transition to the Start Failure status with one of the following status descriptions:

Execution with credentials "credential-name", contained within the Universal Template Script, prohibited due to security constraints.
Execution with credentials "credential-name", contained within the command field or parameters field, prohibited due to security constraints.
Execution with credentials "credential-name", contained within the script "script-name", prohibited due to security constraints.
Execution with credentials "credential-name", contained within a script, prohibited due to security constraints.
For Web Service tasks:
Execution with credentials "credential-name", contained within the "<URL Query Parameter/Form Data/Payload/Payload Script/HTTP Headers>" field, prohibited due to security constraints.

If the Resolvable Credentials Permitted Universal Controller system property is set to false, any task instance with an embedded Resolvable Credential will result in a Start Failure status with the following status description:

Execution with resolvable credentials not permitted; Universal Controller property "Resolvable Credentials Permitted" is not enabled.
For Web Service tasks:
- Execution with resolvable credentials not permitted; Universal Controller property "Web Service Task Resolvable Credentials Functions Permitted" is not enabled
- Execution with resolvable credentials not permitted; Universal Controller property "Resolvable Credentials Permitted" and "Web Service Task Resolvable Credentials Functions Permitted" are not enabled

If an embedded Resolvable Credential cannot be decrypted, the task instance will transition into the Start Failure status with the following status description:

Unable to decrypt password for "credential-name" credentials.

Other Credentials

You can embed source and destination Credentials in a UDM script using File Transfer Task Instance built-in variables.

For File Transfer tasks, the Agent may need additional credentials for logging on to the FTP server.

Defining a Credential

Step 1	From the Automation Center navigation pane, select Other > Credentials. The Credentials list displays a list of all currently defined Credentials. Below the list, Credential Details for a new Credential displays.
Step 2	Enter/select Details for a new Credential, using the field descriptions below as a guide. As a best practice, use an alias in the Name field, as you may have several identical user names for different systems all having different passwords. Required fields display an asterisk ( * ) after the field name. Default values for fields, if available, display automatically. To display more of the Details fields on the screen, you can either: Use the scroll bar. Temporarily hide the list above the Details. Click the New button above the list to display a pop-up version of the Details.
Step 3	Click a Save button. The Credential is added to the database, and all buttons and tabs in the Credential Details are enabled.

Note

To open an existing record on the list, either:

Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).

Credential Details

The following Credential Details is for an existing credential. See the field descriptions, below, for a description of all fields that display in the Credential Details.

For information on how to access additional details - such as Metadata and complete database Details - for Credentials (or any type of record), see Records.

Credential Details Field Descriptions

The following table describes the fields, buttons, and tabs that display in the Credential Details.

Field Name	Description
Details	This section contains detailed information about the credential.
Name	Name for this credential. Maximum length is 100 characters.
Version	System-supplied; version number of the current record, which is incremented by Universal Controller every time a user updates a record. Click on the Versions tab to view previous versions. For details, see Record Versioning.
Description	Description of this record. Maximum length is 255 characters.
Member of Business Services	User-defined; Allows you to select one or more Business Services that this record belongs to. (You also can Check All or Uncheck All Business Services for this record.) You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service. If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted.
Type	Type of Credential. Options: Standard (default) Resolvable Web Service Email Note Only Resolvable Credentials can be embedded in a Universal Template script.
Provider	Specifies Provider. Options: Universal Controller AWS Secrets Manager Azure Key Vault CyberArk Credential Provider CyberArk Central Credential Provider HashiCorp Vault Default is Universal Controller.
Provider Parameters	When switching the Provider option, the default Provider Parameters for each provider will be populated. When switching to the Universal Controller provider, the Provider Parameters will not be displayed.
Runtime User	Runtime user ID, including an LDAP- or AD-formatted user ID, under which the job will be run. Maximum length is 100 characters. If the user does not have a login shell, add a - character in front of the ID. The Controller will provide a shell for that user and strip the - character from the username. When specifying a Windows account, be aware that the user must have the following privileges based upon the Universal Agent's configuration for the UAG logon option: logon = Interactive (default) Not be in "Deny log on locally." Be a member of "Allow log on locally." logon = Batch Not be in "Deny log on as a batch job" Be a member of "Allow log on as a batch job" When specifying a local Windows account that may be used by an Agent running inside a Windows domain environment, be sure to use “.” as a placeholder for the domain name (for example, “.\<localuser>”). This qualifies the account name and ensures that Windows will authenticate it against the local – and not the active directory – account database. If the “.” placeholder is missing, the account may be interpreted as a domain account in a domain environment, and a task using that credential may fail. If none of your Agents execute on a Windows domain member or domain controller, the placeholder is optional. If a domain account must be used, you may specify the account name using the user principal name (UPN) format (that is, “<domainuser>@<domainname>”) or the down-level logon name format (that is, “<domainname>\<domainuser>”).
Runtime Password	Runtime user's password. Maximum length is 512 characters.
Key Location (SFTP only)	Location of the Runtime User's SSH private key in OpenSSH format; only applicable for SFTP. Maximum length is 255 characters.
Passphrase (SFTP only)	Passphrase for the Runtime User's SSH private key file; only applicable for SFTP. Maximum length is 512 characters.
Token	If Type = Resolvable; Token for the Runtime User that can be used with the ${_credentialToken(credential_name)} function. Maximum length is 8000 characters.
Metadata	This section contains Metadata information about this record.
UUID	Universally Unique Identifier of this record.
Updated By	Name of the user that last updated this record.
Updated	Date and time that this record was last updated.
Created By	Name of the user that created this record.
Created	Date and time that this record was created.
Buttons	This section identifies the buttons displayed above and below the Credential Details that let you perform various actions.
Save	Saves a new Credential record in the Controller database.
Save & New	Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.
Save & View	Saves a new record in the Controller database and continues to display that record.
New	Displays empty (except for default values) Details for creating a new record.
Update	Saves updates to the record.
Test Provider	For providers other than Universal Controller. Test Provider button will be available for validating the configured Provider Parameters.
Convert...	Allows you to convert the current Credential Type to a new type and define a new password for the Credential (see Converting Credential Types).
Delete	Deletes the current record.
Refresh	Refreshes any dynamic data displayed in the Details.
Close	For pop-up view only; closes the pop-up view of this credential.
Tabs	This section identifies the tabs across the top of the Credential Details that provide access to additional information about the credential.
Versions	Stores copies of all previous versions of the current record. See Record Versioning.

Provider Parameters

When switching the Provider option, the default Provider Parameters for each provider will be populated.

When switching to the Universal Controller provider, the Provider Parameters will not be displayed.

If a provider parameter is sensitive, value input will be masked in the client, and encrypted in the database. When viewing existing credentials, sensitive provider parameter values are never sent to the client.

AWS Secrets Manager

Provider Parameter	Required	Description
ACCESS_KEY_ID	true	The AWS access key, used to identify the user interacting with AWS.
SECRET_ACCESS_KEY	true	The AWS secret access key, used to authenticate the user interacting with AWS.
REGION	true	The region name (e.g., us-east-1).
SECRET_ID	true	The ARN or name of the secret to retrieve.
SECRET_PASSWORD_KEY	false	If this secret was created by using the console, then Secrets Manager stores the information as a JSON structure of key/value pairs. Specifies the key for the password in the JSON structure. If left unspecified, the password will evaluate to the entire secret value.
SECRET_PASSPHRASE_KEY	false	Specifies the key for the passphrase in the JSON structure. If left unspecified, the passphrase will be undefined.
SECRET_TOKEN_KEY	false	Specifies the key for the token in the JSON structure. If left unspecified, the token will be undefined.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 3600 seconds / 1 hour)

Azure Key Vault

Provider Parameter	Required	Description
KEY_VAULT_NAME	true	The name of the Key Vault used to build the vault URL to send HTTP requests to. https://<your-key-vault-name>.vault.azure.net
SECRET_NAME	true	The name of the secret.
CLIENT_ID	true	The client (application) ID.
TENANT_ID	true	The Azure Active Directory tenant (directory) Id.
CLIENT_SECRET		The client secret used to authenticate. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
CLIENT_ASSERTION		The client assertion used to authenticate. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PEM_CERTIFICATE		The path of the PEM certificate used for authenticating. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PFX_CERTIFICATE		The path of the PFX certificate used for authenticating. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PFX_CERTIFICATE_PASSWORD		The password for the PFX certificate. Required if the PFX_CERTIFICATE is specified.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 28800 seconds / 8 hours)

CyberArk Credential Provider

Provider Parameter	Required	Description
APPLICATION_ID	true	The unique ID of the application issuing the password request.
SAFE	true	The name of the Safe where the password is stored.
FOLDER	true	The name of the folder where the password is stored.
OBJECT	true	The name of the password object to retrieve.
REASON	false	The reason for retrieving the password.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5 seconds)

CyberArk Central Credential Provider

Provider Parameter	Required	Description
HOST	true	The hostname of the Central Credential Provider.
PORT	true	The port of the Central Credential Provider.
APPLICATION_ID	true	The unique ID of the application issuing the password request.
SAFE	true	The name of the Safe where the password is stored.
FOLDER	true	The name of the folder where the password is stored.
OBJECT	true	The name of the password object to retrieve.
KEYSTORE	true	The path of the keystore containing the client certificate used for authenticating.
KEYSTORE_PASSWORD	false	The password used to unlock the keystore.
KEYSTORE_TYPE	false	The type of keystore. (default PKCS12) JKS The proprietary keystore implementation provided by the SUN provider. PKCS12 The transfer syntax for personal identity information as defined in PKCS #12.
KEYSTORE_ALIAS	false	The name of a specific entry in the keystore to use.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5 seconds)

HashiCorp Vault

Provider Parameter	Required	Description
ADDRESS	true	The address of the Vault server (e.g. http://127.0.0.1:8200).
TOKEN		The Vault token for use with Vault’s token auth method.
ROLE_ID		The Role ID of the AppRole for use with Vault’s AppRole auth method.
SECRET_ID		The Secret ID belonging to the AppRole for use with Vault’s AppRole auth method. Required if the ROLE_ID is specified.
JWT		The signed JSON Web Token (JWT) for use with Vault’s JWT auth method.
ROLE		The Role name for use with Vault’s JWT auth method. Required, but not enforced, if the JWT auth method backend does not have a default role.
KEYSTORE		The path to the keystore containing the client certificate and private key for use with Vault’s TLS Certificates auth method.
KEYSTORE_PASSWORD		The password used to unlock the keystore.
KEYSTORE_TYPE		The type of keystore. Default is PKCS12. JKS The proprietary keystore implementation provided by the SUN provider. PKCS12 The transfer syntax for personal identity information as defined in PKCS #12.
CLIENT_CERTIFICATE		The path to the X.509 certificate, in PEM format, for use with Vault’s TLS certificates auth method.
CLIENT_KEY		The path to the unencrypted RSA private key, in PEM format, for use with Vault’s TLS certificates auth method. Required if the CLIENT_CERTIFICATE is specified.
AUTH_MOUNT_PATH	false	Specifies the path where the auth method backend is mounted.
MOUNT_PATH	false	Specifies the path where the KV backend is mounted. If not specified, the SECRET_PATH parameter will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV Version 2 secrets.
SECRET_PATH	true	The path to the KV secret.
DATA_PASSWORD_KEY	false	Specifies the key for the password in the secret data.
DATA_PASSPHRASE_KEY	false	Specifies the key for the passphrase in the secret data.
DATA_TOKEN_KEY	false	Specifies the key for the token in the secret data.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 300 seconds / 5 minutes) If the secret has a TTL, then it will be used to set the expiration time (KV Version 1 only).

Deleting a Credential

You cannot delete a Credential if any references exist for the Credential.

References will be checked according to the Credential type, as shown in the following table:

Credential Type	Record Type
Resolvable	Universal Task (Credentials Fields 1-4) Universal Template Field (Default Value)
Email	Email Monitor (Credentials)
Web Service	Web Service Task (Credentials)
Standard	Windows Agent (Credentials) Linux/Unix Agent (Credentials) Application (Credentials) Database Connection (Credentials) PeopleSoft Connection (Credentials) Windows Task (Credentials) Linux/Unix Task (Credentials) z/OS Task (Credentials) Universal Command Task (Utility Credentials, UCMD Credentials) SAP Task (Utility Credentials, SAP Credentials) PeopleSoft Task (Utility Credentials, PeopleSoft Credentials) File Transfer Task (Credentials, FTP Credentials, Source Credentials, Destination Credentials) SQL Task (Credentials) Stored Procedure Task (Credentials) File Monitor Task (Credentials) FTP File Monitor Task (Credentials, FTP Credentials) System Monitor (Credentials) Universal Task (Credentials) Universal Template (Credentials)

Note

Resolvable, Email, and Web Service Credentials can be used anywhere that a Standard Credential can be specified.