diff --git a/docs/pages/admin-guides/access-controls/getting-started.mdx b/docs/pages/admin-guides/access-controls/getting-started.mdx
index 0bc74d3710db5..a1656c2eecac8 100644
--- a/docs/pages/admin-guides/access-controls/getting-started.mdx
+++ b/docs/pages/admin-guides/access-controls/getting-started.mdx
@@ -1,193 +1,172 @@
---
-title: Getting Started With Access Controls
-description: Get started using Teleport Access Controls.
+title: Getting Started With Role-Based Access Control
+description: Teleport Role-Based Access Control.
---
-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.
+In Teleport, RBAC (Role-Based Access Control) is a system that helps you manage who can access various resources such as 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.
+## What is RBAC in Teleport?
-## Prerequisites
+In Teleport, any local, SSO, or robot user can be assigned one or several roles. Roles govern access to your resources and infrastructure.
-(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+Each role defines specific permissions to ensure that users only have access to what they need.
-- (!docs/pages/includes/tctl.mdx!)
+## What is a role?
-(!docs/pages/includes/permission-warning.mdx!)
+Roles determine what resources a user can access and what actions they can perform within the system.
-## Step 1/3. Add local users with preset roles
+By creating and assigning roles, administrators can enforce security policies, manage access, and ensure users have the appropriate level of privileges based on their responsibilities.
-Teleport provides several preset roles:
+## Teleport users
-(!docs/pages/includes/preset-roles-table.mdx!)
+Users are entities that can authenticate and interact with the resources within a Teleport cluster. These users can have different levels of access depending on the roles assigned to them.
-
-
-Invite the local user Alice as cluster `editor`:
+Teleport supports both internal users and external users, which differ mainly in how they authenticate and how they are managed.
-```code
-$ tctl users add alice --roles=editor
-```
-
-
-Invite the local user Alice as cluster `editor` and `reviewer`:
+### Internal users
-```code
-$ tctl users add alice --roles=editor,reviewer
-```
-
+Internal users are created and managed directly within the Teleport cluster itself. Local users can be created via the CLI (tctl users add), by applying a user resource manifest (tctl create -f user.yaml) or
+via the web UI. Their roles and traits can be modified directly in Teleport.
-
+Internal users can authenticate using credentials managed within Teleport, such as:
+- Username and password
+- Multi-factor authentication (MFA), such as TOTP (time-based one-time passwords)
-Once Alice signs up, she will be able to edit cluster configuration. You can list
-users and their roles using `tctl users ls`.
+Internal users are assigned roles that define what resources they can access and what actions they can perform within the cluster. They are typically used for small to mid-size deployments where user management
+is handled directly in Teleport without relying on external identity providers.
-
-
-```code
-$ tctl users ls
+### External users
-# User Roles
-# -------------------- --------------
-# alice editor
-```
-
-
-```code
-$ tctl users ls
+External users authenticate using external Identity Providers (IdP), such as Okta, Google, GitHub, Microsoft Entra ID, or other SAML/OIDC providers. These users do not manage their passwords or credentials within Teleport itself. Instead, they authenticate using their external SSO credentials. For example, a user in the "admin" group in Okta can be mapped to the admin role in Teleport.
-# User Roles
-# -------------------- --------------
-# alice editor, reviewer
-```
-
+External users are useful for larger organizations or those that want to centralize identity management via an existing SSO provider. This is often preferred for enterprise environments where identity management is handled outside Teleport.
-
+### Robots
-You can update the user's roles using the `tctl users update` command:
+Machine ID provides machines with an identity that can authenticate to the Teleport cluster. This identity is known as a robot. Robots are represented in Teleport by a user and a role resource and can be created via the tctl bots add command. Unlike human users, who use a password, MFA, or SSO, robot users join the cluster as Teleport services using a join method. They can still join even if local auth is disabled.
-
-
-```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
-```
-
+See the [Machine ID introduction](../../../enroll-resources/machine-id/introduction.mdx) for more information.
+
+## Teleport roles
-
+Some examples of roles include:
-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.
+- **access**: Grants basic access to resources.
+- **editor**: Allows users to modify configuration settings.
+- **auditor**: Allows users to view logs and auditing activities.
-## Step 2/3. Map SSO users to roles
+Roles enforce Role-Based Access Control (RBAC), ensuring that users only have the permissions needed for their specific tasks.
+See [Teleport Access Controls Reference](../../../reference/access-controls/roles.mdx) for in-depth information about types of roles, options, and usage.
-Next, follow the instructions to set up an authentication connector that maps
-users within your SSO solution to Teleport roles.
+## Understanding Teleport’s Resource Tagging and Matching
-### Teleport Enterprise
+Before configuring RBAC, it’s essential to understand how Teleport tags and matches resources to users’ 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.
+- Resource Tagging: Teleport uses labels (key-value pairs) to tag resources like SSH nodes, databases, or Kubernetes clusters. For example, a server might have the label env: production.
+- Role Matching: A role in Teleport allows or denies access to resources based on matching these labels. For instance, if a user has a role that allows access to resources labeled env: staging, they will only access resources with that label.
-
-
+You can use this labeling and matching logic to grant users specific access, ensuring they only interact with the resources they need.
-Follow our [SAML Okta Guide](./sso/okta.mdx) to
-create a SAML application.
+## Understanding Teleport’s YAML Configuration
-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`.
+Teleport’s roles are defined using YAML. Here’s a breakdown of a basic role configuration:
+
+- **kind**: The type of resource being created. For roles, this will always be role.
+- **metadata**: Includes information like the role’s name, which is used to identify the role.
+- **spec**: This section defines what the role can and cannot do.
+- **allow**: Lists the permissions the role grants, such as allowed logins or access to resources based on labels.
+- **deny**: Specifies any permissions that should be explicitly denied, even if they would otherwise be allowed.
+
+## Creating a Basic Role for SSH Access
+
+- (!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+### Step 1/3
+
+Let’s set up a simple role that gives users access to staging servers for SSH access. Create a role definition file called staging-access.yaml with the following content:
```yaml
-kind: saml
-version: v2
+kind: role
+version: v7
metadata:
- name: okta
+ name: staging-access
spec:
- acs: https://tele.example.com/v1/webapi/saml/acs
- attributes_to_roles:
- - {name: "groups", value: "okta-admin", roles: ["access"]}
- entity_descriptor: |
-
-
+### Step 3/3
-Follow our [OIDC guides](./sso/oidc.mdx#identity-providers) to
-create an OIDC application.
+Assigning the Role to a User
-Copy the YAML below to a file called `oidc.yaml` and edit the information to
-include the details of your OIDC application.
+Now that you’ve created a role, assign it to a local user named Alice:
-```yaml
-(!examples/resources/oidc-connector.yaml!)
+```code
+$ tctl users add alice --roles=staging-access
```
-Create the `oidc` resource:
+Alice can now log in to staging servers, but she will be blocked from production environments.
+
+## 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 create okta.yaml
+$ tctl users add alice --roles=editor
```
-
-
+Invite the local user Alice as cluster `editor` and `reviewer`:
-### Teleport Community Edition
+```code
+$ tctl users add alice --roles=editor,reviewer
+```
-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`.
+Once Alice signs up, she will be able to edit cluster configuration. You can list
+users and their roles using `tctl users ls`.
-```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"]
+
+```code
+$ tctl users ls
+
+# User Roles
+# -------------------- --------------
+# alice editor, reviewer
+```
+
+You can update the user's roles using the `tctl users update` command:
+
+```code
+$ tctl users update alice --set-roles=editor,auditor
```
-Create the `github` resource:
+Once Alice logs back in, she will be able to view audit logs.
```code
-$ tctl create github.yaml
+$ tctl users update alice --set-roles=editor,reviewer,auditor
```
-## Step 3/3. Create a custom role
+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.
+
+## Create a custom role
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
@@ -244,8 +223,25 @@ $ tctl create -f /tmp/interns.yaml
$ tctl get roles --format text
```
-## Next steps
+Next, follow the instructions to set up an authentication connector that maps users within your SSO solution to Teleport roles. Follow the instructions to set up an authentication connector that maps users within your [SSO solution](../../../admin-guides/access-controls/sso) to Teleport roles.
+
+## Best practices
-- [Mapping SSO and local users traits with role templates](./guides/role-templates.mdx)
-- [Create certs for CI/CD using impersonation](./guides/impersonation.mdx)
+- **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.
+- **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.
+
+## Next steps
+- [Mapping SSO and local users traits with role templates](../../access-controls/guides/role-templates.mdx)
+- [Access Control for Servers](../../../enroll-resources/server-access/rbac.mdx)
+- [Access Control for Kubernetes](../../../enroll-resources/kubernetes-access/controls.mdx)
+- [Enroll a Kubernetes Cluster](../../../enroll-resources/kubernetes-access/getting-started.mdx)
+- [Create certs for CI/CD using impersonation](../../../admin-guides/access-controls/guides/impersonation.mdx)
\ No newline at end of file
diff --git a/docs/pages/admin-guides/access-controls/resource-rbac.mdx b/docs/pages/admin-guides/access-controls/resource-rbac.mdx
new file mode 100644
index 0000000000000..78e9f14073286
--- /dev/null
+++ b/docs/pages/admin-guides/access-controls/resource-rbac.mdx
@@ -0,0 +1,89 @@
+---
+title: Getting Started With Per-Resource Role-Based Access Control
+description: Implementing fine-grained access control with RBAC.
+---
+
+Per-resource RBAC enables administrators to control user access on a per-resource basis. Using a granular approach allows you to grant more precise management of user permissions in your environment.
+
+## What is per-resource RBAC?
+
+This capability is particularly useful in complex, multi-tenant environments where user groups have varying levels of access requirements. It allows for precise control over permissions, enabling restricted access to sensitive resources for certain users while granting broader access to others based on their operational needs.
+
+## Use cases
+
+### Multi-tenant environments
+
+In a multi-tenant setup, per-resource RBAC can ensure that each client or team has access only to their specific resources, preventing any accidental or intentional cross-tenant access.
+
+### Compliance requirements
+For industries with strict regulatory requirements (e.g., finance, healthcare), per-resource RBAC helps in implementing and demonstrating compliance with access control policies.
+
+### Team management
+For new team members or roles, per-resource RBAC facilitates a gradual increase in access privileges as users become more familiar with the systems and demonstrate need and competence.
+When working with external contractors, per-resource RBAC allows granting temporary, limited access to specific resources without exposing the entire infrastructure.
+
+### DevOps workflows
+In CI/CD pipelines, different stages may require different levels of access; per-resource RBAC can be used to grant just-in-time access for specific tasks in the pipeline.
+
+Let's look at some examples of how per-resource RBAC can be implemented:
+
+**SSH access control**
+
+```code
+kind: role
+version: v3
+metadata:
+ name: dev-team
+spec:
+ allow:
+ logins: ['ubuntu']
+ node_labels:
+ environment: ['dev', 'staging']
+ rules:
+ - resources: ['session']
+ verbs: ['read', 'list']
+```
+
+This role allows members of the dev team to SSH into nodes labeled as 'dev' or 'staging' environments, using the 'ubuntu' user account.
+They can also read and list session information.
+
+**Kubernetes access control**
+
+```code
+kind: role
+version: v3
+metadata:
+ name: k8s-dev
+spec:
+ allow:
+ kubernetes_groups: ['system:developers']
+ kubernetes_resources:
+ - kind: pod
+ namespace: 'dev-*'
+ verbs: ['get', 'list', 'create', 'update', 'delete']
+ - kind: service
+ namespace: 'dev-*'
+ verbs: ['get', 'list']
+```
+
+This role grants developers access to manage pods in any namespace starting with 'dev-', while only allowing them to view services in those namespaces.
+
+**Database access control**
+
+```code
+kind: role
+version: v3
+metadata:
+ name: db-readonly
+spec:
+ allow:
+ db_labels:
+ environment: ['production']
+ type: ['postgres']
+ db_names: ['analytics', 'reporting']
+ db_users: ['readonly']
+```
+
+This role provides read-only access to production PostgreSQL databases named 'analytics' and 'reporting' using the 'readonly' database user.
+
+
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..93eeca6f74d74
--- /dev/null
+++ b/docs/pages/enroll-resources/kubernetes-access/kubernetes-access-examples.mdx
@@ -0,0 +1,140 @@
+---
+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 simple examples to get you started; for more in-depth coverage of roles in Kubernetes access, please visit the [Kubernetes Access Controls guide](../../enroll-resources/kubernetes-access/controls.dx).
+
+## 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