Teleport RBAC: Declarative Role‑Based Access Control for Secure Infrastructure

What You’ll Gain

Teleport’s RBAC lets you define fine‑grained, declarative access policies in YAML, attach them to users, and have those policies automatically enforced via short‑lived X.509 certificates. The result is a single source of truth for who can SSH into which nodes, access which Kubernetes namespaces, or query which databases—all without manual credential distribution.

How It Works – A Quick Walk‑Through

1. Define a Role – Roles are YAML files that list allow rules. Each rule targets a resource type (e.g., ssh, k8s, db) and optionally filters by labels. Example:

   spec:
     allow:
       - resource_type: ssh
         nodes: "env:prod"
         logins: ["ubuntu"]
       - resource_type: k8s
         namespaces: ["dev", "qa"]
     deny: []
   

2. Assign the Role – Use tctl create role or edit roles.yaml to add the role name to a user’s roles list.

   tctl create role --file prod-ssh-role.yaml
   # Assign to user
   cat > user.yaml
   name: alice
   roles:
     - prod-ssh-role
   

3. Authenticate – Alice authenticates via an IdP (e.g., SAML, OIDC). Teleport’s Auth Service issues a short‑lived X.509 certificate containing her role claims.

   tsh login --proxy=proxy.example.com
   # After login, tsh status shows the embedded roles
   

4. Access Granted or Denied – When Alice attempts to SSH to a node, the Teleport Proxy checks her certificate’s allow rules against the node’s labels. If the node label env=prod matches, the request is forwarded; otherwise it is rejected.

Practical Verification Steps

1. Deploy a Teleport Community Edition cluster (TLS certificates, Auth Service, Proxy, Node).
2. Create the prod-ssh-role via tctl create role.
3. Assign the role to alice.
4. Label a node: tctl update node --labels env=prod.
5. Log in as Alice and run tsh ssh ubuntu@node1 – should succeed.
6. Label another node env=dev and attempt the same SSH – should fail.
7. Run tsh status to confirm the certificate includes roles: ["prod-ssh-role"].

Limitations & Common Pitfalls

• Label Over‑reach – Using * or broad label selectors grants access to unintended resources. Always specify explicit labels.
• Role Reload – Changes to roles or role assignments take effect only for new sessions. Existing SSH or K8s sessions remain valid until the certificate expires.
• Union of Permissions – If a user has multiple roles, Teleport merges permissions by union. A permissive role can inadvertently grant access beyond the intended scope.
• Certificate Expiry – Teleport’s certificates are short‑lived (default 8 hours). Users must re‑authenticate to maintain access; schedule re‑logins or use tsh login --auth=oidc for seamless token refresh.
• Audit Configuration – Session recording is optional. Without it, compliance audits cannot verify how a user interacted with a resource.

Best Practices

• Use allow rules only; keep deny empty unless you need explicit block.
• Apply the principle of least privilege: limit logins, nodes, and namespaces to the minimum required.
• Version your role YAMLs and store them in a Git repository for auditability.
• Periodically review role assignments and label usage to prevent drift.

Conclusion

Teleport’s declarative RBAC turns infrastructure access into a manageable, auditable process. By defining roles in YAML, assigning them to users, and letting Teleport’s Auth Service issue role‑aware certificates, you eliminate manual key rotation and reduce the risk of privilege creep. Just remember to keep label selectors tight, reload roles for changes to take effect, and enable session recording for full audit coverage.