Configuring security with scripting

Edit online

You can alternatively use the security tool to programmatically configure security for the 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.

To configure security through the UI, see the instructions in the Configuring security for embedded chat topic.

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.

Important:

Never commit private keys to source control. Store client_private_key.pem securely by using your organization’s secrets management solution.