Configuring security for embedded chat

Security for embedded chat is enabled by default at the instance level, but it is not active until you explicitly configure the required cryptographic assets and register them with your instance. You might be able to see the chat widget in the web application, but it does not initialize until this configuration is completed successfully.

This procedure assumes that you understand public and private key cryptography and are responsible for securely managing private keys in your deployment environment. Before you begin configuring security, it is helpful to understand the underlying security concepts. For more information, see Securing the embedded chat.

Prerequisites

Before you begin, ensure that you meet the following requirements:

  1. System requirements
  • macOS or Linux only:
    • OpenSSL installed locally (used to generate client-side key pairs)
  • Python installed on your system
    • Required for extracting and processing keys that are returned from the watsonx Orchestrate APIs
  1. Product-specific requirements
  • An active watsonx Orchestrate instance.
  • The service instance URL.
  • Deployment credentials with administrative privileges to register security artifacts:
Deployment Credentials
IBM Cloud Pak for Data
IBM Software Hub		 Username and password
Amazon Web Services (AWS)
AWS GovCloud (US)		 API key
IBM Cloud API key

Configuring security

Use the security tool to configure security for the embedded chat. The tool supports the following actions:

  • Configure security with newly generated keys.
  • Configure security by using an existing client public key.
  • Disable security to allow anonymous access.
  • View the current security status.
  • View the current configuration.

Step 1. Download the security tool

Click the following link to download the security tools:

Download the security tools here ↓

The ibm-watsonx-orchestrate-embed-chat-security-tools.zip folder contains scripts for instances on the following deployments:

  • Amazon Web Services (AWS) (wxo-embed-security-aws-macos-linux and wxo-embed-security-aws-windows)
  • AWS GovCloud (US) (wxo-embed-security-hipaa-macos-linux and wxo-embed-security-hipaa-windows)
  • IBM Cloud (wxo-embed-security-ibmcloud-macos-linux and wxo-embed-security-ibmcloud-windows)
  • IBM Cloud Pak for Data and IBM Software Hub (wxo-embed-security-onprem-macos-linux and wxo-embed-security-onprem-windows)

Run the script that corresponds to your instance’s deployment.

These scripts orchestrate all the required API calls and local cryptographic operations that are needed to enable embedded chat security, such as:

  • Communication with watsonx Orchestrate APIs.
  • Creation of an IBM-managed key pair.
  • Generation of a client-owned key pair locally.
  • Registration of the corresponding public keys with your service instance.

Step 2. For macOS and Linux devices: Update script permissions

On Unix-based systems, you must mark the script as executable before you run it:

chmod +x <script_name>.sh

Where:

  • <script_name>
    Replace with the name of the script that you need to run based on your instance's deployment, for example, "./wxo-embed-security-aws-macos-linux.sh".

Step 3. Run the security tool

Run the script and follow the interactive prompts to configure security:

./<script_name>.sh

Where:

  • <script_name>
    Replace with the name of the script that you need to run based on your instance's deployment, for example, "./wxo-embed-security-aws-windows.sh".

During execution, the script prompts you for required inputs such as:

  • Service instance URL.
  • Administrative API key.
  • User and password for On-premises instances.
  • Action to run.
Tip:If it is your first time configuring security, select action 1 to configure security with newly generated keys.

Results

When the script completes successfully, the following actions occur automatically:

  • An IBM-managed key pair is generated through the watsonx Orchestrate API.
  • A client-owned key pair is generated locally by using OpenSSL.
  • Both public keys are registered with the watsonx Orchestrate service.
  • Embedded chat security is enabled for your instance if you run actions 1 or 2 from the tools.

This configuration enforces authenticated, signed communication between your embedded client and watsonx Orchestrate.

Generated security artifacts

All generated keys and configuration artifacts are stored locally in the wxo_security_config directory:

  • ibm_public_key.pem IBM’s public key in PEM format.
  • client_private_key.pem Your private key. You must treat it as a secret and restrict access.
  • client_public_key.pem Your public key in PEM format.
Security note:Never commit private keys to source control. Store client_private_key.pem securely by using your organization’s secrets management solution.