Generate Teleport Roles from an External RBAC System

You can use the Teleport gRPC API to generate roles automatically based on an external role-based access control (RBAC) system, such as GitHub or AWS Identity and Access Management.

This is especially useful for:

• Setting up a new Teleport cluster, since you can preserve your existing authorization levels or categories while letting Teleport handle access control.
• Ensuring that your Teleport cluster stays up to date with the RBAC systems of the infrastructure it manages access to. This way, Teleport roles do not unexpectedly gain or lose permissions if your teams reconfigure your external RBAC systems.

In this guide, we will build a small demo application to show you how to generate Teleport roles using Teleport's API client library.

Prerequisites

• A running Teleport cluster version 17.0.2 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.

• Go version 1.22 or above installed on your workstation. See the Go download page. You will not need to be familiar with Go to complete this guide, though Go knowledge is required if you want to build a production-ready Teleport client application.

In a production scenario, you will already have a third-party RBAC solution to use as a basis for generating Teleport roles. In this guide, we will simulate this by deploying a local Kubernetes cluster using minikube and setting up some RBAC resources. We will then use this Kubernetes cluster to generate Teleport roles.

To run the local demo environment, ensure that you have the following tools installed on your workstation:

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.0.2
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/4. Set up your Kubernetes cluster

In this step, we will launch a local Kubernetes cluster and set up role-based access controls within it. We will then use this Kubernetes cluster as a basis for generating Teleport roles.

Start minikube

Start minikube with the Docker driver, which boots a local Kubernetes cluster on a single Docker container:

minikube start --driver=docker

This command should start a local Kubernetes cluster and set your context (i.e., the Kubernetes cluster you are currently interacting with) to minikube. To verify this, run the following command:

kubectl config current-context
minikube

Define demo Kubernetes RBAC resources

Next, we will set up RBAC resources in your local minikube cluster to use as a basis for generating Teleport roles.

In Kubernetes, you can divide a cluster into logically isolated namespaces. A role defines a set of permissions for manipulating resources in a specific namespace. A cluster role is a role that applies to all namespaces in a cluster. You can use a role binding or cluster role binding to attach a role or cluster role to Kubernetes users and groups.

Define a Kubernetes role and role binding that allows users in the app-developer group to read and list pods in the app namespace. Add the following to a file called pod-reader.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: app
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: app
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: app
  annotations:
    'create-teleport-role': 'true'
subjects:
- kind: Group
  name: app-developer
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Create the resources:

kubectl apply -f pod-reader.yaml
namespace/app createdrole.rbac.authorization.k8s.io/pod-reader createdrolebinding.rbac.authorization.k8s.io/read-pods created

Next, define a cluster role and cluster role binding that allow users in the ops group to read, create, and execute commands on pods in all namespaces. Add the following to a file called pod-ops.yaml:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-ops
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list", "create", "exec", "logs"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: pod-ops
  annotations:
    'create-teleport-role': 'true'
subjects:
- kind: Group
  name: ops
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: pod-ops
  apiGroup: rbac.authorization.k8s.io

Create the resources:

kubectl apply -f pod-ops.yaml
clusterrole.rbac.authorization.k8s.io/pod-ops createdclusterrolebinding.rbac.authorization.k8s.io/pod-ops created

Later in this guide, we will show you how to automatically generate Teleport roles based on the Kubernetes RBAC resources you created.

Define RBAC resources for the client application

