diff --git a/docs/pages/admin-guides/access-controls/getting-started.mdx b/docs/pages/admin-guides/access-controls/getting-started.mdx index 0bc74d3710db5..59a8a6b5ad821 100644 --- a/docs/pages/admin-guides/access-controls/getting-started.mdx +++ b/docs/pages/admin-guides/access-controls/getting-started.mdx @@ -1,251 +1,394 @@ +--- +title: Getting Started With Role-Based Access Control +description: Teleport Role-Based Access Control. +tocDepth: 3 --- -title: Getting Started With Access Controls -description: Get started using Teleport Access Controls. ---- - -In Teleport, any local, SSO, or robot user can be assigned one or several roles. -Roles govern access to databases, SSH servers, Kubernetes clusters, Windows -desktops, and web apps. -We will start with local users and preset roles, assign roles to SSO users, and -wrap up with creating your own role. +Teleport RBAC (Role-Based Access Control) is a system for managing who can +access what within your infrastructure. Instead of assigning permissions +directly to users, you create roles that define sets of permissions, then assign +those roles to users. + +This guide helps you understand and implement Role-Based Access Control (RBAC) +in Teleport. By the end of this guide, you'll be able to: + +- Understand how roles control access to resources. +- Implement common access patterns. +- Create and configure basic roles in Teleport. +- Assign roles to users. +- Follow best practices to scale and maintain roles. + +## How it works + +In Teleport, **infrastructure resources** are infrastructure components like SSH +servers, Kubernetes clusters, databases, and web applications. **Users**, which +can be humans or bots, connect to resources. Teleport **roles** are [dynamic +Teleport resources](../infrastructure-as-code/infrastructure-as-code.mdx) that +allow or deny access to infrastructure resources, as well as to Teleport API +operations like creating users or reviewing Access Reqeusts. + +Roles control access to infrastructure resources using **label matching**. All +infrastructure resources that are enrolled in your Teleport cluster have +**labels**, which are key-value pairs such as `env:dev`. When a user attempts to +connect to a resource, the [Teleport +Agent](../../enroll-resources/agents/agents.mdx) that proxies the resource +checks the user's Teleport roles to ensure that the user has the appropriate +permissions and, if not, denies the connection. ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) - (!docs/pages/includes/tctl.mdx!) +- A Teleport user with permissions to create join tokens and other roles. We + recommend using a demo cluster with the preset `editor` role. +- Docker installed on your workstation. + + This guide illustrates how to register a server with Teleport using a Docker + container and the Teleport SSH Service. Docker is only required for the local + demo environment used in this guide. You can find installation instructions + for Docker on [Docker's website](https://docs.docker.com/get-docker/). If you + want to register servers in Teleport without using Docker, see the getting + started guide for [server + access](enroll-resources/server-access/getting-started.mdx). + +## Step 1/2. Enroll resources with labels + +In this section, you will enroll two servers with your Teleport cluster. One +server will have the `env:local-dev` label and the other will have the +`env:local-prod`. Later in this guide, you will create a role that will allow a +user to access a server with the `env:local-dev` label and deny access to the +`env:local-prod` label. + +### Enroll a server with the `env:local-dev` label + +1. Create a join token for the server to use to join the cluster: + + ```code + $ tctl tokens add --type=node + ``` + +1. Assign the token to and the host and web port of your + Teleport Proxy Service to . + +1. Copy the following Teleport configuration to a file called `local-dev.yaml`: + + ```yaml + version: v3 + teleport: + data_dir: /var/lib/teleport + join_params: + token_name: + method: token + proxy_server: + auth_service: + enabled: "no" + ssh_service: + enabled: "yes" + labels: + env: local-dev + proxy_service: + enabled: "no" + ``` + + This Teleport configuration enables the Teleport SSH Service, which enrolls a + server in your Teleport cluster. The `ssh_service.labels` field adds a label + to the server called `env:local`. + +1. Assign the absolute path to the configuration file you created to + . + +1. Start the Teleport SSH Service on a local Docker container with the + configuration and join it to your cluster: + + ```code + $ docker run -v :/etc/teleport/teleport.yaml (=teleport.latest_ent_debug_docker_image=) + ``` + +1. Wait for a minute or so. Ensure that the server has joined your cluster by + listing enrolled servers by label. You should see the server you just + enrolled: + + ```code + $ tsh ls env=local-dev + Node Name Address Labels + ------------ ---------- ------------- + 80f60427d316 ⟵ Tunnel env=local-dev + ``` + +### Enroll a server with the `env:local-prod` label + +1. Open a separate terminal. + +1. Create a join token for the server to use to join the cluster: + + ```code + $ tctl tokens add --type=node + ``` + +1. Assign the token to . + +1. Copy the following YAML document to a file called `local-prod.yaml`. This + configuration starts the Teleport SSH Service with the label + `env:local-prod`: + + ```yaml + version: v3 + teleport: + data_dir: /var/lib/teleport + join_params: + token_name: + method: token + proxy_server: + auth_service: + enabled: "no" + ssh_service: + enabled: "yes" + labels: + env: local-prod + proxy_service: + enabled: "no" + ``` + +1. Assign the absolute path to the configuration file you created to + . + +1. Start the Teleport SSH Service on a local Docker container with the + configuration and join it to your cluster: + + ```code + $ docker run -v :/etc/teleport/teleport.yaml (=teleport.latest_ent_debug_docker_image=) + ``` + +1. Ensure that the server has joined the cluster: + + ```code + $ tsh ls env=local-prod + Node Name Address Labels + ------------ ---------- -------------- + ba2290caf694 ⟵ Tunnel env=local-prod + ``` + +## Step 2/3. Create a Teleport role + +Create a role that can access servers with the `env:local-dev` label but not the +`env:local-prod` label. + +1. Create a file called `role.yaml` with the following content: + + ```yaml + kind: role + version: v7 + metadata: + name: local-dev-access + spec: + allow: + logins: ['root'] + node_labels: + 'env': 'local-*' + deny: + node_labels: + 'env': 'local-prod' + ``` -(!docs/pages/includes/permission-warning.mdx!) - -## Step 1/3. Add local users with preset roles - -Teleport provides several preset roles: - -(!docs/pages/includes/preset-roles-table.mdx!) - - - -Invite the local user Alice as cluster `editor`: - -```code -$ tctl users add alice --roles=editor -``` - - -Invite the local user Alice as cluster `editor` and `reviewer`: - -```code -$ tctl users add alice --roles=editor,reviewer -``` - - - + The `allow` block indicates what the user is allowed to access. By default, + nothing is allowed, so each role must include at least one `allow` field to + provide permissions. -Once Alice signs up, she will be able to edit cluster configuration. You can list -users and their roles using `tctl users ls`. + The `spec.allow.logins` field allows the user to assume the `root` login when + connecting to a server. You can change this to a less permissive login, but + we are using `root` because it is the only available login on the Docker + containers we spun up. + + `spec.allow.node_labels` uses wildcard syntax, which matches one or more + characters, to allow users to connect to any server with a label that begins + `env:local-`, such as the `env:local-dev` and `env:local-prod` labels we + assigned to our servers. - - -```code -$ tctl users ls + However, since the `deny.node_labels` field specifies `env:local-prod`, a + user with this role would only be able to access the server with the + `env:local-dev` label. -# User Roles -# -------------------- -------------- -# alice editor -``` - - -```code -$ tctl users ls - -# User Roles -# -------------------- -------------- -# alice editor, reviewer -``` - - - +1. Create the role: + + ```code + $ tctl create role.yaml + ``` -You can update the user's roles using the `tctl users update` command: +## Step 3/3. Access your server - - -```code -# Once Alice logs back in, she will be able to view audit logs -$ tctl users update alice --set-roles=editor,auditor -``` - - -```code -# Once Alice logs back in, she will be able to view audit logs -$ tctl users update alice --set-roles=editor,reviewer,auditor -``` - +In this step, you will create a local Teleport user with the `local-dev-access` +role, then list available servers and connect the one with the label +`env:local-dev`. + +1. Create a local user named `alice` with the `local-dev-access` role: + + ```code + $ tctl users add alice --roles=local-dev-access + ``` + +1. Follow the instructions in your terminal to sign in as `alice`. + +1. In your terminal, log out of your cluster and log in again: + + ```code + $ tsh logout + $ tsh login --user=alice --proxy= + ``` + +1. List all servers available for your user to access. You should only see one: + + ```code + $ tsh ls + Node Name Address Labels + ------------ ---------- ------------- + ba2290caf694 ⟵ Tunnel env=local-dev + ``` - + Since `alice` is denied access to servers with the `env:local-prod` label, + only the server with the `env:local-dev` label is available to connect to. -Because Alice has two or more roles, permissions from those roles create a union. She -will be able to act as a system administrator and auditor at the same time. +1. Access the server using the value of the `Node Name` field as shown in `tsh + ls`: -## Step 2/3. Map SSO users to roles + ```code + $ tsh ssh root@ + ``` -Next, follow the instructions to set up an authentication connector that maps -users within your SSO solution to Teleport roles. +## Next steps -### Teleport Enterprise +In this guide, you created a Teleport role that allowed and denied access to SSH +servers based on the labels that the servers were enrolled with. Read about more +things you can do with Teleport roles. -Create a SAML or OIDC application that Teleport can integrate with, then -create an authentication connector that maps users within your application to -Teleport roles. +### Refine resource labels - - +Resource labeling is a crucial component of effective RBAC implementation in Teleport. Labels help you define which specific +resources users can access and why they need that access. Some common labels to consider using: -Follow our [SAML Okta Guide](./sso/okta.mdx) to -create a SAML application. +- Environment (`dev`, `staging`, `production`) +- Team ownership (`backend`, `frontend`, `data`) +- Project or application (`auth-service`, `billing-api`) +- Cost center or business unit (`marketing`, `engineering`) -Save the file below as `okta.yaml` and update the `acs` field. -Any member in Okta group `okta-admin` will assume a built-in role `admin`. +Example label structure: ```yaml -kind: saml -version: v2 +kind: role +version: v7 metadata: - name: okta + name: senior-developer spec: - acs: https://tele.example.com/v1/webapi/saml/acs - attributes_to_roles: - - {name: "groups", value: "okta-admin", roles: ["access"]} - entity_descriptor: | - - - -Follow our [OIDC guides](./sso/oidc.mdx#identity-providers) to -create an OIDC application. +Teleport roles can match labels in several ways: -Copy the YAML below to a file called `oidc.yaml` and edit the information to -include the details of your OIDC application. +#### Exact matching ```yaml -(!examples/resources/oidc-connector.yaml!) +node_labels: + environment: 'production' # Matches only 'production' ``` -Create the `oidc` resource: +#### Multiple values -```code -$ tctl create okta.yaml +```yaml +node_labels: + environment: ['dev', 'staging'] # Matches either 'dev' or 'staging' ``` - - - -### Teleport Community Edition - -Save the file below as `github.yaml` and update the fields. You will need to -set up a -[GitHub OAuth 2.0 Connector](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) -app. Any member belonging to the GitHub organization `octocats` and on team -`admin` will be able to assume the built-in role `access`. +#### Wildcard matching ```yaml -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_roles: - - organization: octocats # GitHub organization name - team: admin # GitHub team name within that organization - # map github admin team to Teleport's "access" role - roles: ["access"] +node_labels: + project: 'api-*' # Matches any project starting with 'api-' ``` -Create the `github` resource: +### Maintaining your labeling strategy -```code -$ tctl create github.yaml -``` +- **Regular review:** Regular audits of your labeling scheme are essential for maintaining an effective RBAC system. Your organization's structure +and needs evolve over time, so your labels should be reviewed to ensure they accurately reflect these changes. +- **Documentation:** Maintaining consistency across your organization. Include clear guidelines for label naming conventions to ensure +standardization and prevent confusion as your team grows and your infrastructure expands. +- **Automation:** Implementing automation in your labeling strategy will maintain consistency and reduce human error as your system scales and evolves. -## Step 3/3. Create a custom role +### Common use cases examples -Let's create a custom role for interns. Interns will have access -to test or staging SSH servers as `readonly` users. We will let them -view some monitoring web applications and dev kubernetes cluster. +Here are some exampels of common patterns in Teleport labels. -Save this role as `interns.yaml`: +#### Basic developer access + +This role allows access to servers with the `env:staging` and `env:dev` labels +and Kubernetes clusters with the `env:dev` label: ```yaml kind: role version: v7 metadata: - name: interns + name: developer spec: allow: - # Logins configures SSH login principals - logins: ['readonly'] - # Assigns users with this role to the built-in Kubernetes group "view" - kubernetes_groups: ["view"] - # Allow access to SSH nodes, Kubernetes clusters, apps or databases - # labeled with "staging" or "test" + logins: ['dev'] node_labels: - 'env': ['staging', 'test'] + 'env': ['staging', 'dev'] kubernetes_labels: 'env': 'dev' - kubernetes_resources: - - kind: * - namespace: "*" - name: "*" - verbs: ["*"] - app_labels: - 'type': ['monitoring'] - # The deny rules always override allow rules. - deny: - # deny access to any Node, database, app or Kubernetes cluster labeled - # as prod as any user. - node_labels: - 'env': 'prod' - kubernetes_labels: - 'env': 'prod' - kubernetes_resources: - - kind: "namespace" - name: "prod" - db_labels: - 'env': 'prod' - app_labels: - 'env': 'prod' ``` -Create a role using the `tctl create -f` command: - -```code -$ tctl create -f /tmp/interns.yaml -# Get a list of all roles in the system -$ tctl get roles --format text -``` +#### Read-only auditor -## Next steps +This role allows a user to read audit log entries: -- [Mapping SSO and local users traits with role templates](./guides/role-templates.mdx) -- [Create certs for CI/CD using impersonation](./guides/impersonation.mdx) +```yaml +kind: role +version: v7 +metadata: + name: auditor +spec: + allow: + rules: + - resources: ['session'] + verbs: ['list', 'read'] +``` +### RBAC for specific kinds of resources + +You can label all Teleport-protected resources and use those labels to set RBAC +policies. In addition, each kind of Teleport resource also has more specific +attributes that you can use to control access. Read the guides below to refine +your RBAC for each kind of resource: + +- [Servers](../../docs/pages/enroll-resources/server-access/rbac.mdx) +- [Databases](../../enroll-resources/database-access/rbac.mdx) +- [Kubernetes clusters](../../enroll-resources/kubernetes-access/controls.mdx) +- [Remote desktops](../../docs/pages/enroll-resources/desktop-access/rbac.mdx) +- [Web applications](../../enroll-resources/application-access/controls.mdx) + +### Best practices + +Keep these key principles in mind to maintain a secure environment: + +- **Regular audits**: +Periodically review and update RBAC policies to ensure they align with current organizational needs and security best practices. +- **Principle of least privilege**: +Always start with minimal access and gradually increase permissions as needed. Use descriptive role names that reflect their purpose. +- **Integration with identity providers (IdPs) like Okta and AWS OIDC**: +Leverage existing identity management systems to streamline user management and access control. +- **Monitoring and alerting**: +Set up comprehensive logging and alerting for access events, especially for sensitive resources. +- **User education**: +Ensure that all users understand their access levels and the importance of adhering to security policies. +Document your role configurations. + +## Further reading + +- [Mapping SSO and local users traits with role templates](../access-controls/guides/role-templates.mdx). +- [Add Labels to Resources](../management/admin/labels.mdx). +- [Access Control for Servers](../../enroll-resources/server-access/rbac.mdx). +- [Access Control for Kubernetes](../../enroll-resources/kubernetes-access/controls.mdx). +- [Enforce Device Trust with RBAC](./device-trust/device-trust.mdx). diff --git a/docs/pages/enroll-resources/kubernetes-access/kubernetes-access-examples.mdx b/docs/pages/enroll-resources/kubernetes-access/kubernetes-access-examples.mdx new file mode 100644 index 0000000000000..55dce6c782095 --- /dev/null +++ b/docs/pages/enroll-resources/kubernetes-access/kubernetes-access-examples.mdx @@ -0,0 +1,138 @@ +--- +title: Examples of Role-Based Access Control in Kubernetes +description: RBAC examples with Kubernetes. +--- + +In Teleport's flexible RBAC system, you can define custom roles and granularly control what users can do within your Kubernetes clusters. +Limit access to specific namespaces, enforce read-only permissions, or restrict administrative actions as needed. + +:Note: +Please reference [Setting Up Teleport Access Controls for Kubernetes](../../enroll-resources/kubernetes-access/manage-access.mdx) before proceeding, if you have not done so already. + +Here are a few common use cases. These are sample examples to get you started; for more in-depth coverage of roles in Kubernetes access, please visit the +[Access Controls guide](./controls.mdx) for Kubernetes. + +## Use case 1: Example role for developers + +In many organizations, developers need limited access to Kubernetes clusters, typically restricted to their development environments. + +Below is an example of a role that provides developers with access to only the dev namespace: + +```code +kind: role +version: v6 +metadata: + name: dev-k8s-access +spec: + allow: + kubernetes_groups: ["dev-group"] + kubernetes_labels: + "environment": "dev" # Allow access only to development clusters + kubernetes_resources: + - kind: pod + namespace: dev + - kind: service + namespace: dev + deny: + kubernetes_labels: + "environment": "prod" # Deny access to production clusters +``` + +In this example, the developers in the group dev-group are allowed to access the `dev` namespace's pods and services. Access to any production environments is explicitly denied, using the `deny` directive. + +## Use case 2: Read-only access for auditors + +In some scenarios, you may need to provide auditors with read-only access to a Kubernetes cluster for compliance purposes. The following auditor role grants read-only access to all namespaces +but does not allow any write operations: + +```code +kind: role +version: v6 +metadata: + name: auditor-k8s-read-only +spec: + allow: + kubernetes_groups: ["auditor-group"] + kubernetes_labels: + "*": "*" # Access to all clusters + kubernetes_resources: + - kind: pod + verbs: ["get", "list", "watch"] + - kind: service + verbs: ["get", "list", "watch"] + deny: + kubernetes_resources: + - kind: pod + verbs: ["create", "update", "delete"] # Deny any modification operations + - kind: service + verbs: ["create", "update", "delete"] +``` + +In this example, the auditor-group is allowed to access all namespaces (*), but only with `get`, `list`, and `watch` permissions (read-only). Modifications such as creating, updating, or deleting resources are denied. + +## Use case 3: Admin access to all Kubernetes clusters + +In organizations with DevOps or platform engineering teams, certain users need full administrative access to all Kubernetes clusters for management purposes. This role grants full access to all Kubernetes resources across all clusters, allowing the user to perform any action on any resource. + +```code +kind: role +version: v6 +metadata: + name: admin-k8s-access +spec: + allow: + kubernetes_groups: ["admin-group"] + kubernetes_labels: + "*": "*" # Allow access to all Kubernetes clusters + kubernetes_resources: + - kind: "*" # Allow access to all Kubernetes resources (pods, services, deployments, etc.) + verbs: ["*"] # Allow all verbs (get, list, create, delete, etc.) +``` + +In this example: + +- `kubernetes_groups` assigns the user to the admin-group, granting them permissions typically associated with cluster-admin roles in Kubernetes. +- `kubernetes_labels` provides access to all clusters, as denoted by `"*": "*"`. +- `kubernetes_resources` allows the user to interact with any Kubernetes resource type (denoted by "kind": "*"), including pods, services, deployments, config maps, and more. +- `verbs` grants all actions (denoted by "*"), which means users can get, list, create, update, and delete resources. + +This role is ideal for cluster administrators or platform engineers who need full control over Kubernetes resources across all environments (development, staging, production). + +## Use case 4: Access for CI/CD pipelines + +In certain cases, you may want to provide a specific user or service account (often used by a CI/CD pipeline) with limited permissions to deploy and manage resources in Kubernetes. This role is designed for automation systems, allowing them to deploy applications and update resources in a specific namespace without granting unnecessary permissions to other parts of the cluster. + +```code +kind: role +version: v6 +metadata: + name: cicd-k8s-access +spec: + allow: + kubernetes_groups: ["cicd-group"] + kubernetes_labels: + "environment": "prod" # Only allow access to production environments + kubernetes_resources: + - kind: deployment + namespace: prod # Only allow modifying deployments in the production namespace + verbs: ["get", "create", "update"] + - kind: service + namespace: prod + verbs: ["get", "create", "update"] + - kind: pod + namespace: prod + verbs: ["get", "list"] + deny: + kubernetes_resources: + - kind: deployment + namespace: prod + verbs: ["delete"] # Prevent the pipeline from deleting deployments +``` + +In this example we have: + +- `kubernetes_groups` which assigns the user (or service account) to the cicd-group, which represents the CI/CD pipeline's identity in Teleport. +- `kubernetes_labels` grants access to clusters labeled as "production" environments only. `kubernetes_resources` limits the pipeline’s actions to specific resources. +- `Deployment` allows the pipeline to get, create, and update deployments in the prod namespace. Similar permissions for `service`, so the pipeline can manage services associated with deployments. +- `Pod` allows listing and getting pods for status checks but denies permission to update or delete pods. +- `Deny rules` role explicitly prevents the pipeline from deleting any deployments, ensuring that destructive actions are restricted to human operators. \ No newline at end of file