Credentials

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:

  1. If the task specifies Credentials, the Agent uses those Credentials.
  2. If the task does not specify Credentials, the Agent uses the Credentials specified in its Agent Details record.
  3. 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:

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.2.x release.
  • Perform a bulk import or list import from a pre-6.4.x release of Universal Controller to a 7.2.x release.
  • Promote from a pre-6.4.x release of Universal Controller to a 7.2.x release.

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

  • Promote from a 7.2.x release of Universal Controller to a compatible pre-6.4.x release. However, any attempt to promote a Resolvable Credential from a 7.2.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.2.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.2.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.2.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:

Using Resolvable Credentials in a Task

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

TaskFields
Linux/Unix
  • Command
  • Parameters
Windows
  • Command
  • Parameters
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

Required. Name for this credential.

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 Credentials#Versions tab to view previous versions. For details, see Record Versioning.

Description

Description of this record. (Maximum = 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:

Default is Universal Controller. 

Provider Parameters 

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

When switching to the Universal Controller provider, the Credentials#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.

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 is 512 characters.
 

Note

As of Universal Controller release 6.4.4.0, a credential with a password greater than 40 characters can now be used for an agent-based task instance that uses Universal Agent 6.4.2.0 or greater. If the Universal Agent release is earlier than 6.4.2.0, the agent-based task instance will continue to go Start Failure with the expected Status Description. Credentials with a password greater than 40 characters are supported only on Universal Agent 6.4.2.0 or higher.

Key Location
(SFTP only)

Location of the Runtime User's SSH private key in OpenSSH format; only applicable for SFTP.

Passphrase
(SFTP only)

Passphrase for the Runtime User's SSH private key file; only applicable for SFTP.

Token

If Type = Resolvable; Token for the Runtime User that can be used with the /wiki/spaces/UC71x/pages/5177620 function.

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 ProviderFor 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 Credentials#Type to a new type and define a new password for the Credential (see Credentials#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.

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)

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)

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.