docs: rbac getting started guide

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. 
 
-<Tabs>
-<TabItem scope={["oss"]} label="Teleport Community Edition">
-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
-```
-</TabItem>
-<TabItem scope={["enterprise", "cloud"]} label="Commercial">
-Invite the local user Alice as cluster `editor` and `reviewer`:
+### Internal users
 
-```code
-$ tctl users add alice --roles=editor,reviewer
-```
-</TabItem>
+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.
 
-</Tabs>
+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.
 
-<Tabs>
-<TabItem scope={"oss"} label="Teleport Community Edition">
-```code
-$ tctl users ls
+### External users
 
-# User                 Roles
-# -------------------- --------------
-# alice                editor
-```
-</TabItem>
-<TabItem scope={["enterprise", "cloud"]} label="Commercial">
-```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
-```
-</TabItem>
+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.
 
-</Tabs>
+### 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.
 
-<Tabs>
-<TabItem scope={"oss"} label="Teleport Community Edition">
-```code
-# Once Alice logs back in, she will be able to view audit logs
-$ tctl users update alice --set-roles=editor,auditor
-```
-</TabItem>
-<TabItem scope={["enterprise", "cloud"]} label="Commercial">
-```code
-# Once Alice logs back in, she will be able to view audit logs
-$ tctl users update alice --set-roles=editor,reviewer,auditor
-```
-</TabItem>
+See the [Machine ID introduction](../../enroll-resources/machine-id/introduction.mdx) for more information.
+
+## Teleport roles
 
-</Tabs>
+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.
 
-<Tabs>
-<TabItem label="SAML">
+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: |
-    <?xml !!! Make sure to shift all lines in XML descriptor
-    with 4 spaces, otherwise things will not work
+  allow:
+    logins: ['dev']
+    node_labels:
+      'env': 'staging'
+  deny:
+    node_labels:
+      'env': 'production'
+
 ```
 
-Create the `saml` resource:
+### Step 2/3
+
+Apply this role using the following command:
 
 ```code
-$ tctl create okta.yaml
+$ tctl create -f staging-access.yaml
 ```
+This role allows the user to log in as the `dev` user to servers labeled with `env: staging` and explicitly denies access to any server labeled `env: production`.
 
-</TabItem>
-<TabItem label="OIDC">
+### 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
 ```
 
-</TabItem>
-</Tabs>
+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 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)