Storing Credentials and Certificates
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 specify the user, domain (if applicable) and password in the process definition Run As User field directly, or you leave out the password and look the password up using a separate credentials object. In the latter case, if the password of a user changes, you change it on the credential, which takes effect immediately; if you had specified the user explicitly on process definitions, you would have to change the password on every process definition manually, which is error-prone, or use RedwoodScript, which can become complex.
Credentials also increase security since they allow you to separate who can use the credential from those who know the password. The person that creates or modifies the credential needs to know the password. This person or an administrator can then pass the right to use the credential to other persons who can then create process definitions or submit processes using that credential without knowing the password.
Credentials are part of the Security section of the navigation bar.
note
Redwood strongly recommends the use of credentials over specifying a password in the Run As User field, in parameters, or on the command line.
Tabs & Fields
The following table illustrates the fields of each tab of Credentials editor window.
| Tab | Field | Description |
|---|---|---|
| Credential | Partition | Partition of the credential. |
| Credential | Protocol | Protocol for the credential. |
| Credential | Endpoint | The target system for the credential. |
| Credential | Real User | Actual user name. |
| Credential | Password | The password, usually case sensitive, retype for safety. |
| Credential | Retype Password | |
| Credential | Virtual User | The virtual username to be across test, development, and production. |
| 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. |
Context-Menu
Credentials support the following context-menu actions:
| Action | Description |
|---|---|
| Edit Security | Edit the security of the credential |
| Delete | Delete the credential |
| Edit | Edit the credential |
| Show permalinks | Show links that can be used from third party credentials to link to the object |
| New credential | Create a new credential |
| Filter > New Filter | Create a new credential filter |
| Filter > Edit Filter | Edit current credential filter |
| Filter > Delete | Delete current credential filter |
| Filter > Duplicate Filter | Create a copy of the filter |
| Filter > Export Filter | Export the filter into a CAR file |
| Filter > Add to navigation bar | Add the filter to a navigation bar |
| Filter > Create filter from search | Create a filter from the current IntelliSearch query |
Security
To use a credential, the user must have sufficient privileges, like 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 | Access credentials |
You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted per partition or system-wide.
You specify which users can access, edit, and delete the credential on the Security tab of the credential.
note
Please be very careful when you create credentials, 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
The following credential protocols are available:
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, Redwood Server retrieves the credential password by searching for a credential 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, or if that is empty or does not exist the Run as User field or if that is empty the DefaultRunAsUser process server parameter.
The Endpoint attribute comes from the JCS_ENDPOINT, or if that is empty or does not exist 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; the 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 that then uses this information to log into the external service.
When this 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_USERorJCS_REMOTE_USERprocess parameter.JCL_FTP_USERorSQLPLUS_USER, for JCL_FTP and SQLPLUS definition types only.- Run As User or Remote Run As User fields.
DefaultRunAsUserprocess server parameter.
The endpoint is evaluated in the following order (first found wins) for processes:
JCS_ENDPOINTorJCS_REMOTE_ENDPOINTprocess parameter.JCL_FTP_ENDPOINTorSQLPLUS_ENDPOINT, for JCL_FTP, and SQLPLUS definition types only.- Run As User or Remote Run As User field.
EndPointprocess server parameter.RemoteHostNameprocess server parameter.
Note that JCS_USER behaves differently on Windows in Redwood Server version 9 than did JCS_NTUSER in 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
GLOBALpartition.
Note that this was introduced in 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 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 by a colon ':' character. The first field, the Try User will be tried first. If this user exists (and the password validates) then 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
When you encode the {forcejobowner} in the Run As User field then the system will log in as the Redwood Server process owner. If this fails the process is put into the Error status.
The {tryjobowner} Specification
When you encode the {tryjobowner} in the Run As User field then the system will log in as the Redwood Server process owner. If this fails the system will use any second user specification or failing that 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 although their username and password are different. When the process gets allocated to a process server, Redwood Server retrieves the credential by searching 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.
You 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, 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 |
Example
Credential for Processes Running on Process Server GLOBAL.MSLN_WINS3, a Platform Agent Running on 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:
jdoejdoe@pr1.example.compr1.example.com\jdoe{virtual}:operator
Credential for Processes Running on Servers of the Example Domain Named pr1.example.com, pr2.example.com, pr3.example.com, exc1.example.com, 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@exampleexample\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
Credential for 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 |
Credential for 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; you can set the encryption mechanism for new passwords to AES SecureStorage encryption using the System_SecureStorage_Configure process definition. Note that 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. You enable Externally Available (ExternallyAvailable) on the credential to allow users to access the credential password. 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 the password using either of these methods:
- RedwoodScript method
SchedulerSession.unprotectPassword(String), which takes a protected password as returned byCredential.getProtectedPassword()as argument - jtool echo
You restrict who can change the ExternallyAvailable property by activating the Externally_Available_Credential global privilege and granting it to the users/roles who should be allowed to.
Login
The login credential is used to login to platform agents. You 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 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> of 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" then for "jdoe@.dev.example.com", then ".example.com" then ".com" then "". Note that this slows down the lookup somewhat, because a full lookup is done for each asterisk (*); in this example, it will have done 4 lookups if you only specified a credential with Endpoint *.com, 7 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 pro-actively: authentication data is already sent on the first request, because it is known that this 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 as it might be used in multiple servers (with the same login database) so it is easier to administrate. In others 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 - Redwood 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
Choose "Security > Credentials" in the navigation bar to use Redwood credentials to specify proxy server settings.
Two types of HTTP credentials are available:
- proxy server credentials
- 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
Not recommended by Redwood.
If you have a single HTTP proxy, then the Redwood Server 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 running in the Redwood Cloud, you can set these by setting Redwood Server registry entries of 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. Default is3128.proxyuser= Username to authenticate with at the proxy.proxypassword= Password to authenticate with at the proxy.nonproxyhosts= List of hostnames to contact directly. Default islocalhost,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.
Example
You want to connect process server MSLN_ORA01 to your Oracle database named ORCL on server ora1.example.com
Credential:
| 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 |
You 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
You 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 as 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, 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, it 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
| 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 used 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); to this effect.
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, merely 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, 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:
${JCS_SSH_USER:=${remoteUser}} ${JCS_SSH_HOST:=${remoteHost}} ssh -i ${HOME}/.ssh/id_dsa -T ${remoteUser}@${remoteHost} uname
Or this can be shortened as ssh prefers to use publickey 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.
Password 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.
Passphrase 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.
Password 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}:.
Following is an example of a server password being resolved by a credential.
Password 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 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 instance, if the URL is https://client.example.com/path then 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 asBag 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 then 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, then 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 instance, 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 then 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 systemqa1adm- quality assurance systemdv1adm- 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 as in each system, the correct user is used to execute the code.
Example Connecting to a Windows system
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 as this:
user1/password1@domain:localuser/password@computername
Troubleshooting
The System_CredentialTrace process definition allows you to troubleshoot credential lookups. You 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 as two credentials were specified, both credentials were looked up and only one was found and used for execution.
See Also
Credential password Run as User RunAsUser