PingOne Privilege

Configuring AI gateways

The AI Gateway secures AI agent interactions for PingOne Privilege at a single enforcement point. It authenticates every caller, enforces policy at the tool, model, and agent boundaries, and injects backend credentials at runtime so agents never hold them. Every request and response is inspected for AI-specific threats, and all interactions are recorded in one audit trail.

PingOne Privilege allows you to add a AI Gateway using a setup wizard or through Docker.

Any user who uses personal agents through a AI Gateway must have an allow policy for that agent. This applies only when the personal agent calls agentic apps through a registered agent. Learn more in Registering an agent.

Configure an AI gateway using the setup wizard

Before you begin

You must create a new virtual machine (VM) to deploy the proxy container. Ensure the VM meets the required specifications for optimal performance and connectivity:

  • CPU: 4 vCPUs.

  • RAM: 16 GB.

  • Storage: 20 GB. Provision more storage if you deploy the MCP Catalog on this gateway.

  • Firewall Policy:

    • Outbound: Allow all traffic.

    • Inbound: Open the following ports:

      • 8623: AI clients to AI gateway

      • 8680: Endpoint Controller to AI gateway

      • 8690: Gateway to Gateway - Mesh Cluster

  • DNS: A DNS record for the gateway’s fully-qualified domain name (FQDN), so that AI clients can resolve the Gateway URL.

  • TLS certificate: Generate a TLS server certificate for the gateway FQDN and copy it to the gateway host. The wizard fills the Cert Path field with the default location.

  • Supported Operating Systems:

    • RHEL / CentOS (RPM x86_64)

    • Debian / Ubuntu AMD64

    • Debian / Ubuntu ARM64

Step 1: Create the OIDC web application in PingOne

  1. In the PingOne admin console, go to Applications > Applications.

  2. Click the Plus icon ().

  3. Enter an appropriate Application Name and optional Description.

  4. Under Application Type, click the OIDC Web App application type.

  5. Click Save.

    Result:

    The Overview panel for the application opens.

  6. On the Configuration tab, click the Pencil icon ().

  7. Configure the OIDC Settings:

    • Response Type: The default Code checkbox.

    • Grant Type: The default Authorization Code checkbox.

    • PKCE Enforcement: The default Optional option.

    • Redirect URI: The AI gateway’s server URL with /callback appended.

    • Token Endpoint Authentication Method: Select the Client Secret Post option.

  8. Click Save.

  9. Copy the Client ID and Client Secret values. You need them for configuring the AI Gateway in PingOne Privilege.

Step 2: Configure the AI gateway in PingOne Privilege

  1. In the PingOne Privilege admin console, go to Directory > Nodes.

  2. Click Add New, and then click Add via Wizard.

  3. Select AI GW as your deployment mode. Click Next.

  4. Review the requirements for your VM, then click Next.

  5. Install Docker based on the official Docker installation guide for your OS.

  6. Verify Docker is running using the following command in your CLI:

    sudo docker ps

    If the command runs without errors, Docker is ready to use.

  7. Enter a unique AI GW Name to identify the AI Gateway.

  8. Enter the FQDN / Host IP of the server where you installed the AI Gateway.

  9. Click Next.

  10. Enter the following fields:

    • AI GW Config fields:

      • Gateway URL: FQDN from the VM.

        This URL must include a port. The default gateway port is 8623.

      • Cert Path: The wizard fills this field by default.

      • Redis URL (Optional): Point the Gateway to your Redis URL.

      • OAuth Configuration (for MCP Clients): Checkbox selected by default. Clear the checkbox to disable OAuth configuration for MCP clients.

    • Fill in the following fields with information from the OIDC app created in PingOne:

      • Client ID: The client ID from the OIDC application configured in step 1.

      • Client Secret: The client secret from the OIDC application configured in step 1.

      • Auth URL: The authorization endpoint that starts the browser sign-on, for example, https://auth.pingone.com/<environment-id>/as/authorize.

      • Token URL: The token endpoint where the gateway exchanges authorization codes for tokens, for example, https://auth.pingone.com/<environment-id>/as/token.

      • User Info URL: The userinfo endpoint that resolves the user’s profile after sign-on, for example, https://auth.pingone.com/<environment-id>/as/userinfo.

      • User ID Claim: The token claim that identifies the user for policy and audit. Select sub from the list unless your OIDC application maps an email claim.

  11. Click Next.

  12. Create the environment file with the following commands:

    1. To create the directory, if not already present, run:

      sudo mkdir -p /var/lib/procyon

    2. To create the file and open it, run:

      sudo vi /var/lib/procyon/procyon-guest-agent.env

    3. Copy the generated content from your setup tasks and paste it inside the newly created file and save it.

    4. In the setup wizard, click Next.

  13. Select your operating system from the list. Click Show Instructions for the detailed steps for installing the package for your operating system.

  14. Click Finish.

