zscaler/zscaler-mcp-server/application-segment-pra-onboard

ZPA: Onboard Privileged Remote Access (PRA) Application

Keywords

privileged remote access, pra, rdp access, ssh access, jump host, bastion host, jumpbox, pra portal, pra credential, agentless rdp, agentless ssh, browser rdp, browser ssh, secure remote access

Overview

Onboard a new Privileged Remote Access (PRA) application in Zscaler Private Access. PRA segments publish RDP and SSH targets to authorized users through Zscaler's PRA portal — the end user connects through their browser without a native RDP/SSH client and without ZCC. The connection is brokered by the PRA portal and authenticated using PRA credentials managed as separate ZPA resources.

This skill walks through the full dependency chain: connector group → server group → segment group → PRA credential → PRA portal → PRA application segment with `apps_config` → access policy rule.

Use this skill when: The admin explicitly mentions Privileged Remote Access, PRA, RDP, SSH, jump host, bastion, or "publish a Windows/Linux server for browser-based remote access."

DO NOT use this skill when:

• The admin wants a regular client-routed application segment (any TCP/UDP app reachable via ZCC) — use zpa-application_segment-onboard instead.
• The admin wants to publish a clientless web application — use zpa-application_segment-ba-onboard instead.

What makes PRA different from a regular or BA app segment

The biggest source of PRA onboarding mistakes:

1. Forgetting to create / select a PRA portal users will connect to.
2. Forgetting to create / select a PRA credential for the target host.
3. Putting connection_security on an SSH app — it's RDP-only.
4. Forgetting that the same domain in apps_config[].domain must also appear in the segment's domain_names.

The zpa_create_application_segment_pra tool validates #3 and #4 client-side.

Workflow

Follow this 8-step process for complete PRA application onboarding.

Step 1: Gather Application Details

Collect the following from the administrator:

Required:

• Application name (e.g. "DC1 Jump Hosts", "Linux Bastions")
• One or more target host FQDNs / IPs (e.g. rdp01.acme.com, bastion.acme.com)
• Protocol per target: RDP or SSH
• Port per target (almost always 3389 for RDP, 22 for SSH)
• For RDP targets: desired connection_security mode — ANY is the safe default, NLA if Network Level Authentication is required
• Who should have access (users, groups, or departments)
• The credential users will authenticate to the target with (username + secret)

Optional:

• Description and purpose of the application
• Geographic location of the target servers
• Whether to reuse existing ZPA resources (connector groups, server groups, segment groups, PRA portals, PRA credentials)
• Health check requirements

If the admin says "I want users to RDP/SSH to my servers without installing anything" — this is PRA. If they say "I want users on ZCC to reach an internal API" — stop and use `zpa-application_segment-onboard` instead. If they say "publish my intranet website to the browser" — stop and use `zpa-application_segment-ba-onboard` instead.

Step 2: Set Up App Connector Group

Check for existing connector groups or create a new one. The same connector groups are used by regular, BA, and PRA segments — there is no PRA-specific connector group.

List existing:

zpa_list_app_connector_groups()

Create if needed:

zpa_create_app_connector_group(
  name="<location>-Connectors",
  description="Connectors serving <application_name>",
  enabled=True,
  latitude="<lat>",
  longitude="<lon>",
  location="<datacenter_or_office>",
  country_code="<country>"
)

The create tool already resolves the tenant's enrollment certificate ID automatically.

Save the connector group id for the next step.

Step 3: Set Up Server Group

Check for existing server groups or create a new one.

List existing:

zpa_list_server_groups()

Create if needed:

zpa_create_server_group(
  name="<application_name>-Servers",
  description="Server group for <application_name>",
  app_connector_group_ids=["<connector_group_id>"],
  enabled=True,
  dynamic_discovery=True
)

Save the server group id for Step 7.

Step 4: Set Up Segment Group

Check for existing segment groups or create a new one.

List existing:

zpa_list_segment_groups()

Create if needed:

zpa_create_segment_group(
  name="<application_grouping>",
  description="Segment group for <application_grouping>",
  enabled=True
)

Save the segment group id for Step 7.

Step 5: Set Up the PRA Credential

A PRA credential carries the username + secret used to authenticate the user into the RDP/SSH target host. PRA brokers the connection but the target still needs a real OS-level credential.

List existing PRA credentials:

zpa_list_pra_credentials()

Pick one if a suitable shared credential already exists (e.g. an Active Directory service account that can RDP to all jump hosts, or a sudo-capable user on the SSH bastions).

Create if needed:

zpa_create_pra_credential(
  name="<descriptive-name>",
  description="<purpose>",
  credential_type="USERNAME_PASSWORD",  # or PASSWORD, SSH_KEY, etc.
  user_domain="<AD_domain_if_RDP>",
  username="<account>",
  password="<secret>"
)

Save the credential id for Step 8 (it gets referenced by the access policy rule, NOT by the segment itself).

Note: Don't put real secrets into a chat. Confirm the credential storage path with the admin and have them create or paste the secret directly into the tenant if needed.

