Certificate Authentication for Client API Connections

Configuring API certificate authentication

The API connection certificate authentication feature allows clients to connect to a Connect:Direct server by using only an SSL Certificate with the Common Name (CN) specified as a user name. This feature improves password management in large deployments of Connect:Direct, as it removes the extra administrative steps that result from password usage.

If the intended client usage does not include submitting processes, then the user name does not have to be a real Windows system user name and only needs to be defined in the Connect:Direct Windows Functional Authorities. The API certificate authentication requires no user password to be presented.

Note: although it is possible for a Connect:Direct Administrator to create a user name for an API program that does not submit processes, identity management is simplified by using a standard identity supported by an internal Certificate Authority. For example, if the API program runs on UNIX and the internal CA issues certificates for UNIX system users, the user name (and certificate Common Name) could be the UNIX system user name under which the API program runs. Or, if the internal CA issues certificates for systems, the user name (and certificate Common Name) could be the DNS name of the API program's host system.

If the intended client usage does include submitting processes, consider one of the following options:
  1. When the user name specified in the Common Name is a real Windows system user, enable "Use Password Exit" in the Connect:Direct Windows Functional Authorities. The require user's password will be supplied by means of a password exit. See Password Exit and the CyberArk sample exit.
  2. Enable "Allow Process to run using Service Account" in the Connect:Direct Windows Functional Authorities to grant permission to run the process using the Connect:Direct Windows service account instead of the user specified in the Common Name. No password is needed. Since the service account is typically powerful on the Windows system, it is recommended to review the security implications.
  3. Use the PNODEID parameter in the Connect:Direct Process to specify a different user name for process execution. Then configure option (1) or (2) for this other user name, or specify its password within the PNODEID parameter (not recommended).
Note: This feature is specific only to API connections. These connections must also be AIJ-based. When you use the authentication feature, ensure that the version of the AIJ is at least 1.1.00 Fix 000025. This version of the AIJ contains updates that allow blank passwords to be used. These AIJ version requirements also apply if you use the authentication feature in IBM® Control Center. API connection certificate authentication is not supported for the Direct.exe CLI, IBM Connect:Direct Requester, or the Connect:Direct native C/C++/C# non Java APIs.