Skip to main content
Version: 17.x (unreleased)

Managing Users And Roles With IaC

In this guide, you will see how to create users and grant them roles through infrastructure as code (IaC). Teleports supports three ways to dynamically create resources from code:

  • The Teleport Kubernetes Operator, which allows you to manage Teleport resources from Kubernetes
  • The Teleport Terraform Provider, which allows you to manage Teleport resources via Terraform
  • The tctl CLI, which allows you to manage Teleport resources from your local computer or your CI environment

Prerequisites​

To follow this guide, you must have:

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

Step 1/4. Write manifests​

In this step, we'll write text files describing the resources we want in Teleport. Those files are called manifests and their syntax will vary based on the IaC tooling you'll use.

Those manifests are typically versioned in a shared revision system like git. This allows you to keep track of all changes, follow standard code review procedures before changing resources in Teleport, and quickly redeploy your Teleport instance if needed.

Write role manifests​

We will create 2 roles:

  • manager allows listing users and roles, as well as reviewing audit events and session contents.
  • engineer grants access to dev and staging servers.

Create the following roles.yaml file:

kind: role
version: v7
metadata:
  name: manager
spec:
  allow:
    rules:
      - resources: ['user', 'role']
        verbs: ['list','read']
      - resources: ['session', 'event']
        verbs: ['list', 'read']
---
kind: role
version: v7
metadata:
  name: engineer
spec:
  allow:
    logins: ['root', 'ubuntu', '{{internal.logins}}']
    node_labels:
      'env': ['test', 'staging']

Write user manifests​

We will create 2 users:

  • Bob, an engineer with the engineer role.
  • Alice, an engineering manager with both manager and engineer roles.
note

Users created from manifests are local users, as opposed to users coming from an external SAML/OIDC/GitHub Identity Provider (IdP).

See the user type reference for more details.

Create the file users.yaml with the following content:

kind: user
version: v2
metadata:
  name: alice
spec:
  roles: ['manager', 'engineer']
---
kind: user
version: v2
metadata:
  name: bob
spec:
  roles: ['engineer']

Step 2/4. Apply all manifests​

$ tctl create -f roles.yaml
role 'manager' has been created
role 'engineer' has been created

$ tctl create -f users.yaml
user "alice" has been created
user "bob" has been created
note

The user resource depends on roles, you must create roles before users as a user with a non-existing role is invalid and might be rejected by Teleport.

Step 3/4. Validate users were created​

Now that the IaC tooling has run, we'll validate that the users were properly created and granted the correct roles.

If you have UI access, connect to your Teleport cluster Web UI, open the management panel, and select the "Users" tab.

Screenshot of the web UI listing alice and bob users

Two new users alice and bob should be present.

At this point, the local users have been created in Teleport. However, we never specified any password or additional authentication factors. You must issue a password reset link for the users to finish their Teleport registration and be able to log in Teleport.

User reset links contain single-use expiring tokens. Because of this, you cannot follow the same declarative approach as for other Teleport resources and generate them via a manifest. You need to create those tokens once after the user creation, and securely send them to the end-user for them to register their password/MFA.

Option 1: Reset via CLI​

You can manually reset a user password via tctl by doing:

$ tctl users reset alice
User "alice" has been reset. Share this URL with the user to complete password reset, link is valid for 8h:
https://teleport.example.com:443/web/reset/05b420fdc784597cbbb1d2ba65697cd8

NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.

Option 2: Automating user reset​

If you have a way to securely send reset links to the users, you can build automation to fit your organization's specific needs. For example:

$ tctl users reset alice --format=json | \
    jq '"Sending an email to " + .spec.user +" that contains the link: " + .spec.url'

You must replace the jq command by something that actually sends the link over a secure channel. This channel will depend on your organization. It is usually a direct message or an email.

For Terraform users

You can trigger your custom script on Terraform resource creation with the local-exec provisioner.

resource "teleport_user" "bob" {
  version = v2
  metadata = {
    name = "bob"
  }

  spec = {
    roles = [teleport_role.engineer.metadata.name]
  }
  
  # on user creation, trigger a reset flow and send the link via 
  provisioner "local-exec" {
    command = "tctl users reset alice --format=json | jq '\"Sending an email to \" + .spec.user +\" that contains the link: \" + .spec.url'"
  }
}

Next steps​

  • Allow users with the manager role to grant access to production servers to some engineers via Access Lists. Manager will need to justify and review granted access periodically. See the AccessList documentation for a high-level explanation of the feature, and the AccessList IaC guide for a step by step IaC AccessList setup.
  • Allow users with the engineer role to request temporary access to production, and have users with the manager role validate the requests. See the Access Requests documentation
  • You can see all supported fields in the references of the user resource and the role resource.