Overview of AI agent chat security

You can embed the chat experience of AI agents or assistants directly into your web UI applications, this setup is known as an embedded agent or assistant. To secure communication between your application and the watsonx Orchestrate service, the embedded agent relies on public-key cryptography as its core security mechanism.

Default security behavior

Security is enabled by default, but is not configured. Until you configure it, the embedded agent will not work. Here's what you need to know:

  • The embedded agent is inactive until you complete the security setup.
  • Configure both IBM and client key pairs to enable secure communication.
  • Alternatively, you can disable security to allow anonymous access (not recommended for sensitive use cases).

Security architecture

Embedded agents use RSA public-key cryptography to secure data exchange between your application and the watsonx Orchestrate service. The architecture includes two key pairs and JWT-based authentication:

  1. watsonx Orchestrate key pair
  • The watsonx Orchestrate service generates the key pair.
  • watsonx Orchestrate shares the public key with your application.
  • Your application uses this public key to encrypt the user_payload section of the JSON Web Token (JWT).
  • The private key remains securely stored in the watsonx Orchestrate service.
  • The service uses the private key to decrypt the user_payload in incoming JWTs.
  1. Client key pair
  • You generate this key pair, either manually or by using a security configuration tool.
  • You share the public key with the watsonx Orchestrate service.
  • You keep the private key secure and use it to sign JWTs.
  • The service uses your public key to verify the JWT signature and confirm the request's authenticity.
  1. JWT authentication

When security is enabled, you must:

  • Generate a JWT signed with your private key.
  • Include the JWT in all requests to the embedded API.
  • Ensure that the watsonx Orchestrate service can validate the token by using your public key.

Security configuration options

You can choose between two configuration modes for the security of embedded agents:

Option 1: Enable security (recommended)

When you enable security:

  • Every request to the embedded API must include a valid JWT.
  • Sign the JWT with your private key.
  • The watsonx Orchestrate service validates the token by using your public key.
  • This setup prevents unauthorized access to your watsonx Orchestrate instance.

Option 2: Disable security

When you disable security:

  • Requests to the embedded API do not require authentication.
  • Anyone with access to your application can interact with your watsonx Orchestrate instance.
  • The service allows anonymous access to a limited set of APIs required for chat functionality.
  • Use this option only for specific scenarios where anonymous access is necessary.
  • Make sure that your watsonx Orchestrate instance does not expose sensitive data or tools with functional credentials.