How-to Allow Boundary Users to View Targets in the Client Desktop App

Avatar
Clayton Platt
  • Updated

Introduction

It is common to notice a recently created user cannot view targets in the Boundary client desktop.  In such instances, it is likely that their permissions on a particular resource are missing the authorize-session action.  This is because the Boundary desktop will only show targets that the credentials have permission to connect to.  In other words, if a non-admin user is not granted the permission to connect to the target (via authorize-session action) it is impossible for that user to view that target in the desktop app.

In this article, we demonstrate how to add the authorize-session action by assigning the necessary grant string to the user's role.  Grant strings are the mechanism by which we can allow or "grant" users various actions to Boundary's resources (including viewing and connecting).

Though viewing/connecting to a target resource via the desktop app is discussed here, this concept can also be extended to viewing any resources (from this list) via the Admin UI (accessed by entering your controller's dns into the browser).  If for instance, a user is unable to view his own role in the admin UI, that user's role likely needs to grant list/read actions on role resources.

Expected Outcome

Observe a test user's credentials in the Boundary desktop app go from being unable to view a Boundary target, to being able to list/read/connect to it.

Prerequisites

  • familiarity with boundary scopes (project level scope, specifically)
  • familiarity with grant string components
  • browse through Boundary's resource table
  • admin access to Boundary CLI
  • access to a boundary desktop client application, connected to the same controller as the CLI 

  • (optional) a target id for a target that you would like the user to connect to:

    # view all targets by id
boundary targets list -recursive
  • a valid role id from a role in the same project as the target in-question, whose members (principals) include the user in question, or a group containing the user
# view all targets by id
boundary roles list

# read role to confirm user/group is member, see user id under 'Principals'
boundary roles read -id r_wfmaMMT4Qu
Direct usage of BOUNDARY_TOKEN env var is deprecated; please use "-token env://<env var name>" format, e.g. "-token env://BOUNDARY_TOKEN" to specify an env var to use.

Role information:
  Created Time:        Thu, 02 Oct 2025 15:59:33 PDT
  Description:         testing of targets visibility
  ID:                  r_wfmaMMT4Qu
  Name:                target-viewier
  Updated Time:        Thu, 02 Oct 2025 16:06:32 PDT
  Version:             5

  Scope:
    ID:                p_8qvHOatrkH
    Name:              Generated project scope
    Parent Scope ID:   o_E3JZNdMu0a
    Type:              project

  Authorized Actions:
    add-grant-scopes
    set-grant-scopes
    remove-grant-scopes
    delete
    add-principals
    remove-principals
    remove-grants
    read
    update
    set-grants
    no-op
    set-principals
    add-grants

  Principals:
    ID:             u_EjYY8wPrvW
      Type:         user
      Scope ID:     o_E3JZNdMu0a

  Grant Scope IDs:
    ID:             this

Use Case

For a Boundary user who cannot view their intended targets in the client desktop app.

Procedure

  • in the Boundary CLI: ensure authenticated with admin creds

  • in the Boundary desktop (client app), ensure authenticated with affected user's creds

  • confirm this user cannot view targets in the client app (shows No Targets Available)

  • using the role and target IDs from above, run the following commands to add the necessary grant strings to the user's role (command to remove unwanted grant string is also included for reference):

# allow users in role to see and read all targets in their project
boundary roles add-grants -id <role_id> -grant "ids=*;type=targets;actions=authorize-session"

# limit to only view a particular target in project by ID
boundary roles add-grants -id <role_id> -grant ids=<target_id>;actions=authorize-session

# example to cleanup unwanted grant strings
boundary roles remove-grants -id <role_id> -grant "ids=*;type=targets;actions=authorize-session"

  • role will now show grant string added

boundary roles add-grants -id r_wfmaMMT4Qu -grant "ids=*;type=target;actions=authorize-session"

Role information:
  Created Time:        Thu, 02 Oct 2025 15:59:33 PDT
  Description:         testing of targets visibility
  ID:                  r_wfmaMMT4Qu
  Name:                target-viewier
  Updated Time:        Thu, 02 Oct 2025 16:37:32 PDT
  Version:             9

  Scope:
    ID:                p_8qvHOatrkH
    Name:              Generated project scope
    Parent Scope ID:   o_E3JZNdMu0a
    Type:              project

  Authorized Actions:
    set-grants
    set-principals
    remove-principals
    remove-grants
    add-grant-scopes
    set-grant-scopes
    remove-grant-scopes
    no-op
    delete
    add-principals
    add-grants
    read
    update

  Principals:
    ID:             u_EjYY8wPrvW
      Type:         user
      Scope ID:     o_E3JZNdMu0a

  Canonical Grants:
    ids=*;type=target;actions=authorize-session

  Grant Scope IDs:
    ID:             this

  • refresh the Boundary client app (ctrl / cmd + r)

  • the targets should now be visible in the UI

Additional Information

  • different resources have available different actions to them, and can be referenced in the resource table

  • remember that if the user's role is not in the same scope (project-level) as the target, adding the above grants will have no effect on user visibility of targets, since targets can only be created within a project

Articles in this section