Access Control Guide


You will need:


The following features are supported:

  • Access control by Host Tags configuration using Groups synchronized from your IDP

Step By Step Instructions

Step 0: Understanding Host Tags

Host Tags (key-value pairs) are the pillars of our access control model. Rather than mapping people or groups directly to hosts, you'll map tag combinations to your hosts and to your user groups. First you'll put your hosts into logical groups using tags, eg. role:web or env:staging. Then, you'll grant user groups access to all hosts with a specific tag combination. Finally, you'll choose which user group tag combinations will allow sudo privileges on any matching hosts.

Let's look at an example:

  • The developers group will have access to myserver #1 only.
  • The data group will have access to myserver #2 and myserver #3.
  • The ops group will have sudo access to myserver #2 and myserver #3.

Of course, hosts and groups can have as many tag combinations as you like. Take a minute to think about how you'd like to use Host Tags in your environment.

Step 1: Determine Host Tag Combination

Sign in at[Team ID]

  • Choose "SSH Professional" from the top navigation bar
  • Choose "Hosts" on the right hand navigation bar
  • Find and select a Host that includes the Host Tags you wish to use for access grants.
    • In the example below that combination is database : production.
  • Make a note of the tag combination, you will need this in Step 2

Step 2: Grant User Group Access to Host(s)

On your Smallstep Dashboard.

  • Select the "Users" tab on the right hand navigation bar.
  • Choose the "GROUPS" tab

  • Select the User Group that you want to configure for access control. You will see the user group detail page with a list of existing Host Grants and a form to add additional grants.
  • Select "Edit" from the kebab menu to the right of the Group's name.
    • Enter the tag values from Step 1
    • If Sudo access is permitted for this user group, select the "Allow Sudo" checkbox
    • Click the checkbox to enable access control
  • Optional. Assign POSIX Groups. Smallstep now supports POSIX groups on hosts running step-ssh version 0.22.0 or greater. Managed Groups are POSIX groups that you want Smallstep to create or delete on your Hosts. Unmanaged Groups are the default POSIX groups such as fax or floppy that already exist on the Host. Groups members will have permissions assigned to these groups.
    • In the example below, we are adding users in the Smallstep group okta-isvtest-ssh to one unmanaged POSIX group (floppy) and one managed POSIX group (sre-team)
  • Optional. Assign Certificate Principals. Smallstep now supports adding additional principals to user certificates. A Principal is a string that allows access to a host, or even a specific user on a host. Users in the assigned group will be able to access Smallstep-managed hosts as that user, whether or not the user is managed by Smallstep. Adding a user as a certificate principal does not enable full lifecycle management for that user.
    • In the example below we are adding the principal craig to certificates issued for the Group okta-isvtest-ssh.

  • All users in the group now have access to all hosts with the specified tag combination.