Next steps

After adding the gateway, go to the Directory > Nodes page in the admin console. Your new AI Gateway should be listed with a Success status, typically within a minute of startup.

Configure an AI gateway using Docker

Before you begin

Ensure the following inbound ports are open on the host where you install the Gateway Mesh Cluster:

  • 8623: AI clients to AI gateway

  • 8680: Endpoint Controller to AI gateway

  • 8690: Gateway to Gateway - Mesh Cluster

Create a DNS record for the gateway host’s FQDN, so that AI clients can resolve the AI Gateway Server URL.

Step 1: Create the OIDC web application in PingOne

  1. In the PingOne admin console, go to Applications > Applications.

  2. Click the Plus icon ().

  3. Enter an appropriate Application Name and optional Description.

  4. Under Application Type, click the OpenID Connect (OIDC) (OIDC Web App) application type.

  5. Click Save.

    Result:

    The Overview panel for the application opens.

  6. Click the Configuration tab, then click the Pencil () icon.

  7. Configure the OIDC Settings:

    • Response Type: The default Code checkbox.

    • Grant Type: The default Authorization Code checkbox.

    • PKCE Enforcement: The default Optional option.

    • Redirect URI: The AI gateway’s server URL with /callback appended.

    • Token Endpoint Authentication Method: Select the Client Secret Post option.

  8. Click Save.

  9. Copy the Client ID and Client Secret values. You need them for configuring the AI Gateway in PingOne Privilege.

Step 2: Add the AI gateway in PingOne Privilege

  1. In the PingOne Privilege admin console, go to Directory > Nodes.

  2. Click Add New, and then click Add via Docker.

  3. Select AI GW.

  4. To generate a Docker command, fill in the following fields:

    • Cluster ID: A unique name for this gateway. You can’t change this after registration.

    • Host IP: The gateway host’s address. This field is informational only. Clients connect to the AI Gateway Server URL.

    • AI Gateway Server URL: The base URL that MCP clients call. The OIDC application’s Redirect URI must match this value, with /callback appended.

    • OAuth Configuration (for MCP Clients): Checkbox selected by default. Clear the checkbox to disable OAuth configuration for MCP clients.

    • OIDC Client ID: The client ID from the OIDC application configured in step 1.

    • OIDC Client Secret: The client secret from the OIDC application configured in step 1.

    • OIDC Auth URL: The authorization endpoint that starts the browser sign-on, for example, https://auth.pingone.com/<environment-id>/as/authorize.

    • OIDC Token URL: The token endpoint where the gateway exchanges authorization codes for tokens, for example, https://auth.pingone.com/<environment-id>/as/token.

    • OIDC User URL: The userinfo endpoint that resolves the user’s profile after sign-on, for example, https://auth.pingone.com/<environment-id>/as/userinfo.

    • User ID Claim: The token claim that identifies the user for policy and audit. Select sub from the list unless your OIDC application maps an email claim.

    • Redis URL (Optional): Point the Gateway to your Redis URL.

  5. Click Get Docker Command.

  6. Click Copy Docker Command to copy the command to your clipboard.

