Credentials and Certificates

To work with credentials in RunMyJobs, navigate to Security > Credentials.

Credentials are used to store username/password combinations in a central, secure manner. Credentials are typically used by Process Servers when they run processes or when they connect to remote systems.

To run processes on external platforms as a specific user, you can do one of the following things:

Directly specify the user, domain (if applicable), and password in the Process Definition Run As User field.
Omit the password and let RunMyJobs look it up using a separate credentials object. In this case, if the password of a user changes, it gets changed on the credential, which takes effect immediately. If, instead, you specified the user explicitly on Process Definitions, you would have to change the password on every Process Definition manually or with RedwoodScript.

Only the person that creates or modifies a credential needs to know the password. This person (or an administrator) can then pass the right to use the credential to other users, who can then create Process Definitions or submit processes using that credential without knowing the password.

Tip: It is a Redwood best practice to use credentials rather than specifying a password in the Run As User field, in parameters, or on the command line.

Tabs and Fields

The following table describes the fields that must be filled out for credentials.

Tab	Field	Description
Credential	Partition	The partition of the credential.
Credential	Protocol	The protocol for the credential.
Credential	Endpoint	The target system for the credential.
Credential	Real User	The actual user name.
Credential	Password	The password, usually case sensitive.
Credential	Retype Password
Credential	Virtual User	A virtual username to be used across the test, development, and production environments.
Credential	Description	An optional description of the credential. Can contain any combination of printable UTF-8 characters. Limited to 255 characters.
Credential	Documentation	An optional comment for the credential.
Security	*	This is where you can specify who can access/change/remove the credential.

Credentials support the following context menu options.

Note: For generally applicable object context menu options, see Object Context Menu.

Action	Description
Edit Security	Edit the security of the credential.
Delete	Delete the credential.
Edit	Edit the credential.
New credential	Create a new credential.

Security

The privileges available in the Security tab are as follows.

For more information, see Security Tab.

To use a credential, the user must have sufficient privileges. These can be Credential.view system privileges or corresponding object privileges.

To create a credential, you need to have privileges to see the credential protocol you want to use.

Privilege	Description
Credentials.Create	Create credentials
Credentials.Delete	Delete credentials
Credentials.Edit	Edit credentials
Credentials.View	View credentials

Note: Be careful when you create credentials to make sure that only specific users can use them. Access to a credential allows the grantee to log into a system without a password.

Credential Protocols

See Credential Protocols

Credential Lookup

With credentials, you specify the username in the Run As User and/or Remote Run As User field of a Process Definition, the Process Server parameter, or on an object. When the process gets allocated to a Process Server, or a Process Server connects to a remote system, RunMyJobs retrieves the credential password by matching a user and an Endpoint in the list of available credentials.

For processes, the user attribute comes from the JCS_USER process parameter. If that is empty or does not exist, it comes from the Run as User field. If that is empty, it comes from the DefaultRunAsUser Process Server parameter.

The Endpoint attribute comes from the JCS_ENDPOINT. If that is empty or does not exist, it comes from the Run as User field or a default (which depends on the protocol and service, but is usually the Endpoint Process Server parameter).

For Process Servers connecting to remote systems, the user attribute comes from the Redwood Server object orthe Endpoint Process Server parameter. It can also be the name of the Process Server, or the name of an ERP object.

The credential lookup is done by matching the user and Endpoint found above against the Real User and Endpoint in the credential. These are then combined into a new value (username/password@Endpoint) and passed to the service, which then uses this information to log into the external service.

If login fails or there is no accessible credential available, the process is put into status Error.

The Run As User and Remote Run As User fields support the following syntax:

