Integrated authorization with multi‑SAF support

SAF provides secure, policy-driven access to z/OS resources for agent-initiated requests using token exchange.

End-User Flow

Consider the following scenarios:

As a system administrator or developer, I want to expose z/OS service configuration details to agents through a RESTful API, so that configuration settings can be dynamically created, retrieved, updated, and deleted for different agents and contexts without requiring application redeployment.
As an enterprise user, I want to interact with backend z/OS systems through the watsonx Assistant for Z chat interface in a simple, conversational manner, so that I can seamlessly access services.

From the user’s perspective, the experience is simple and conversational. The user does not need to manage multiple credentials or understand backend complexities.

Behind the scenes, the system securely processes the request using the Token Exchange Service (TES), which plays a critical role in enabling controlled access to z/OS systems.

The user logs in to watsonx Orchestrate and navigates to the chat interface.
Agent receives the authenticated user context (email ID).
The token exchange service generates a one-time PassTicket for the user based on configured policy mappings.
Agent invokes the z/OS service using the PassTicket.
z/OS service validates the PassTicket and performs the operation.

TES architecture and deployment models

The following diagram illustrates the TES architecture:

The architecture connects a watsonx Orchestrate service instance (tenant) to multiple z/OS systems using context-based connections defined by user-provided keys (such as SYS_A and SYS_B). Each connection routes requests to a dedicated Token Exchange Service (TES) instance deployed in a specific environment.

Each TES instance runs as a Liberty application and generates PassTickets locally using SAF, ensuring system-level isolation and compliance with enterprise security policies.

TES is deployed independently in each monoplex or sysplex environment. Each deployment is self-contained and operates without dependencies on other systems. Each system (sysplex or monoplex) hosts its own TES instance. This ensures local availability, isolates failures, and eliminates cross-system dependencies.

Setting up the configuration for agents to support multi-SAF

Configure multi-SAF support by providing the agent ID, context key, and configuration settings in JSON format.

{
  "agent_id": "agent_id",
  "context": "unique-key",
  "config": {
    "key": "value",
    "key2": "value2"
  }
}

Parameter	Description	Type	Is this parameter mandatory?
agent_id	Unique identifier for the agent.	String	Yes
context	Unique context key for configuration isolation.	String	Yes
config	Key-value pairs containing configuration settings.	Object	Yes

Setting up the connection for agents to support multi-SAF

To optimize LPAR selection by an agent, focus on context. By implementing a context-driven or tag-driven selection process, agents can dynamically access multiple LPARs based on specific criteria that align with their intended use or operational requirements.

When handling agent subscriptions and ensuring secure interactions with multiple LPARs (Logical Partitions), collect and use relevant context information. The following codeblock outlines a structured solution for agent configuration and context management.

{
    "tenant_id": "string //Unique identifier for the tenant requesting the agent",
    "agent_id": "string Unique identifier for the agent",
    "authz": [
        {
          "zos_url": "string //URL of the z/OS system where passticket service is running",
          "port": "string //Port number for the z/OS system",
          "context": "string //Context for the z/OS system",
          "client_cert": "string //Client certificate for the passticket   service",
          "client_key": "string //Client key for the passticket service"               
        }
    ]
}