Introduction to credentials, connections, and aliases for Orchestration

All application integrations in Orchestration require connection information, credentials, and connection and credential aliases to their respective applications to access resources.

Before you can execute an application integration in Orchestration, you must create and configure the corresponding connection information and credentials. The Connections pertains to an integration with a system, such as an IP address or endpoint with protocols. It contains specific details, such as database particulars, when integrating with a database. The associated Credentials are the authentication data required to make the connection.

Connection information and credentials can vary between QA/Development/Production environments for the same integration. The tight coupling between this data and application metadata, such as workflow or job scheduling, make application metadata obsolete when you change environments. To alleviate this problem, the concept of an alias is introduced, for connections and credentials, to decouple this data from application metadata. These aliases allow customers to design their application metadata to couple to an alias, which during runtime resolves to connection and credential data.

There are two types of aliases, a connection and credential alias and a credential alias. There are business rules that enforce certain constraints on these aliases. Names should contain alphabets, numbers, and underscores but cannot have special characters. The alias must be unique in a scope. If you choose to have multiple active connections, you can have more than one active connection in the same domain. If you do not choose this option, you can have only one active connection in per domain.
Note: If you enable multiple active connections, when the connection records resolve, your application picks one connection based on an established order. The order of the connections depends on the API you use to retrieve connection data.
You can add additional connection attributes to an alias, which are available in connection data during run time. Variables overridden by connection administration during run time should not affect the alias.

The credential alias resolves only credential data. Along with alias data model, you can use a scriptable API which can get connection and credential data during runtime.

Using Connection and Credential Alias with Orchestration

Define an alias to label a credential or connection record.

The Credential and Connection Alias defines an alias that labels a credential or connection record. It is extended from the sys_metadata table. It requires the admin role. The credential_admin and connection_admin have read access to sys_alias. A connection alias contains:
Name
Name of the alias.
ID
This field is based on the format "scope name.alias name" Unique index on ID to ensure unique record based on scope name + name. If the scope is global, the ID is the alias name.
Type
You can select either 'Credential' or 'Connection and Credential'. The default is Connection and Credential.
Connection type
This field is applicable when the alias type is set to Connection and Credential. There are three connection types: HTTP, JDBC, JMS. The default is HTTP.
If you create a workday alias in global scope, the ID is set to workday
If you create a workday alias in hr app scope, the ID is set to x_hr_app.workday
  • Name can only contain alphabets, numbers and underscore.
  • During the upgrade, the tag in credential record will be migrated to connection alias. If the tag in previous release‚Äôs credential record contains special characters other than alphabets, numbers and underscore, the tag data will be preserved during the upgrade. The user still can use these connection alias, but the user cannot update these alias, unless he removes these special characters when do the update.

Using credentials with Orchestration

Orchestration requires credentials to access resources.

Credential table

The credential table (discovery_credential) defines credentials that can be used for integration. In the previous release, the Credential table contains a string-type tag field, which labels a credential and the tag is used in orchestration activities. In the Kingston release, we rename tag to credential alias, and change the type from string to GlideList, which is a reference to connection alias table.

Credential types

The following credential types are provided:
Credential type Description Supports Test Credential option
Applicative credentials The credentials to explore the applications on a device or computer. Pattern customization often need applicative credentials. No
AWS credentials The Amazon Web Services (AWS) master account, access key ID, and secret access key.
Note: You cannot test AWS credentials through the Test
No
Azure credentials The Azure service principals required for an Azure subscription. No
Basic authentication credentials A user name and password. No
CIM credentials The user name and password required to access a CIMOM - Common Information Model Object Manager (CIM) server, which obtains information about VMware ESX servers. No
Cloud credentials Credentials that Orchestration uses to access cloud resources. No
JDBC credentials A user name and password to access a Java Database Connectivity (JDBC) connection. Yes
JMS credentials A user name and password to access to a Java Message Service (JMS). Yes
OAuth 2.0 credentials OAuth 2.0 credentials enable ServiceNow to obtain access to user accounts on an HTTP service.
SNMP community credentials The community string to access devices via SNMP. Yes
SNMPv3 credentials The user name and keys required to access devices on your SNMP v3 network. Yes
SSH credentials The user name and password to access Linux and Unix devices. Yes
SSH private key credentials The private key credentials to access Linux and Unix devices.

SSH private key credentials are recommended over SSH password credentials for security reasons.

Yes
VMware credentials Credentials to access vCenter resources. These credentials are required for any work that is performed on vCenter, such as cloning a virtual machine. Yes
Windows credentials The user name and password required to access Windows computers. Several requirements must be satisfied to use Windows credentials. Yes

