Skip to main content
Version: Developer

Grant access with kziti

Overview​

A kziti-managed OpenZiti deployment isolates resources by default, so an identity reaches nothing until you grant it access. This guide grants a Kasm user, workspace, or external identity access to a network, a service set, or a single service. You choose the narrowest scope that satisfies the requirement, confirm who can reach each resource, and revoke access when it is no longer needed. As a result, the deployment enforces least-privilege egress while you retain a clear, auditable view of every grant. For the underlying model, see kziti architecture.

Prerequisites​

Before you begin, confirm the following:

  • A configured kziti profile that authenticates against your OpenZiti controller. See Configure kziti.
  • At least one published network, service set, or service to grant access to. See Manage networks with kziti and Publish services with kziti.
  • The identity name you intend to grant, such as a Kasm user email, a workspace name, or an external user identifier.

Solution approach​

This guide progresses through the following phases:

  1. Find the identity.
  2. Choose the access scope.
  3. Grant access.
  4. Audit existing grants.
  5. Revoke access.

Detailed steps​

Find the identity​

  1. If you know the identity name, use it directly. The name can be a Kasm user email, a workspace name, or an external user identifier.

  2. To browse every identity, list them.

    kziti identity list

  3. To narrow the list, search by substring or attribute.

    kziti identity search 'name contains "alice"'

Kasm-managed identities have predictable names like kasm-user-<username>-<user-id-prefix>-<provider-id-prefix> and kasm-workspace-<workspace>-<image-id-prefix>-<provider-id-prefix>.

Choose the access scope​

kziti access grant accepts three kinds of resource ID, in order of decreasing breadth:

  • A network ID (e.g. net-corp-a) — the identity gains access to every service in the network.
  • A service set ID (e.g. svcset-devops) — access to every service in the named set.
  • A service ID (e.g. svc-corp-a-gitlab) — access to a single service only.

Pick the narrowest scope that satisfies the requirement. Service-set grants are the common middle ground for groups of users who need access to a coherent set of services.

Grant access​

  1. To grant access to an entire network, pass the network ID.

    kziti access grant alice@example.com net-corp-a

  2. To grant access to a service set, pass the service set ID.

    kziti access grant alice@example.com svcset-devops

  3. To grant access to a single service, pass the service ID.

    kziti access grant alice@example.com svc-corp-a-gitlab

Each grant adds the resource ID as a role attribute on the identity. The grant takes effect immediately for new sessions. Existing tunnels may need to reconnect.

Audit existing grants​

  1. To list every grant an identity holds, pass the identity name.

    kziti access list alice@example.com

    The output shows each access role attribute the identity holds (net-*, svcset-*, or svc-*), with a human-readable description of what it covers.

  2. To see the inverse view, run access who against a resource. The command shows every identity that can reach that resource.

    # All identities with access to the corp-a network
    kziti access who net-corp-a

    # All identities with access to a service set
    kziti access who svcset-devops

    # All identities with access to a single service
    kziti access who svc-corp-a-gitlab

    access who accepts the same resource IDs as grant and remove. For each matching identity, the output shows the name, the type (Kasm user, workspace, or external), and whether it currently has an active session. Use -o json (the global --output-format flag) for machine-readable output.

Revoke access​

  1. Revoke access using the same scope you used to grant it.

    kziti access remove alice@example.com svcset-devops

remove strips the role attribute immediately for new dial attempts. Existing tunnels are not torn down. To terminate live sessions for a compromised identity, revoke the workspace mapping in Kasm to remove the identity entirely.

Common troubleshooting steps​

  • A grant does not take effect on an existing tunnel. A new grant applies immediately to new sessions, but established tunnels may need to reconnect. Reconnect the affected tunnel.
  • Access persists after a remove. remove stops new dial attempts but does not tear down live tunnels. For a compromised identity, revoke the workspace mapping in Kasm to remove the identity entirely.
  • The identity name is not found. Confirm the exact name with kziti identity list or kziti identity search. Kasm-managed identities follow the kasm-user-... and kasm-workspace-... naming patterns.
  • A grant covers more than intended. A network ID grants access to every service in the network. Revoke the broad grant, then re-grant a service set ID or a single service ID to apply the narrowest scope.