Next, ensure that your API client can read the RBAC resources you created. Create a file called rbac-sync.yaml with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: rbac-sync
rules:
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["roles", "clusterroles", "rolebindings", "clusterrolebindings"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: rbac-sync
subjects:
- kind: User
  name: sync-kubernetes-rbac
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: rbac-sync
  apiGroup: rbac.authorization.k8s.io

Apply the changes:

kubectl apply -f rbac-sync.yaml
clusterrole.rbac.authorization.k8s.io/rbac-sync createdclusterrolebinding.rbac.authorization.k8s.io/rbac-sync created

Step 2/4. Set up Teleport

In this step, you will configure Teleport to enable your API client application to interact with your Kubernetes cluster.

Create a user and role for the client application

Give the client application a Teleport user and role that can retrieve information about a Kubernetes cluster that is registered with Teleport, authenticate to the cluster, and create or update Teleport roles.

Create a file called sync-kubernetes-rbac.yaml with the following content:

kind: role
version: v7
metadata:
  name: sync-kubernetes-rbac
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_users:
      - sync-kubernetes-rbac
    kubernetes_resources:
      - kind: pod
        name: '*'
        namespace: '*'
    rules:
      - resources: ['kubernetes_cluster']
        verbs: ['read']
      - resources: ['role']
        verbs: ['create', 'update']
---
kind: user
metadata:
  name: sync-kubernetes-rbac
spec:
  roles: ['sync-kubernetes-rbac']
version: v2

Create the user and role:

tctl create -f sync-kubernetes-rbac.yaml
role 'sync-kubernetes-rbac' has been createduser "sync-kubernetes-rbac" has been created

Enable impersonation of the client application

As with all Teleport users, the Teleport Auth Service authenticates the sync-kubernetes-rbac user by issuing short-lived TLS credentials. In this case, we will request the credentials manually by impersonating the sync-kubernetes-rbac role and user.

If you are running a self-hosted Teleport Enterprise deployment and are using tctl from the Auth Service host, you will already have impersonation privileges.

To grant your user impersonation privileges for sync-kubernetes-rbac, define a role called sync-kubernetes-rbac-impersonator by pasting the following YAML document into a file called sync-kubernetes-rbac-impersonator.yaml:

kind: role
version: v5
metadata:
  name: sync-kubernetes-rbac-impersonator
spec:
  allow:
    impersonate:
      roles:
      - sync-kubernetes-rbac
      users:
      - sync-kubernetes-rbac

Create the sync-kubernetes-rbac-impersonator role:

tctl create -f sync-kubernetes-rbac-impersonator.yaml

Assign the sync-kubernetes-rbac-impersonator role to your Teleport user by running the appropriate commands for your authentication provider:

You will now be able to generate signed certificates for the sync-kubernetes-rbac role and user.

Install the Teleport Kubernetes Service

We will enable your client application to communicate with your Kubernetes cluster via the Teleport Kubernetes Service, which forwards requests after authorizing them. While this step is not strictly necessary with a local minikube cluster, it demonstrates one way to use Teleport to securely access your external RBAC system's API.

Set up the Teleport Helm repository.

Allow Helm to install charts that are hosted in the Teleport Helm repository:

helm repo add teleport https://charts.releases.teleport.dev

Update the cache of charts from the remote repository so you can upgrade to all available releases:

helm repo update

Request a token that the Kubernetes Service will use to join your Teleport cluster:

tctl tokens add --type=kube,app,discovery --ttl=10000h --format=json

Copy this token so you can use it when running the Teleport Kubernetes Service.

Ensure that you are connected to the right Kubernetes cluster (logging into Teleport earlier will have changed your Kubernetes context):

kubectl config use-context minikube
Switched to context "minikube".

Install the Teleport Kubernetes Service in your cluster, assigning proxy-address to the host and port of your Teleport Proxy Service (e.g., mytenant.teleport.sh:443) and token to the token you requested earlier:

helm install teleport-agent teleport/teleport-kube-agent \  --set kubeClusterName=minikube \  --set roles="kube\,app\,discovery" \  --set proxyAddr=proxy-address \  --set authToken=token \  --create-namespace \  --namespace=teleport-agent \  --set labels.environment=demo \  --version 17.0.2

After a few seconds, verify that you have deployed the Teleport Kubernetes Service by running the following command:

kubectl -n teleport-agent get pods

This should show that the Kubernetes Service is running:

NAME               READY   STATUS    RESTARTS   AGE
teleport-agent-0   1/1     Running   0          22s

tsh should indicate that the cluster has registered with Teleport:

tsh kube ls
Kube Cluster Name Labels           Selected----------------- ---------------- --------minikube          environment=demo

Step 3/4. Write the client application

At this point, we have set up an external RBAC system to use for generating Teleport roles and configured Teleport to allow our API client to interact with our Kubernetes cluster and Teleport cluster. In this step, we will write our client application.

Set up your Go project

Download the source code for the API client application:

git clone --depth=1 https://github.com/gravitational/teleport -b branch/v17
cd teleport/examples/api-sync-roles

For the rest of this guide, we will show you how to set up the client application and explore the ways it uses Teleport's API to automatically generate Teleport roles.

Export identity files for the client application

The sync-kubernetes-rbac user needs signed credentials in order to connect to your Teleport cluster as well as your Kubernetes cluster. You will use the tctl auth sign command to request these credentials for your API client.

Connecting to your Teleport cluster

The following tctl auth sign command impersonates the sync-kubernetes-rbac user, generates signed credentials, and writes an identity file to the local directory:

tctl auth sign --user=sync-kubernetes-rbac --out=auth.pem

The identity file, auth.pem, includes both TLS and SSH credentials. Your client application uses the SSH credentials to connect to the Proxy Service, which establishes a reverse tunnel connection to the Auth Service. The client application uses this reverse tunnel, along with your TLS credentials, to connect to the Auth Service's gRPC endpoint.

Connecting to the Kubernetes cluster

You will also need to give the client application a way to authenticate to your Kubernetes cluster. To do this, use Teleport's certificate authority to sign credentials for the sync-kubernetes-rbac user. Your API client will present these credentials to authenticate to the Teleport Kubernetes Service, which will proxy requests to the Kubernetes cluster.

Run the following command, ensuring that proxy-address includes the host and port of your Proxy Service:

tctl auth sign --user=sync-kubernetes-rbac \  --kube-cluster-name=minikube \  --format=kubernetes \  --proxy=https://proxy-address \  --out=kubeconfig

Imports

In the api-sync-roles directory, open main.go, which contains the API client program we demonstrate in this guide.

Here are the packages our client application imports from Go's standard library:

The client imports the following third-party code:

Constants

The program defines constants in a visible location so, later on, it's easier to make them configurable outside the program:

const (
	proxyAddr         string = ""
	initTimeout              = time.Duration(30) * time.Second
	identityFilePath  string = "auth.pem"
	kubeconfigPath    string = "kubeconfig"
	clusterName       string = "minikube"
	roleAnnotationKey string = "create-teleport-role"
)

We will use these constants later in the program. They define some values we may want to change later, including:

Initializing a Kubernetes RBAC client

To contact the Kubernetes API, we will need to set up an HTTP client. The client authenticates to the API using mutual TLS, loading a client certificate, certificate authority, and private key from the file at kubeconfigPath. Earlier in the guide, we requested this from the Teleport Auth Service.

The program sets up a Kubernetes API client with the getRBACClient function:

func getRBACClient() (v1.RbacV1Interface, error) {
	f, err := os.Open(kubeconfigPath)
	if err != nil {
		return nil, trace.Wrap(err)
	}

	kc, err := io.ReadAll(f)
	if err != nil {
		return nil, trace.Wrap(err)
	}
	n, err := clientcmd.RESTConfigFromKubeConfig(kc)
	if err != nil {
		return nil, trace.Wrap(err)
	}

	c, err := kubernetes.NewForConfig(n)
	if err != nil {
		return nil, trace.Wrap(err)
	}

	return c.RbacV1(), nil
}

getRBACClient opens and reads the Kubernetes credentials file at kubeconfigPath, then uses the file to set up a Kubernetes API client configuration (clientcmd.RESTConfigFromKubeConfig(kc)) and, with that, an HTTP client (kubernetes.NewForConfig(n)).

Finally, it returns an interface to the Kubernetes API dedicated to role-based access controls, which the rest of the program uses to interact with your Kubernetes cluster.

Creating a Teleport role from a Kubernetes cluster role binding

The createTeleportRoleFromClusterRoleBinding function creates a Teleport role from a Kubernetes cluster role binding by populating fields in the former based on fields in latter:

func createTeleportRoleFromClusterRoleBinding(teleport *client.Client, k types.KubeCluster, r rbacv1.ClusterRoleBinding) error {
	if e, ok := r.Annotations[roleAnnotationKey]; !ok || e != "true" {
		return nil
	}

	role := types.RoleV6{}
	role.SetMetadata(types.Metadata{
		Name: k.GetName() + "-" + r.RoleRef.Name + "-" + "cluster",
	})

	b := k.GetStaticLabels()
	labels := make(types.Labels)
	for k, v := range b {
		labels[k] = []string{v}
	}
	role.SetKubernetesLabels(types.Allow, labels)
	role.SetKubeResources(types.Allow, []types.KubernetesResource{
		types.KubernetesResource{
			Kind:      "pod",
			Namespace: "*",
			Name:      "*",
		},
	})

	var g []string
	var u []string
	for _, s := range r.Subjects {
		if s.Kind == "User" || s.Kind == "ServiceAccount" {
			u = append(u, s.Name)
			continue
		}
		if s.Kind == "Group" {
			g = append(g, s.Name)
			continue
		}
	}
	role.SetKubeGroups(types.Allow, g)
	role.SetKubeUsers(types.Allow, u)
	if err := teleport.UpsertRole(
		context.Background(),
		&role,
	); err != nil {
		return trace.Wrap(err)
	}
	fmt.Println("Upserted Teleport role:", role.GetName())
	return nil
}

To avoid unexpected behavior, this function ignores Kubernetes-managed roles and roles for internal systems like the Teleport Kubernetes Service. This function checks the cluster role binding's metadata for an annotation with a specific key, roleAnnotationKey, and ignores any resource where this key is not set to "true".

We also want a quick way to identify roles we created with this program. To do so, this function names all roles it generates based on cluster role bindings according to the following attributes:

• Kubernetes cluster name
• Kubernetes role name
• The suffix -cluster.

In our demo application, this function will create a Teleport role called minikube-pod-ops-cluster.

The rest of the function assigns fields to a types.RoleV6, the Teleport API client's role type, based on the cluster role binding:

Creating a Teleport role from a Kubernetes role binding

As with cluster role bindings, this program will also create Teleport roles based on Kubernetes role bindings:

func createTeleportRoleFromRoleBinding(teleport *client.Client, k types.KubeCluster, r rbacv1.RoleBinding) error {
	if e, ok := r.Annotations[roleAnnotationKey]; !ok || e != "true" {
		return nil
	}

	role := types.RoleV6{}
	role.SetMetadata(types.Metadata{
		Name: k.GetName() + "-" + r.RoleRef.Name + "-" + r.Namespace,
	})

	b := k.GetStaticLabels()
	labels := make(types.Labels)
	for k, v := range b {
		labels[k] = []string{v}
	}
	role.SetKubernetesLabels(types.Allow, labels)
	role.SetKubeResources(types.Allow, []types.KubernetesResource{
		types.KubernetesResource{
			Kind:      "pod",
			Namespace: r.Namespace,
			Name:      "*",
		},
	})
	var g []string
	var u []string
	for _, s := range r.Subjects {
		if s.Kind == "User" || s.Kind == "ServiceAccount" {
			u = append(u, s.Name)
			continue
		}
		if s.Kind == "Group" {
			g = append(g, s.Name)
			continue
		}
	}
	role.SetKubeGroups(types.Allow, g)
	role.SetKubeUsers(types.Allow, u)

	if err := teleport.UpsertRole(
		context.Background(),
		&role,
	); err != nil {
		return trace.Wrap(err)
	}
	fmt.Println("Upserted Teleport role:", role.GetName())
	return nil
}

While the overall behavior of this function is the same as createTeleportRoleFromClusterRoleBinding, Kubernetes role bindings require some differences in how we assign fields to Teleport roles:

• When setting the name of the role, we use the role binding's namespace as the suffix, rather than -cluster, to indicate the namespace that this role applies to.
• In the role's kubernetes_resources field, the value has the same namespace as the role binding, rather than applying to all namespaces.

Creating Teleport roles based on Kubernetes resources

Now that we have functions to create Teleport roles based on individual Kubernetes RBAC resources, we can fetch all RBAC resources from our Kubernetes cluster and call these functions:

func createTeleportRolesForKubeCluster(teleport *client.Client, k types.KubeCluster) error {
	rbac, err := getRBACClient()
	if err != nil {
		return trace.Wrap(err)
	}

	crb, err := rbac.ClusterRoleBindings().List(
		context.Background(),
		metav1.ListOptions{},
	)
	if err != nil {
		return trace.Wrap(err)
	}

	for _, i := range crb.Items {
		if err := createTeleportRoleFromClusterRoleBinding(teleport, k, i); err != nil {
			return trace.Wrap(err)
		}
	}

	rb, err := rbac.RoleBindings("").List(
		context.Background(),
		metav1.ListOptions{},
	)
	if err != nil {
		return trace.Wrap(err)
	}

	for _, i := range rb.Items {
		if err := createTeleportRoleFromRoleBinding(teleport, k, i); err != nil {
			return trace.Wrap(err)
		}
	}
	return nil
}

createTeleportRolesForKubeCluster takes a Teleport client and a Teleport-registered Kubernetes cluster. It calls the getRBACClient function we defined earlier to set up a client for the Kubernetes cluster. It then:

• Lists Kubernetes cluster role bindings and creates a Teleport role for each one.
• Lists Kubernetes role bindings and creates a Teleport role for each one.

Initializing clients and start the application

The functions we declared earlier require a Teleport API client and a Teleport-registered Kubernetes cluster, and we initialize these in the entrypoint of the program, the main function:

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), initTimeout)
	defer cancel()
	creds := client.LoadIdentityFile(identityFilePath)

	teleport, err := client.New(ctx, client.Config{
		Addrs:       []string{proxyAddr},
		Credentials: []client.Credentials{creds},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println("Connected to Teleport")

	ks, err := teleport.GetKubernetesServers(context.Background())
	if err != nil {
		panic(err)
	}
	for _, k := range ks {
		if k.GetCluster().GetName() != clusterName {
			continue
		}
		fmt.Println("Retrieved Kubernetes cluster", clusterName)

		if err := createTeleportRolesForKubeCluster(teleport, k.GetCluster()); err != nil {
			panic(err)
		}
		fmt.Println("Created roles for Kubernetes cluster", clusterName)
		return
	}
	panic("Unable to locate a Kubernetes Service instance for " + clusterName)
}

client is Teleport's library for setting up an API client. Our program initializes a Teleport client by calling client.LoadIdentityFile to obtain a client.Credentials. It then uses the client.Credentials to call client.New, which connects to the Teleport Proxy Service specified in the Addrs field using the provided identity file.

After initializing a Teleport client, the main function fetches all Kubernetes servers registered with Teleport (teleport.GetKubernetesServers) and checks if there is a registered Kubernetes cluster that matches the one you specified.

If a matching Kubernetes cluster exists, the code calls the createTeleportRolesForKubeClusters function we defined earlier. If not, the program prints an error message and a stack trace by calling Go's built-in panic function.

Step 4/4. Test your client application

To test the client application, start it up from within its project directory:

go run main.go

You should see the following output:

Connected to Teleport
Retrieved Kubernetes cluster minikube
Upserted Teleport role: minikube-pod-ops-cluster
Upserted Teleport role: minikube-pod-reader-app
Created roles for Kubernetes cluster minikube

Examine the new minikube-pod-ops-cluster role by running the command below:

tctl get roles/minikube-pod-ops-cluster

You should see output similar to the following:

kind: role
metadata:
  id: 1678732494974032643
  name: minikube-pod-ops-cluster
spec:
  allow:
    kubernetes_groups:
    - ops
    kubernetes_labels:
      environment: demo
    kubernetes_resources:
    - kind: pod
      name: '*'
      namespace: '*'
  deny: {}
  options:
    cert_format: standard
    create_host_user: false
    desktop_clipboard: true
    desktop_directory_sharing: true
    enhanced_recording:
    - command
    - network
    forward_agent: false
    idp:
      saml:
        enabled: true
    max_session_ttl: 30h0m0s
    pin_source_ip: false
    port_forwarding: true
    record_session:
      default: best_effort
      desktop: true
    ssh_file_copy: true
version: v7

Compare this with the minikube-pod-reader-app role, which you can retrieve with the following command:

tctl get roles/minikube-pod-reader-app

Here is the role we created:

kind: role
metadata:
  id: 1678732495284493075
  name: minikube-pod-reader-app
spec:
  allow:
    kubernetes_groups:
    - app-developer
    kubernetes_labels:
      environment: demo
    kubernetes_resources:
    - kind: pod
      name: '*'
      namespace: app
  deny: {}
  options:
    cert_format: standard
    create_host_user: false
    desktop_clipboard: true
    desktop_directory_sharing: true
    enhanced_recording:
    - command
    - network
    forward_agent: false
    idp:
      saml:
        enabled: true
    max_session_ttl: 30h0m0s
    pin_source_ip: false
    port_forwarding: true
    record_session:
      default: best_effort
      desktop: true
    ssh_file_copy: true
version: v7

Since role bindings are namespaced, this role only allows access to pods in the app namespace, where this role binding was applied. The Kubernetes Service forwards traffic from users with this role using the app-developer Kubernetes group.

Next steps

We have implemented a Teleport API client that generates Teleport roles based on the Kubernetes RBAC system. You can use Teleport's API to build similar applications that interact with other RBAC systems, such as GitHub teams or groups within your database management system.

Here are some starting points for building out your client application.

Learn more about Teleport roles

To write an effective client application that generates Teleport roles from an external RBAC solution, you should understand the role fields that apply to infrastructure resources you want to manage access to.

See the links below for guides to fields related to different infrastructure resources:

• Servers
• Databases
• Kubernetes clusters
• Windows Desktops
• Applications

For general guidance, read our Access Controls Reference.

Register your cloud provider with Teleport

You can protect cloud provider APIs with Teleport and instruct your API client applications to connect to these APIs via the Teleport Application Service. Using Teleport-protected cloud provider APIs, you can generate Teleport roles based on your cloud provider's RBAC solution.

Read our guides for how to set up the Teleport Application Service for cloud provider APIs:

• AWS
• Google Cloud
• Azure

Consult examples

The Teleport code repository contains examples of production-ready Teleport API clients. While we currently do not maintain plugins that generate Teleport roles, you can use these examples to see how to implement configuration parsing, retries, and other tasks.

Provision the client application with short-lived credentials

In this example, we used the tctl auth sign command to fetch credentials for the program you wrote. For production usage, we recommend provisioning short-lived credentials via Machine ID, which reduces the risk of these credentials becoming stolen. View our Machine ID documentation to learn more.