Fork me on GitHub
Teleport

Teleport Kubernetes Access Controls

Single Sign-On and Kubernetes RBAC

Teleport issues short-lived X.509 certs and updates Kubernetes clients to talk to Teleport proxy using mutual TLS. It then intercepts every request and adds impersonation headers to map users to Kubernetes users and groups.

Impersonation

Teleport's connectors configure single sign-on for OIDC, OAuth, or SAML providers. Here are examples of connectors that map SSO users to Kubernetes groups in the Teleport Open Source Edition and Teleport's roles in the Enterprise Edition:

Github's teams_to_logins section maps users to roles based on users' teams.

kind: github
version: v3
metadata:
  # Connector name that will be used with `tsh --auth=github login`
  name: github
spec:
  # Client ID of Github OAuth app
  client_id: client-id
  # Client secret of Github OAuth app
  client_secret: client-secret
  # This name will be shown on UI login screen
  display: Github
  # Change tele.example.com to your domain name
  redirect_url: https://tele.example.com:443/v1/webapi/github/callback
  # Map github teams to teleport roles
  teams_to_logins:
    - organization: octocats # Github organization name
      team: admin            # Github team name within that organization
      # keep this field as is for now
      logins: ["admin"]

Mapping OIDC claims and SAML attributes to Kubernetes groups

Identity provider admins can assign metadata to a user, such as group membership or access permissions. Administrators configure what metadata is shared with Teleport. Teleport receives user metadata keys and values as OIDC claims or SAML attributes during signle sign-on redirect flow:

# Alice has an email [email protected] Email is a standard OIDC claim.
email: "[email protected]"
# Alice is a member of groups admins and devs
groups: ["admins", "devs"]
# She can access prod and staging environments
access: {"env": ["prod", "staging"]}

Teleport's roles map OIDC claims or SAML attributes using template variables. Template variable {{external.groups}} will be substituted to the users' group list in the role definition.

kind: role
version: v4
metadata:
  name: group-member
spec:
  allow:
    # For Alice, will be substituted with the list ["admins", "devs"]
    kubernetes_groups: ["{{external.groups}}"]
    # For Alice, will be substituted with ["[email protected]"]
    kubernetes_users: ["{{external.email}}"]
Tip

The examples below may include the use of the sudo keyword, token UUIDs, and users with admin privileges to make following each step easier when creating resources from scratch.

Generally:

  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

Create or update this role using tctl:

tctl create -f member.yaml

Assign this role to a user in OIDC or SAML connector:

kind: github
version: v3
metadata:
  # Connector name that will be used with `tsh --auth=github login`
  name: github
spec:
  # Client ID of Github OAuth app
  client_id: client-id
  # Client secret of Github OAuth app
  client_secret: client-secret
  # This name will be shown on UI login screen
  display: Github
  # Change tele.example.com to your domain name
  redirect_url: https://tele.example.com:443/v1/webapi/github/callback
  # Map github teams to kubernetes groups
  teams_to_logins:
    - organization: octocats # Github organization name
      team: admin            # Github team name within that organization
      # List of Kubernetes groups this Github team is allowed to connect to
      # Keep this field as is for now
      logins: ["admins"]

Local Users

Local users are mapped to Kubernetes groups using roles:

Specify `kubernetes_groups` property in a role "admins" and

create a user assigned to the role.

tctl users add joe --roles="admins"

Kubernetes labels

Label each cluster with key-value pairs describing the cluster:

Install or upgrade the agent or cluster and set labels:

helm upgrade teleport-agent teleport-kube-agent --set kubeClusterName={CLUSTER?}\ --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent\ --set labels.env=prod --set labels.region=us-west-1

Limit access to cluster based on the label:

kind: role
version: v4
metadata:
  name: group-member
spec:
  allow:
    # Allow access to kubernetes clusters in production environment
    kubernetes_labels:
      'env': 'prod'

Impersonation

Teleport uses Kubernetes impersonation to map OIDC and SAML users to Kubernetes users and groups.

Here is an example of Kubernetes ClusterRole and ClusterRoleBinding allowing Teleport's ServiceAccount to impersonate users and groups:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: teleport-impersonation
rules:
- apiGroups:
  - ""
  resources:
  - users
  - groups
  - serviceaccounts
  verbs:
  - impersonate
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
- apiGroups:
  - "authorization.k8s.io"
  resources:
  - selfsubjectaccessreviews
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: teleport
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: teleport-impersonation
subjects:
- kind: ServiceAccount
  # this should be changed to the name of the Kubernetes ServiceAccount being used
  name: teleport-serviceaccount
  namespace: default

Take a look at the example usage in a Teleport Helm chart

Next steps

Integrate with your identity provider:

Have a suggestion or can’t find something?
IMPROVE THE DOCS