[[<tryas>:]<runas>

<tryas>:== <credentialset> | {tryjobowner}
<runas>:== <credentialset> | {forcejobowner}
<credentialset>:== [[<endpoint>\] <user> [[/<password>] [[@<endpoint>] | {virtual}:<user> [[@<endpoint>]

The <tryas> and <runas> constructs are not supported by all Definition Types. See the Definition Type-specific documentation for the supported syntax.

The JCS_USER, JCS_REMOTE_USER, JCL_FTP_USER, and SQLPLUS_USER Process Definition parameters support the following syntax:

[{virtual}:]<user>

Note that tryjobowner and forcejobowner are not supported in Process Definition parameters, nor are the password or <endpoint>.

The user is evaluated in the following order (first found wins) for processes:

JCS_USER or JCS_REMOTE_USER process parameter.
JCL_FTP_USER or SQLPLUS_USER, for JCL_FTP and SQLPLUS Definition Types only.
Run As User or Remote Run As User fields.
DefaultRunAsUser Process Server parameter.

The endpoint is evaluated in the following order (first found wins) for processes:

JCS_ENDPOINT or JCS_REMOTE_ENDPOINT process parameter.
JCL_FTP_ENDPOINT or SQLPLUS_ENDPOINT, for JCL_FTP, and SQLPLUS Definition Types only.
Run As User or Remote Run As User field.
EndPoint Process Server parameter.
RemoteHostName Process Server parameter.

Note that JCS_USER behaves differently on Windows than did JCS_NTUSER in RunMyJobs version 7 and earlier; JCS_USER defaults to local accounts (when no domain is specified) whereas JCS_NTUSER would default to domain accounts.

Partitions

When a credential lookup is performed, the credential partition is evaluated in the below order. The first credential that the user can use and that matches the Endpoint will be used.

Partition of the Process Server.
Partition of the Process Definition (if applicable).
Partition of the Queue (if applicable).
The GLOBAL partition.

Note: This was introduced in RunMyJobs 9.0.9.0 and backported to 9.0.8.7. The previous lookup, used prior to 9.0.8.7, did not include the partition of the Queue and the partition of the Process Definition was used in favor of that of the Process Server.

Security with Credentials used in Processes

This section uses the following two concepts:

Process Definition owner: The user that created or imported the Process Definition.
Process owner: The user that submitted the process or Process Definition.

The lookup is first performed as the process owner; the process owner needs the required privileges on the credential. If this first lookup does not return a usable credential, and the Run As User field is set to {tryjobowner},<user>[@<domain>], or [<domain>\]user, the lookup is performed once more as the Process Definition owner. Note that for the latter approach to work, the Run As User field must be set; any Process Definition parameters will be ignored.

Credential Variations

Credentials can be modified using modifiers in the Run As User and Remote Run As User fields.

Not all Process Server services support modifiers. The following table lists the available modifiers and locations where they can be used.

Modifier or Specification	Service
`{virtual}`	Platform Agent, PeopleSoft, AS400, JDBC, Oracle, smtp
Secondary user specification	Platform Agent
`{forcejobowner}`	Platform Agent, PeopleSoft, JDBC
`{tryjobowner}`	Platform Agent, PeopleSoft, JDBC
`{logoff}`	Platform Agent

Note: Note that valid credentials must exist for the submitters when used with {forcejobowner}.

The Secondary User Specification

The Platform Agent service allows you to specify two separate usernames (and passwords) in the Run As User field. Separate these with a colon. The first field, Try User, will be tried first. If this user exists (and the password validates), that user will be used for the process. If the user does not exist (or the password is incorrect), then the second user will be used.

The {forcejobowner} Specification

If you encode the {forcejobowner} in the Run As User field, the system will log in as the RunMyJobs process owner. If this fails, the process is put into the Error status.

The {tryjobowner} Specification

If you encode the {tryjobowner} in the Run As User field, the system will log in as the RunMyJobs process owner. If this fails, the system will use any second user specification. Failing that, the system will run the process under the default account (as if the Run As User field was empty).

The {virtual}: Modifier

Virtual credentials allow you to specify a user across several systems by the same name, even though their username and password are different. When the process is allocated to a Process Server, RunMyJobs searches for a credential where the User attribute matches the value of the Virtual User (the {virtual}: prefix is trimmed). The Real User and Password from the credential are then used to log in and execute the code in the process.

Use virtual credentials when the usernames and passwords of specific users are different across systems. For example, all your systems could have a virtual user named erpuser which has a different username and password on one or more systems. In the Run As User field of the Process Definition, you can then specify {virtual}:erpuser. The credential with the Virtual User erpuser will be used, and the actual username and password can be different across systems, as in the example below.

	Standard Credentials	Virtual Credentials
Run As User value	username	{virtual}:vuser
Lookup by	Username=username Endpoint=RemoteHostName	VirtualUser=vuser Endpoint=RemoteHostName
Result	Password	Username Password

The table below shows a credential for processes running on Process Server GLOBAL.MSLN_WINS3, a Platform Agent running on a server named pr1.example.com.

Credential Field	Value
Partition	GLOBAL
Protocol	login
Endpoint	pr1.example.com
Real User	jdoe
Password	*********
Retype Password	*********
Virtual User	operator
Description	John Doe is the operator user used in the production environment

Valid Run As User fields:

jdoe
jdoe@pr1.example.com
pr1.example.com\jdoe
{virtual}:operator

The table below shows a credential for processes running on the example server domains of pr1.example.com, pr2.example.com, pr3.example.com, exc1.example.com, and erp1.example.com.

Credential Field	Value
Partition	GLOBAL
Protocol	login
Endpoint	example
Real User	jdoe
Password	*********
Retype Password	*********
Virtual User	operator
Description	John Doe is the operator user used in the production environment

Valid Run As User fields:

jdoe@example
example\jdoe
{virtual}:operator

Note: In this second example, you cannot simply specify jdoe unless the RemoteHostName is set to example as well, which is unlikely.

Using the Same Process Definitions in Test and Production Environments

The table below shows the credential for the production environment.

Credential Field	Value
Partition	GLOBAL
Protocol	login
Endpoint	example
Real User	jdoe
Password	*********
Retype Password	*********
Virtual User	operator
Description	John Doe is the operator user used in the production environment

The table below shows the credential for the test environment.

Credential Field	Value
Partition	GLOBAL
Protocol	login
Endpoint	examplet
Real User	scott
Password	*********
Retype Password	*********
Virtual User	operator
Description	Scott is the operator user used in the test environment

Valid Run As User field (for both environments):

{virtual}:operator

The {logoff} Modifier

The {logoff} modifier is used to force the RDP session specified in the JCS_SESSION parameter to close on process completion.

Password Security

By default, passwords are encrypted in the database using Redwood SecureStorage encryption. However, you can set the encryption mechanism for new passwords to AES SecureStorage encryption using the System_SecureStorage_Configure Process Definition.

Warning: Once you have enabled AES SecureStorage encryption, you cannot revert back to Redwood SecureStorage encryption. AES SecureStorage encryption uses a per-database key.

You cannot directly read the password of a credential; this is a security feature. To allow users to access the credential password, enable Externally Available (ExternallyAvailable) on the credential. The password can be accessed (protected) from Redwood Expression Language (Credential.getProtectedPassword(), Credential.getProtectedPasswordByProtocolRealUser(), or Credential.getProtectedPasswordByProtocolVirtualUser()) and RedwoodScript (Credential.getPassword()). You can un-protect a password using either of these methods:

RedwoodScript method SchedulerSession.unprotectPassword(String), which takes a protected password as returned by Credential.getProtectedPassword() as an argument
jtool echo

To restrict who can change the ExternallyAvailable property, activate the Externally_Available_Credential global privilege and grant it to the users/roles who should be allowed to make such changes.

The login credential is used to log in to Platform Agents. Set the Endpoint to the value of the RemoteHostName Process Server parameter when you specify the username only in the Run As User field of a Process Definition. The syntax to use is user.

Nis[+] and Microsoft Windows Domains

When you want to use a username/password for multiple systems, you can specify a Windows domain name or NIS[+] domain name in the Endpoint field of a credential. In the Process Definition, you now have to specify the domain name in the Run As User field. To do this, you use the following syntax: <user>@<domain>. On Microsoft Windows, the following syntax is also supported: <domain>\<user>.

Logical Endpoints

You use the Endpoint process server parameter to define logical endpoints for one or more Process Servers. This allows you to create a group of Process Servers that share common credentials (for example, a domain). The value of the Process Server parameter can be set to any alphanumerical value. The credentials that have this same value specified in Endpoint will then be used.

Domain Tree Support

You use wildcards in Run As User fields to use a same credential for multiple domains. The exact match will be looked up first. For example:

jdoe@host.dev.example.com
jdoe@.dev.example.com
.example.com
.com
'

Note that this slows down the lookup somewhat, because a full lookup is done for each asterisk (*). In this example, four lookups will be required if you only specified a credential with endpoint *.com, but seven lookups if you had it lookup the process owner as well.

Example

At Example Inc., MS Windows and UNIX jobs use a centralized authorization system. The central LDAP server has been set up to log in from various clients. The domain name is example.com.

In most Process Definitions, the Run As User field contains <user>@example.com. Some Windows Process Definitions at Example.com still use the old example\jdoe syntax. However, the old syntax requires duplicate credentials: one for Endpoint example, and one for endpoint example.com. It has been decided to change all Process Definitions to use the <user>@example.com syntax.

HTTP Server Credentials

Authentication to a HTTP server or proxy server can be done proactively. Authentication data is already sent on the first request, because it is known that it is needed, or reactively, where the HTTP or proxy servers answers with an "authentication required" code (401 or 407) and mentions a Realm. For this reason, realm-based credentials will only work in reactive mode, and require an extra round trip.

The following credentials are supported:

Type=HTTP  Endpoint=<hostname>:<port>  RealUser=<username> Password=<password> VirtualUser='default'
Type=HTTP  Endpoint=<hostname>  RealUser=<username> Password=<password> VirtualUser='default'
Type=HTTP  Endpoint=<realm>  RealUser=<username> Password=<password> VirtualUser='default'
Type=HTTP  Endpoint=*  RealUser=<username> Password=<password> VirtualUser='default'

Which one to create depends on your server setup. Sometimes it is better to use Realm, because it might be used in multiple servers (with the same login database), and thus be easier to administrate. In other cases, the realm changes over time, so it is better to use hostname instead. If your job definitions use an explicit IP address instead of a hostname, you must use the IP address in the credentials as well (which is another reason why it might be better to use Realm instead).

HTTP(S) Traffic via HTTP Proxy

Two approaches are available for the configuration of HTTP(S) proxy settings, for use with HTTP(S) traffic from the Redwood Server:

HTTP credentials: RunMyJobs credentials can be used to specify proxy server settings. This approach is available when there is a single proxy server used for HTTP traffic, or when there is communication with different HTTP servers that are accessed via different proxy servers. In either case, this approach is recommended because it is most flexible.
Global proxy server settings: This method can be used when there is a single proxy server. However, the HTTP credentials approach is preferred.

Creating HTTP Server Credentials

To use RunMyJobs credentials to specify proxy server settings, navigate to "Security > Credentials" in the navigation bar. Two types of HTTP credentials are available: proxy server credentials and HTTP server credentials.

Proxy Server Credentials

Credentials where the Virtual User field contains the value 'proxy'; used when the Endpoint is a HTTP host that is contacted via a proxy server. The Real User field will contain the URI to contact the proxy server, and the Password field is the password for the proxy host. This can be used to define per-host proxy servers.

Examples

Type=HTTP Endpoint=hostname:port RealUser=http://proxyuser@proxyhost:proxyport Password=proxypassword VirtualUser='proxy'
Type=HTTP Endpoint=hostname RealUser=http://proxyuser@proxyhost:proxyport Password=proxypassword VirtualUser='proxy'
Type=HTTP Endpoint=* RealUser=http://proxyuser@proxyhost:proxyport Password=proxypassword VirtualUser='proxy'

Note the peculiar use of the Real User field, which contains the URL of the proxy server. Standard URL encoding applies, so if the proxy user contains special characters such as @, they should be URL-encoded like this: http://proxy%40user@host.

The default for the proxy port is 3128. If the proxy does not require authentication, leave the proxyuser@ part out of the Real User field and use a dummy password (like '-').

HTTP Server Credentials

Credentials where the Virtual User field contains the value 'default'; used when the Endpoint is an HTTP server. The Real User and Password fields will contain the username and password to send to the HTTP server.

Examples

Type=HTTP Endpoint=proxyhost:proxyport RealUser=proxyuser Password=proxypassword VirtualUser='default'
Type=HTTP Endpoint=proxyhost RealUser=proxyuser Password=proxypassword VirtualUser='default'
Type=HTTP Endpoint=Realm RealUser=proxyuser Password=proxypassword VirtualUser='default' (causes extra round trip)
Type=HTTP Endpoint=* RealUser=proxyuser Password=proxypassword VirtualUser='default'

Global Proxy Server Settings

Global proxy server settings are not recommended by Redwood.

If you have a single HTTP proxy, then RunMyJobs can be configured to route all HTTP traffic via that HTTP proxy by defining it in the system configuration (for example, via the Redwood Server registry or the Global configuration file). Look at the System Configuration overview generated by the "Get Support Files" report to see where you can define these. If you are using SaaS, you can set these by adding RunMyJobs registry entries with the form /configuration/jcs/net/http/<proxy setting name>. Details on how to do this are presented under the configuration system documentation.

The configuration fields are:

proxyhost = The hostname or IP address of the HTTP proxy.
proxyport = The port that the proxy is running on. The default is 3128.
proxyuser = Username to authenticate with at the proxy.
proxypassword = Password to authenticate with at the proxy.
nonproxyhosts = List of hostnames to contact directly. Default is localhost,127.*,[::1],0.0.0.0,[::0]

If you do not set these in the configuration and are running on-premise, the proxy configuration is inherited from the Java JVM, which on Windows and some UNIX systems can be picked up from the host settings.

The nonproxyhosts field contains a "vertical bar" or "comma" separated list of hostnames and IP addresses that should not be proxied and should be contacted directly.

If the user and password are not set in the configuration, the system will look them up in the credentials as documented above in the "HTTP Credentials" section.

SOAP Definitions

The SOAP Process Definitions have traditionally had support for HTTP authentication and HTTP proxies, and this is implemented independently. Proxy settings for SOAP have been extended so that SOAP will also use the proxy settings defined in the HTTP credential protocol or system-wide proxy server (on premise installations, only).

JDBC

The built-in JDBC credential protocol is used to authenticate users against the remote database used on the Process Server defined in Endpoint. The Endpoint must match the name of a JDBC Process Server.

For example, if you want to connect Process Server MSLN_ORA01 to your Oracle database named ORCL on server ora1.example.com:

Credential Field	Value
Partition	GLOBAL
Protocol	JDBC
Endpoint	ORCL_DB
Real User	SCOTT
Password	*********
Retype Password	*********
Virtual User	operator
Description	Scott is the user used in the production database orcl

Create a Database object with the connection details and select SCOTT@ORCL_DB in the Connection User field.

In JDBC Process Definitions, you specify either SCOTT@ORCL_DB or {Virtual}:operator in the Run As User field.

Oracle

The built-in oracle credential protocol is used to authenticate users against the oracle database defined in Endpoint (usually the SID or service name, such as orcl or XE, for example). You must add the SQLPLUS Definition Type to a Platform Agent. The sqlplus binary must be on the path of the user running the job. On the SQLPLUS Process Definition you specify <user>@<Endpoint> to use the credential <user>-<Endpoint>-oracle.

Specify Oracle connect strings in credentials as follows:

Field	Value
Protocol	oracle
Endpoint	The connect identifier for the database
Real User	The username of the database user
Password	The password of the database user

Note: There is no capability to specify the SYSDBA or SYSOPER attributes in credentials. If you need to log in as SYSDBA, you must set the full connect string in the Run As User field.

Note: Make sure ORACLE_HOME is set for the user and that sqlplus is on the path of the user. You can use the EnvironmentVariables Process Server parameter to specify ORACLE_HOME.

Note: When no suitable Oracle credential can be found, a search is performed for an equivalent JDBC credential.

Example

You want to run a report in an Oracle database from within Redwood Server. The database user is named SCOTT, the password is tiger, and the database service name is example.

Field	Value
Protocol	oracle
Endpoint	example
Real User	SCOTT
Password	tiger

Chain Processes that use the credential have SCOTT@example in the Run As User field.

ERP

The following credential protocols fall under ERP credential protocols, because they all work in a similar way.

JDBC
OraOHI
PeopleSoft

The Endpoint must match the name of the system in Redwood Server. For example, a possible Endpoint could be OA12 for an Oracle Applications system. ERP systems use the credential to connect to the remote ERP system, so the Endpoint must match the name of the ERP system in Redwood Server.

Additionally, PeopleSoft supports the Run As User field of PeopleSoft Process Definitions. You specify a username, which must match the Real User of a PeopleSoft credential which has an Endpoint matching the PeopleSoft system name in Redwood Server. PeopleSoft also supports {tryjobowner}, {forcejobowner} keywords, and {virtual}: prefix; see the Credential Variations section above for more information.

Note: SAP_RFC credentials are documented below.

Example

You want to create a credential for your Oracle applications system named OApps on server ora1.example.com

Credential Field	Value
Partition	GLOBAL
Protocol	JDBC
Endpoint	OApps
Real User	SCOTT
Password	*********
Retype Password	*********
Virtual User	operator
Description	Scott is the user used in the production Oracle Applications system OApps

SAP_RFC

The built-in SAP_RFC credential protocol only uses Real User and Password fields. This way, a single SAP_RFC credential can be used with multiple SAP systems. No credential lookup is done with SAP_RFC credentials, as these are used exclusively in RFC scripting using RedwoodScript; you specify the exact credential to use in your code.

The built-in SAP_RFC credential protocol can be used with merely Real User and Password in combination with a fake Endpoint if no lookup is to be done. A number of Redwood-provided Process Definitions have a CREDENTIAL_USER parameter. These expect the Endpoint to be filled with the <partition>.<name> of the SAP system. The credential must reside in the same partition as the SAP system.

SOAP

The built-in soap credential protocol is used to authenticate users against servers providing web services. The credential is also used to count the number of remote servers for licensing. The Endpoint must match the FQDN of the server providing the web services. If no authentication is required, the username and password are ignored but must always be set. You can use dummy in this case to indicate that authentication is not required. To prevent authentication headers to be sent to the web service, you can use the {redwood}:nocredential syntax in the Run As User field. In your Process Definition source, you can also use req.setAuthentication(SOAPRequest.REDWOOD_NOCREDENTIAL, null).

SOAP definitions use HTTP credentials for proxies.

Example Proxy Credential

The following proxy configuration is used for all SOAP servers serving on port 80.

Protocol: login
Real User: jdoe
Password: ***
Endpoint: proxy.masalan.com
Virtual User: proxy:*:80

The following proxy configuration is used for all SOAP servers serving on port 443. This proxy server does not require a username, only a password:

Protocol: login
Real User: forceNone
Password: ***
Endpoint: sproxy.masalan.com
Virtual User: proxy:*:443

SMTP

The smtp credential protocol is used to authenticate users against mail servers. The Endpoint must match the value specified using the System_Mail_Configure Process Definition, and the Virtual User field must contain default.

SSH

The SSH credential protocols passphrase, PuTTY, and SSH are used by jgetcredential to retrieve any requested credential from the central server. By default, SSH_ASKPASS environment variable is to jgetcredential, and when jscp or scp request an SSH, PuTTY key or passphrase, jgetcredential will use the user and remote host to retrieve the credential in the central server.

Examples

The below examples illustrate how to run ssh or ssp and retrieve the credentials from various sources.

The BASH Process Definition has the following parameters set:

remoteUser=jdoe
remoteHost=server1.example.com
putty_keyfile=$HOME/jdoe.ppk

Following is an example where a private key $HOME/.ssh/id_{rsa,dsa} requires a passphrase. The passphrase is retrieved by ssh by calling jgetcredential (SSH_ASKPASS) to obtain the Redwood Server passphrase:<current user>@<remote host> credential. Host authentication is achieved using ssh server authorized_keys on the remote host.

${JCS_SSH_USER:=${remoteUser}} ${JCS_SSH_HOST:=${remoteHost}} ssh -i ${HOME}/.ssh/id_dsa -T ${remoteUser}@${remoteHost} uname

This can be shortened, as ssh prefers to use public key user authentication and by default uses $HOME/.ssh/id_{rsa,dsa} for private keys.

${JCS_SSH_USER:=${remoteUser}} ${JCS_SSH_HOST:=${remoteHost}} ssh ${remoteHost} uname

The following is an example where ssh uses password based user authentication. The user password is retrieved by ssh using jgetcredential (SSH_ASKPASS) to obtain the Redwood Server login:$JCS_SSH_USER@$JCS_SSH_HOST credential. Note that JCS_SSH_USER and JCS_SSH_HOST need to be configured in this case, to ensure that jgetcredential can determine the user and hostname. This example uses JCS_LOGLEVEL to verify from the logging that the correct credentials have been used.

JCS_LOGLEVEL=debug JCS_SSH_USER="jdoe" JCS_SSH_HOST="server1.example.com" ssh ${remoteUser}@${remoteHost} uname

Following is an example where an interactive login is performed via SSH by supplying the password via credential. The password is supplied by credential login:$JCS_SSH_USER@$JCS_SSH_HOST. Note that since "ssh" does not supply enough information to jtool, it needs to be told what the remote user and host are via JCS_SSH_ variables.

JCS_SSH_USER=${remoteUser} JCS_SSH_HOST=${remoteHost} ssh -i ${HOME}/.ssh/id_dsa -T ${remoteUser}@${remoteHost} uname

The BASH Process Definition has the following parameters set:

remoteUser=jdoe
remoteHost=server1.example.com
putty_keyfile=$HOME/jdoe.ppk

The following is an example of jtool scp using user authentication with a PuTTY private key ${putty_keyfile} and associated passphrase. The private key passphrase needed for user authentication is supplied by the Redwood Server credential passphrase:${comment}, or ${comment}@${HOST}, or ${USER}@${HOST} The -storekey parameter is supplied to save a new or updated remote server key (for server authentication) in the sshhostkeys cache.

jtool scp -i ${putty_keyfile} -storekey -ls ${remoteUser}:.

The following is an example of jtool scp using user authentication with a user/password combination. The password supplied by a Redwood Server credential login:${remoteUser}@${remoteHost}. Since the remoteUser field is supplied on the command line no JCS_SSH_USER environment variable is required.

jtool scp -ls ${remoteUser}@${remoteHost}:.

The following is an example of a jtool sftp to a Windows server, using user authentication with a user/password combination. The password supplied by Redwood Server credential login:${remoteUser}@${remoteHost}. Since the remoteUser field is not supplied on the command line the JCS_SSH_USER environment variable is required.

JCS_SSH_USER=${remoteUser} jtool sftp -batch ${remoteHost} <<EOD
dir *.bin
EOD

Following is an example of a PuTTY private key ${putty_keyfile} with a passphrase. The passphrase is supplied by credential passphrase:${comment}, or ${comment}@${HOST}, or ${USER}@${HOST}

jtool scp -i ${putty_keyfile} -storekey -ls ${remoteUser}@${remoteHost}:.

Following is an example of a server password being resolved by a credential. The password is supplied by credential login:${remoteUser}@${remoteHost}. Since this uses built-in code, it automatically knows when a login credential is needed, and for which user and host, so no var JCS_SSH_ is needed.

jtool scp -ls ${remoteUser}@${remoteHost}:.

jtool sftp -batch ${remoteUser}@${remoteHost} <<EOD
dir *.bin
EOD

Archive_Server

The built-in Archive_Server credential protocol is used to authenticate users against Active Archive. The Endpoint must match the value specified in the Process Definition Archive_Feeder_Configure.

X.509 Trusted Certificates

This credential type is used to store trusted TLS certificates, such as the public certificates of Certificate Authorities (CAs). This is in addition to the generally accepted list of trusted Root CAs contained within the Java KeyStore. Trusted Certificates are used to verify the identity of a remote server or service whilst establishing a secure HTTPS connection from the Redwood Server.

The default HTTPS connection method is to verify the server's certificate. It will be checked against the default Java JVM trust store, which will contain the OS or JVM default Certificate Authorities. If this doesn't work it looks if the server's certificate or root CA is stored as a X509_TrustedCertificate credential. The Common Name set in the Credentials for these certificates is only a (unique) alias. To make sure it is unique, it is suggested that this is set to the actual CommonName field as found in the certificate. For example, if the URL is https://client.example.com/path, the CommonName can be set to client.example.com.

A PEM-encoded public certificate will consist of a -----BEGIN CERTIFICATE----- header and a -----END CERTIFICATE----- footer, encoding base-64 encoded text that represents the actual certificate. Text such as Bag Attributes`, such as generated by tools such as openssl during conversion to PEM format, does not need to be manually removed before input. Only a single certificate should be input into each X.509 Trusted Certificate credential. The password field will be ignored, and should be left blank for X.509 Trusted Certificate credentials. The Common Name (endpoint) set in a X.509 Trusted Certificate credential is a unique alias; to ensure uniqueness, it is suggested that the Endpoint field is set to the actual CommonName found in the certificate.

HTTPS connections verify the hostname by checking whether the hostname or IP address is allowed by the server certificate. If not, either a warning is given in an Operator Message or the connection fails.

The above checks can be configured via the configuration system. The following options have been added:

Http.VerifyHostname
Verify / Warn / DontVerify

The DontVerify option is designed for troubleshooting purposes and should NOT be used.

A description of the current contents of the X.509 Trusted Certificate credential store can be seen by using System_DynamicTrace with Trace string api.http=debug;http=debug;net=debug

How Trusted Certificates are Used

The default HTTPS connection method verifies the identity of the remote server or service to which the Redwood Server is connecting. This is achieved by the remote server presenting their public certificate combined with the chain of digital signing certificates leading up to a Root Certificate Authority (Root CA). Trust of a remote server certificate is established when the Redwood Server trusts the Root CA, or specifically trusts a self-signed certificate.

The remote server certificate will be checked against the default Java JVM trust store, which will contain the OS or JVM default Certificate Authorities. Non-cloud customers can request their Java system administrator to add extra trusted certificates to this KeyStore.

It is also possible to add extra trusted certificates via TrustedCertificate Credentials.

The Redwood Server will first try to match the root CA certificate of the remote server against the default Java JVM trust store contents. If this match fails, it will look for a match in the TrustedCertificate credentials. To establish a secure connections to a remote server that presents a certificate issued by one or more private Root and intermediate CAs, you only need to create a TrustedCertificate Credential for the Root CA. But if your connection is to a remote server that presents a self-signed certificate, you should create an TrustedCertificate Credential for the self-signed certificate.

HTTPS connections verify the remote server hostname by checking whether the hostname or IP address is allowed by the server certificate. If not, either a warning is given in an Operator Message or the connection fails.

X.509 Client Certificates

Client certificates are used to authenticate to a remote HTTPS server by presenting a client certificate as identification. Client certificates must be loaded in the credential store as ClientCertificate credentials, in P12/PFX or PEM format, including a private key. If the private key is protected by a password or passphrase, this must be entered in the password field. Currently only RSA and DSA private key types are supported; there is no support for Elliptic Curve private keys. The Common Name (endpoint) set in a Client Certificate credential should be either the hostname or IP address of the remote server. For example, if the URL is https://client.test.com/path then the CommonName can be set to client.test.com.

Typically the ClientCertificate credentials will need to include the public certificate(s) of the CA(s) that digitally signed the client certificate, as this will need to be presented to the remote server. This is known as the certificate chain of trust, and if the client certificate is input in PEM format, the order should be:

<client public certificate>
[intermediate CA public certificate]
<root CA public certificate>
<client private key>

How Client Certificates Are Used

Whilst establishing an HTTPS connection, the remote server will present a list of acceptable CA issuer subject names. The Redwood Server will look through its ClientCertificate credentials and choose the first one that contains a matching CA subject name with a key protocol that is accepted by the remote server. As a fallback, if no ClientCertificate matches, a final lookup is done with the hostname used in the connection request.

Creating X509 Trusted and Client Certificates using the API

Create X509 Trusted Certificate Credentials

Protocol: X509_TrustedCertificate.
Protocol Type: Certificate.
Certificate: Where you upload the certificate file.
Password: the Root Certificate in PEM or base64-encoded CRT format.
Common Name: CommonName for the Root CA (recommended), or hostname of the server that is contacted.
Description:
Comment:

Create X509 Client Certificate Credentials

Protocol: X509_ClientCertificate.
Protocol Type: Certificate.
Certificate: Where you upload the certificate file.
Password: the Client Certificate in PEM or base64-encoded CRT format.
Common Name: CommonName from the Server certificate; either `CN` of the server itself (recommended) or a
             common name on the certificate chain, or hostname of the server that is contacted.
Description:
Comment:

Procedure

Create a Credential

Navigate to Security > Credentials.
Choose New Credential from the context menu, fill a Fully Qualified Domain Name (FQDN) into the Endpoint field.
Specify the username and password, which in most cases are case-sensitive.
Choose Save and Close.

Use a Credential

Navigate to Definitions > Processes.
Choose Edit from the context menu of a Process Definition that runs on an external platform.
On the Source tab, enter the username of the user provided in a credential.
Submit the process and choose a Queue that is served by a Process Server running on the Endpoint specified in the credential.

Values

Field	Description
Protocol	The protocol used for the credential, login is the default
Endpoint	The FQDN of the system where the user is valid
Real User	The username of the user on the Endpoint
Password	The password of the user on the Endpoint
Virtual User	The virtual username for the user

Example of Process Definition Promotion Across Systems

The ERP production system at Example Inc has an additional development and a quality assurance system; Process Definitions are developed and tested before they reach production. To ease the pain of migration, Example Inc uses the virtual user property of their credentials. The following accounts are used to run the jobs on the different systems:

pr1adm: production system
qa1adm: quality assurance system
dv1adm: development system

In the development system, you create a credential as follows:

Field	Value
Protocol	login
Endpoint	dv1.example.com
Real User	dv1adm
Password	someGoodSecret
Virtual User	erpadmin

In the quality assurance system, you create a credential as follows:

Field	Value
Protocol	login
Endpoint	qa1.example.com
Real User	qa1adm
Password	someOtherSecret
Virtual User	erpadmin

In the production system, you create a credential as follows:

Field	Value
Protocol	login
Endpoint	pr1.example.com
Real User	pr1adm
Password	stillAnotherSecret
Virtual User	erpadmin

Chain Processes that need to run as the environment-specific user contain {virtual}:erpadmin in the Run As User field. The Process Definition can be migrated without the need to change the Run As User field because in each system, the correct user is used to execute the code.

Example Connecting to a Windows system

Assume you want to run a program on a Windows server; preferably using a domain account but failing that a local user. The Run As User attribute can be specified like so:

user1/password1@domain:localuser/password@computername

Troubleshooting

The System_CredentialTrace Process Definition allows you to troubleshoot credential lookups. Submit your Process Definition that uses the credential on Hold, using Hold On Submit on the Control tab of the Submit Wizard, for example, and submit System_CredentialTrace with the JobId of the held process. The System_CredentialTrace process will release the held Process Definition. The output will be attached to the released process (not System_CredentialTrace ).

Example

A JDBC process was submitted on hold and System_CredentialTrace was submitted with the fcaJobDefinitionJob; ID parameter set to 64504:

CredentialTrace for JobId=64504, Subject=Administrator (Process Definition Type JDBC)
CredentialType='JDBC'
DefaultEndpoint='JDBC_Oracle'
Password is set to mandatory.
RunAsUser='invalid@JDBC_Oracle:example@JDBC_Oracle'
RunAsUser: split into Try and Must user
MustRunAs: Split into User='example', Endpoint='JDBC_Oracle', Password=<null>
MustRunAs: Credential found for User='example', Endpoint='JDBC_Oracle', Protocol='JDBC', Partition='GLOBAL' (Process Server)
MustRunAs: Specification is complete
TryRunAs: Split into User='invalid', Endpoint='JDBC_Oracle', Password=<null>
TryRunAs: No credential for User='invalid', Endpoint='JDBC_Oracle', Protocol='JDBC', Partition='GLOBAL' (Process Server)
TryRunAs: No credential for User='invalid', Endpoint='JDBC_Oracle', Protocol='JDBC', Partition='GLOBAL' (Job Definition)
CredentialTrace complete

Here, the Run As User field was set to invalid@JDBC_Oracle:example@JDBC_Oracle, the Definition Type was JDBC. The Run As User field value was split in two because two credentials were specified. Both credentials were looked up and only one was found and used for execution.

Credentials and Certificates

Tabs and Fields

Context Menu

Security

Credential Protocols

Credential Lookup

Partitions

Security with Credentials used in Processes

Credential Variations

The Secondary User Specification

The {forcejobowner} Specification

The {tryjobowner} Specification

The {virtual}: Modifier

Using the Same Process Definitions in Test and Production Environments

The {logoff} Modifier

Password Security

Login

Nis[+] and Microsoft Windows Domains

Logical Endpoints

Domain Tree Support

Example

HTTP Server Credentials

HTTP(S) Traffic via HTTP Proxy

Creating HTTP Server Credentials

Proxy Server Credentials

Examples

HTTP Server Credentials

Examples

Global Proxy Server Settings

SOAP Definitions

JDBC

Oracle

Example

ERP

Example

SAP_RFC

SOAP

Example Proxy Credential

SMTP

SSH

Examples

Archive_Server

X.509 Trusted Certificates

How Trusted Certificates are Used

X.509 Client Certificates

How Client Certificates Are Used

Creating X509 Trusted and Client Certificates using the API

Create X509 Trusted Certificate Credentials

Create X509 Client Certificate Credentials

Procedure

Create a Credential

Use a Credential

Values

Example of Process Definition Promotion Across Systems

Example Connecting to a Windows system

Troubleshooting

Example

See Also