Step 3: Run the gateway container

The Docker command copied in step 2 is self-contained and performs the following actions:

  • Creates the gateway’s configuration directory.

  • Writes the configuration file with the values from the form.

  • Runs the container with a short-lived registration token.

Run the command promptly after copying it. If the registration token expires before the container starts, the container fails to register until you generate and run a new command.

The Docker command has the following shape, with your values filled in:

mkdir -p /var/lib/procyon/config

cat > /var/lib/procyon/config/pingone.env <<'EOF'
SERVER_URL=https://localhost:8623
OIDC_CLIENT_ID=<client ID from step 1>
OIDC_CLIENT_SECRET=<client secret from step 1>
OIDC_AUTH_URL=https://auth.pingone.com/<environment-id>/as/authorize
OIDC_TOKEN_URL=https://auth.pingone.com/<environment-id>/as/token
OIDC_USER_URL=https://auth.pingone.com/<environment-id>/as/userinfo
OIDC_SCOPES=openid profile email
USER_ID_CLAIM=sub
EOF

docker run -itd -e ENV_PROXY_TOKEN=<registration token> \
  --net=host --name privilege-aigw \
  -v /var/log/procyon:/var/log/procyon \
  -v /var/lib/procyon/config:/procyon/config \
  -v /var/lib/procyon/ssl:/procyon/ssl \
  -v /var/lib/procyon/recordings:/procyon/recordings \
  <gateway image> \
  /procyon/bin/mcpgw -mcpconfpath /procyon/config/pingone.env -hostname 127.0.0.1

On a Linux host, run the Docker command as-is.

On Docker Desktop for Mac:

  1. Replace --net=host with -p 8623:8623 -p 8680:8680 -p 8690:8690. Host networking publishes no ports on Docker Desktop.

  2. Replace the /var/…​ host paths with local paths, for example ~/pingidentity-local/…​. Docker creates any missing host directories automatically.

Result

Your new AI Gateway should be listed with a Success status on the Directory > Nodes page.

The Endpoint Controller doesn’t have automatic visibility into on-premise network topology. After deploying the gateway, you must manually configure which resources are accessible through it.

The gateway writes its log to /var/log/procyon/cyonproxy.log on the gateway host, not to the container console, so container logging commands show no output. A successful startup and registration show the following in the log:

  • MCP Gateway starting in TLS mode on :8623, the port MCP clients call.

  • A line confirming that the node established its command stream to the cluster.

You can also confirm that the gateway enforces authentication by calling the well-known endpoint without credentials:

curl -sk https://<gateway-url>:8623/.well-known/openid-configuration

An HTTP 401 response is expected: the gateway acts as an OAuth protected resource and rejects unauthenticated callers.

Troubleshooting the AI gateway

Symptom Cause Fix

The container exits immediately, and the log shows MCP Config path not specified

The gateway binary requires the configuration path argument.

Run the generated Docker command, or make sure the command points to the gateway configuration file using -mcpconfpath.

The log shows has same NodeURL …​ misconfigured Node

The Host IP makes the mesh see the node as its own peer.

Benign for a single-node deployment; registration still succeeds. Use a real host address on multi-node deployments.

The container restarts repeatedly after registration

The registration token expired before the container started.

Generate a new Docker command in the console, and run it promptly.

The log shows token contains an invalid number of segments

The registration token was pasted twice or was otherwise corrupted.

Generate a new Docker command in the console, and run it.

Clients receive HTTP 502 responses

The port clients call doesn’t match the port the gateway actually bound.

Find the port in the startup log line (MCP Gateway starting in TLS mode on …​), and use that port in client URLs.

Sign-on fails, and the log shows userinfo …​ yielded an empty user ID

The User ID Claim references a claim the OIDC application doesn’t return.

Generate a new Docker command with the correct claim, typically sub, and run it.

The log shows a transient Failed to find the tenant at startup

The tenant cache is cold in the first seconds after boot.

Ignore it if the node establishes its command stream immediately after.