Step 6: Set Up the PRA Portal

A PRA portal is the URL endpoint users navigate to in their browser to launch a PRA session. One portal can serve many PRA segments; reuse an existing portal if one already exists.

List existing PRA portals:

zpa_list_pra_portals()

Create if needed:

zpa_create_pra_portal(
  name="<portal-name>",
  domain="<portal.example.com>",
  enabled=True,
  certificate_id="<ba_or_pra_tls_certificate_id>",
  user_notification_enabled=True,
  user_notification="Welcome to <company> Privileged Remote Access"
)

The portal needs a TLS certificate covering its domain (look up via zpa_list_ba_certificates — BA certs and PRA portal certs come from the same store).

Save the portal id for Step 8 (also referenced by the access policy rule).

Step 7: Create the PRA Application Segment

This is the PRA-specific segment step. The apps_config block is required and must list one entry per RDP/SSH target. Every apps_config[].domain must also appear in domain_names.

RDP example (most common — TCP 3389 + UDP 3389):

zpa_create_application_segment_pra(
  name="DC1 RDP Jumpboxes",
  description="Windows jump hosts in DC1",
  enabled=True,
  segment_group_id="<segment_group_id>",
  server_group_ids=["<server_group_id>"],
  domain_names=["rdp01.acme.com", "rdp02.acme.com"],
  tcp_port_range=[{"from": "3389", "to": "3389"}],
  udp_port_range=[{"from": "3389", "to": "3389"}],
  apps_config=[
    {
      "name": "rdp01",
      "domain": "rdp01.acme.com",
      "application_port": "3389",
      "application_protocol": "RDP",
      "connection_security": "ANY",
      "enabled": True
    },
    {
      "name": "rdp02",
      "domain": "rdp02.acme.com",
      "application_port": "3389",
      "application_protocol": "RDP",
      "connection_security": "ANY",
      "enabled": True
    }
  ],
  bypass_type="NEVER",
  health_check_type="DEFAULT",
  health_reporting="ON_ACCESS"
)

SSH example (TCP 22 only — no UDP, no connection_security):

zpa_create_application_segment_pra(
  name="Linux Bastions",
  description="SSH bastion hosts",
  enabled=True,
  segment_group_id="<segment_group_id>",
  server_group_ids=["<server_group_id>"],
  domain_names=["bastion.acme.com"],
  tcp_port_range=[{"from": "22", "to": "22"}],
  apps_config=[
    {
      "name": "bastion",
      "domain": "bastion.acme.com",
      "application_port": "22",
      "application_protocol": "SSH",
      "enabled": True
    }
  ]
)

Hard rules enforced client-side by the tool:

• Every apps_config[].domain MUST appear in domain_names.
• application_protocol MUST be "RDP" or "SSH".
• connection_security is RDP-only — supplying it on an SSH app is rejected. Allowed values: ANY, NLA, NLA_EXT, TLS, VM_CONNECT, RDP.
• Required per-app keys: name, domain, application_port, application_protocol.
• At least one of tcp_port_range / tcp_port_ranges / udp_port_range / udp_port_ranges must be supplied.

Save the segment id for Step 8.

Step 8: Create the Access Policy Rule

Grant access to the PRA segment, binding the PRA credential and PRA portal to the rule.

Look up the requesting principals:

zpa_list_segment_groups()        # confirm segment group ID
zpa_list_user_groups()            # for group-based access
zpa_list_idp()                    # find the IDP backing the criteria
zpa_list_scim_groups(idp_id="<idp_id>")  # for SCIM group-based criteria

Create the access rule:

zpa_create_access_policy_rule(
  name="Allow <user_group> to <application_name> (PRA)",
  description="Privileged Remote Access for <application_name>",
  action="ALLOW",
  conditions=[
    {
      "operands": [
        {"object_type": "APP", "values": ["<pra_segment_id>"]}
      ]
    },
    {
      "operands": [
        {
          "object_type": "SCIM_GROUP",
          "entry_values": [
            {"rhs": "<scim_group_id>", "lhs": "<idp_id>"}
          ]
        }
      ]
    }
  ],
  credential_id="<pra_credential_id>",
  console_ids=["<pra_portal_id>"]
)

The operand type for a PRA segment is the same APP operand used for regular and BA segments — the policy engine doesn't distinguish. The PRA-specific binding lives in credential_id (which credential to inject into the session) and console_ids (which portal to launch the session from).

Validation

After completion, confirm:

Resource creation:

zpa_get_application_segment_pra(segment_id="<pra_segment_id>")
zpa_get_segment_group(group_id="<segment_group_id>")
zpa_get_server_group(group_id="<server_group_id>")
zpa_get_app_connector_group(group_id="<connector_group_id>")
zpa_get_pra_credential(credential_id="<pra_credential_id>")
zpa_get_pra_portal(portal_id="<pra_portal_id>")

The get_application_segment_pra response should include common_apps_dto.apps_config populated with each RDP/SSH target, port, protocol, and (for RDP) connection_security.