How MID Servers use credentials

By default, Windows MID Servers use the login credentials of the MID Server service on the host machine to discover Windows devices in the network. You should configure these service credentials so that they have domain or local administrator privileges. For Linux and UNIX machines and network devices, the MID Server uses the SSH and SNMP credentials configured in the instance in Discovery > Credentials.

MID Servers that Orchestration uses must have access to the necessary credentials to execute commands on computers in the network as specified by the Workflow activities. Orchestration can use the same SSH and SNMP credentials as Discovery, but has two additional credentials designed for specific Workflow activities: Windows (for PowerShell) and VMware.

Encryption and decryption

The platform stores credentials in an encrypted field on the Credentials [discovery_credentials] table. Once they are entered, they cannot be viewed.

When credentials are requested by the MID Server, the platform decrypts the credentials using the following process:
  1. The credentials are decrypted on the instance with the password2 fixed key.
  2. The credentials are re-encrypted on the instance with the MID Server's public key.
  3. The credentials are encrypted on the load balancer with SSL.
  4. The credentials are decrypted on the MID Server with SSL.
  5. The credentials are decrypted on the MID Server with the MID Server's private key.
Note: The platform does not have separate encryption keys for multi-tenant instances.

Credential order

Credentials can be assigned an order value in the Credentials Form, which forces the application to try all the credentials at their disposal in a certain sequence. If you do not specify an order value, the application tries the credentials in the Credentials [discovery_credential] table randomly, until it finds one that works, such as when Orchestration attempts to run a command on an SSH server (such as a Linux or UNIX machine), or when Discovery attempts to query an SNMP device (such as a printer, router, or UPS).

After identifying the credentials for a device, Discovery and Orchestration create an affinity between the credentials and the device using the Credential Affinity [dscy_credentials_affinity] table. All subsequent discoveries or Orchestration activities attempt to match the credentials in this table with a device for which an affinity exists. If credentials for a device change, Discovery and Orchestration try all available credentials again until they create a new affinity.
Note: If Orchestration and Discovery are installed, and credential alias is enabled, multiple affinities can exist. In this case, the platform looks up credentials for each affinity and inserts the credential for the affinity with the lowest order into the probe.
Ordering credentials is useful in the following situations:
  • The credentials table contains many credentials, with some used more frequently than others. For example, if the table contains 150 SSH credentials, and 5 of those are used to log into 90% of the devices, it is good practice to configure those five with low order numbers, which places them at the top of the execution list. Discovery and Orchestration will work faster if they try these common credentials first. After the first successful connection, the system knows which credentials to use the next time for each device.
  • The system has aggressive login security. For example, if the Solaris database servers in the network only allow three failed login attempts before they lock out the MID Server, configure the database credentials with a low order value.

Credential alias

Credential alias allows flow and workflow creators to:
  • Assign individual credentials to any activity in an Orchestration workflow
  • Assign individual credentials to any action in Flow Designer
  • Assign different credentials to each occurrence of the same activity type in an Orchestration workflow.
  • Assign different credentials to each occurrence of the same action in designer flow.
Credential alias also works with credential affinities.

External credential stores

If you do not want credentials stored in your instance, you can use external credential repositories. External credential stores save the credentials in an external site that your instance can access. Only CyberArk is supported.

Connections with Orchestration

Use the connections table to setup a JMS, JDBC, or HTTP(s) connection to a target host.

Connection Table

The Connection table (sys_connection) is the base table for all connection tables. You can setup connections for the following protocols:
  • JDBC
  • JMS
  • HTTP(s)
The connection table references the connection alias table, which couples the connection alias to connection information. Every connection records the following information:
Table 1. Base connection properties
Field Description
Name Name of the connection. This field must be unique on the table.
Credential Specify the credential to use with this connection. This is optional.
Connection alias The connection alias resolves your connection and credentials at run time. Only one connection is active per Connection alias at any one time.
Active Check to make the current connection active.
Domain Domain to which the connection belongs.

Credential is unique across active connections, if not empty

Upgrading connection information

The JDBC connection (jdbc_connection) and JMS connection (orch_jms_ds) tables are existing Orchestration connection tables. In Kingston, we re-parent them to extend from Connection (sys_connection) table. They move from Orchestration run time plugins to Credentials & Connections plugins. They are originally extended from sys_metadata. The sys_metadata related data will be removed. JDBC field name changes:
  • JDBC server is renamed to host
  • Database port is renamed to port