Managing authentication using API Keys

Learn what API Keys are and how they can secure authentication quickly and easily.

API Keys provide a secure authentication method based on a JSON Web Token (JWT) generated and stored by HCL Universal Orchestrator. This authentication method provides a number of advantages, such as:
  • Central repository for all platforms and for multiple configurations.
  • Improved user experience when setting up the Orchestration CLI.
  • API Keys life cycle completely managed using Orchestration CLI.
  • Easier problem solving when authentication problems occur.

Before you begin

Ensure you have completed the following tasks:
  • You have installed an OpenID Connect (OIDC) provider and configured HCL Universal Orchestrator to work with it. To configure HCL Universal Orchestrator, fill in the relevant properties in the values.yaml file available for HCL Universal Orchestrator deployment. Comments are available in the values.yaml file to explain all properties.
  • After accessing the product for the first time, configure administrative roles based on your requirements. For more information, see Managing Workload Security.

Issuing API Keys

You can issue API Keys using one of the following methods:
  • Using the UI, as described in Managing API Keys from the UI.
  • Using the REST APIs, as described in the documentation available at 
    https://hostname:port/q/swagger-ui/#/
    , where
    hostname
    is the host name of the HCL Universal Orchestrator gateway.
    port
    is the port used by the HCL Universal Orchestrator gateway.
  • Using the command line, as described in Authenticating Orchestration CLI using API Keys.

You can view the API Keys using the ocli model list apikey command. For more information, see list.

If an API Key is about to expire or has expired, a warning message is displayed in the command line, together with a link to generate a new API Key.

Cross Dependencies API Keys

To authenticate bind calls between different orchestration engines, you must use a specific Cross dependencies API Key type. This API Key type is designed exclusively for cross-engine orchestration and has unique behaviors and security scopes:

  • Folder restriction: When creating the key, you must define a specific folder. This restricts the workflows that can be targeted when sending binding requests using this API Key.
  • Workstation for notifications: You must define a workstation, which is used by the remote engine to send back status notifications. If the selected workstation is a pool, a member of that pool is dynamically selected when sending notifications.
  • Permissions: This API key is not bound to a specific user and does not support group assignments. It automatically grants LIST and DISPLAY access to workflows in the selected folder, and LIST access to folders from the selected folder.
    Note: Cross dependencies API Keys are valid only for HCL Universal Orchestrator to HCL Universal Orchestrator connections. The API Key must be created on the remote engine and used on the local engine where the shadow task is defined.

Revoking agent authorization

To revoke authorization for an agent to register and connect with HCL Universal Orchestrator, perform the following steps:

  1. Remove the REGISTER_AGENT administrative permissions from the ACLs for the user who installed the agent or the user who created the API Key used to register the agent. You can perform this operation from the Orchestration CLI, as described in Managing access control lists from the Orchestration CLI.
  2. Delete the API Key.
You can delete the API Key from the UI or from the command line. To delete the API Key from the command line, perform the following steps:
  1. Open a shell session.
  2. Launch the ocli model script.
  3. Run the following command:
    ocli model delete apikey Label
    where
    Label
    is the name of the API Key you want to delete.

For more information about the delete command, see delete.

From the UI, you can perform the same operation as follows:
  1. Log in to the UI.
  2. Click on the User icon in the upper right corner.
  3. Select Settings.
  4. Go to the Security tab and select API Key.
  5. Select the API Key to be deleted.
  6. Click on the Delete icon.

After revoking the agent authorization, you can register the agent again by creating a new API Key, as explained in Issuing API Keys.