Deploy Login Rules using Kubernetes Operator

This guide will explain how to:

• Use Teleport's Kubernetes Operator to deploy Login Rules to your Teleport cluster
• Edit deployed Login Rules with kubectl

This guide is applicable if you self-host Teleport in Kubernetes using the teleport-cluster Helm chart.

Prerequisites

• A Teleport Enterprise license

• A Kubernetes cluster (with or without teleport-cluster Helm chart already deployed)

• Helm

• kubectl

• Validate Kubernetes connectivity by running the following command:

  kubectl cluster-info
  Kubernetes control plane is running at https://127.0.0.1:6443
  CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

  Tip

  Users wanting to experiment locally with the Operator can use minikube to start a local Kubernetes cluster:

  minikube start

• Follow the Teleport operator guides to install the Teleport Operator in your Kubernetes cluster. Make sure to follow the Enterprise instructions if you're deploying the operator as part of the teleport-cluster chart.

  Confirm that the CRD (Custom Resource Definition) for Login Rules has been installed with the following command:

  kubectl explain TeleportLoginRule.spec
  KIND:     TeleportLoginRuleVERSION:  resources.teleport.dev/v1
  RESOURCE: spec <Object>
  DESCRIPTION:    LoginRule resource definition v1 from Teleport
  FIELDS:  priority     <integer>    Priority is the priority of the login rule relative to other login rules in    the same cluster. Login rules with a lower numbered priority will be    evaluated first.
    traits_expression    <string>    TraitsExpression is a predicate expression which should return the desired    traits for the user upon login.
    traits_map   <>    TraitsMap is a map of trait keys to lists of predicate expressions which    should evaluate to the desired values for that trait.

  If this fails, you may not have installed the Teleport Operator, or you may have installed an older version.

Step 1/2. Create a Login Rule using kubectl

Paste the following into a file called login-rules.yaml that describes two custom Login Rule resources:

# login-rules.yaml
apiVersion: resources.teleport.dev/v1
kind: TeleportLoginRule
metadata:
  name: example-traits-map-rule
  labels:
    example: "true"
spec:
  # The rule with the lowest priority will be evaluated first.
  priority: 0

  # traits_map holds a map of all desired trait keys to lists of expressions
  # that determine the trait values.
  traits_map:

    # The "logins" traits will be set to the external "username" trait converted
    # to lowercase, and any external "logins" trait.
    logins:
      - 'strings.lower(external.username)'
      - 'external.logins'

    # The external "groups" trait will be passed through unchanged, all other
    # traits will be filtered out.
    groups:
      - external.groups
---
apiVersion: resources.teleport.dev/v1
kind: TeleportLoginRule
metadata:
  name: example-traits-expression-rule
  labels:
    example: "true"
spec:
  # This rule has a higher priority value, so it will be evaluated after the
  # "terraform-test-map-rule".
  priority: 1

  # traits_expression is an alternative to traits_map, which returns all desired
  # traits in a single expression.
  traits_expression: |
    external.put("groups",
      choose(
        option(external.groups.contains("admins"), external.groups.add("app-admins", "db-admins")),
        option(external.groups.contains("ops"), external.groups.add("k8s-admins")),
        option(true, external.groups)))

Create the Kubernetes resources:

kubectl apply -f login-rules.yaml

List the created Kubernetes resources:

kubectl get loginrules
NAME                             AGEexample-traits-expression-rule   8m8sexample-traits-map-rule          8m8s

Check that the Login Rules have been created in Teleport:

AUTH_POD=$(kubectl get pods -l app=teleport-cluster -o jsonpath='{.items[0].metadata.name}')
kubectl exec -i $AUTH_POD -c teleport -- tctl get login_rules
kind: login_rulemetadata:  id: 1680225062340767900  labels:    example: "true"    teleport.dev/origin: kubernetes  name: example-traits-expression-rulespec:  priority: 1  traits_expression: |    external.put("groups",      choose(        option(external.groups.contains("admins"),external.groups.add("app-admins", "db-admins")),        option(external.groups.contains("ops"),external.groups.add("k8s-admins")),        option(true, external.groups)))version: v1---kind: login_rulemetadata:  id: 1680225067068319000  labels:    example: "true"    teleport.dev/origin: kubernetes  name: example-traits-map-rulespec:  priority: 0  traits_map:    groups:    - external.groups    logins:    - strings.lower(external.username)    - external.loginsversion: v1

Test the Login Rules by sending some example input traits to the standard input of the tctl login_rule test command and having it load all Login Rules from the cluster.

echo '{"groups": ["admins", "ops"], "username": ["Alice"], "logins": ["user", "root"]}' | \  kubectl exec -i $AUTH_POD -c teleport -- tctl login_rule test --load-from-cluster
groups:- admins- ops- app-admins- db-adminslogins:- alice- user- root

Step 2/2. Edit the Login Rules with kubectl

Edit the example-traits-map-rule to add an extra login example login.

--- a/login-rules.yaml
+++ b/login-rules.yaml
@@ -18,6 +18,7 @@ spec:
     logins:
       - 'strings.lower(external.username)'
       - 'external.logins'
+      - 'example'

     # The external "groups" trait will be passed through unchanged, all other
     # traits will be filtered out.

Apply the update to the Kubernetes resource:

kubectl apply -f login-rules.yaml

Test the Login Rules again to see the extra example login:

echo '{"groups": ["admins", "ops"], "username": ["Alice"], "logins": ["user", "root"]}' | \  kubectl exec -i $AUTH_POD -c teleport -- tctl login_rule test --load-from-cluster
groups:- ops- app-admins- db-admins- adminslogins:- root- user- example- alice

Next Steps

• Read the Teleport Operator Guide to learn more about the Teleport Operator.
• Read the Login Rules reference to learn mode about the Login Rule expression syntax.