Server Access RBAC Docs page (gravitational#20246)

* Server Access RBAC Docs page * verbiage change Co-authored-by: Zac Bergquist <[email protected]> * verbiage change Co-authored-by: Zac Bergquist <[email protected]> * verbiage change Co-authored-by: Zac Bergquist <[email protected]> * Addressed comments * Verbiage update Co-authored-by: Paul Gottschling <[email protected]> * verbiage update Co-authored-by: Paul Gottschling <[email protected]> * verbiage update Co-authored-by: Paul Gottschling <[email protected]> * verbiage update Co-authored-by: Paul Gottschling <[email protected]> * wording update Co-authored-by: Paul Gottschling <[email protected]> * verbiage update Co-authored-by: Paul Gottschling <[email protected]> * change Co-authored-by: Paul Gottschling <[email protected]> * verbiage Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * verbiage change Co-authored-by: Paul Gottschling <[email protected]> * Add trusted cluster def * Update docs/pages/server-access/rbac.mdx Co-authored-by: Paul Gottschling <[email protected]> * Update docs/pages/server-access/rbac.mdx Co-authored-by: Paul Gottschling <[email protected]> --------- Co-authored-by: Zac Bergquist <[email protected]> Co-authored-by: Paul Gottschling <[email protected]>
Somith11 · Mar 1, 2023 · 9926da7 · 9926da7
1 parent 6fd8a23
commit 9926da7
Show file tree

Hide file tree

Showing 2 changed files with 190 additions and 0 deletions.
diff --git a/docs/config.json b/docs/config.json
@@ -750,6 +750,10 @@
               "slug": "/server-access/guides/ansible/"
             }
           ]
+        },
+        {
+          "title": "Access Controls",
+          "slug": "/server-access/rbac/"
         }
       ]
     },

diff --git a/docs/pages/server-access/rbac.mdx b/docs/pages/server-access/rbac.mdx
@@ -0,0 +1,186 @@
+---
+title: Access Controls for Servers
+description: Role-based access control (RBAC) for Teleport Server Access.
+---
+
+
+You can use Teleport's role-based access control (RBAC) system to set up
+granular permissions for authenticating to Linux servers connected to Teleport.
+
+An example of a policy could be, *Server administrators have access to
+everything, the QA team and engineers have full access to staging servers, and
+engineers can gain temporary access to production servers in case of
+emergency.*
+
+For a more general description of Teleport roles and examples see our [Access Controls guides](../access-controls/introduction.mdx), as
+this section focuses on configuring RBAC for servers connected to Teleport.
+
+## Role configuration
+
+Teleport's "role" resource provides the following instruments for restricting
+server access:
+
+```yaml
+kind: role
+version: v5
+metadata:
+  name: developer
+spec:
+  allow:
+    # The logins array defines the OS/UNIX logins a user is allowed to use.
+    # both strings and template variables are supported in this field
+    logins: [ubuntu, debian, '{{internal.logins}}']
+
+    # node_labels: a user with this role will be allowed to connect to
+    # SSH nodes whose labels match any of the expressions below.
+    node_labels:
+      # literal strings:
+      'env': 'test'
+      # the wildcard ('*') means "any node"
+      '*': '*'
+      # a list of allowed values:
+      'region': ['us-west-1', 'eu-central-1']
+      # regular expressions start with ^ and end with $
+      # Teleport uses Golang's regexp syntax.
+      # the list example above can be expressed as:
+      'reg': '^us-west-1|eu-central-1$'
+
+    # List of host groups the created user will be added to. Any that don't already exist are created.
+    host_groups: [ubuntu, nginx, other]
+
+    # Assign the user to the sudoers group
+    host_sudoers:
+    - 'ALL=(ALL) NOPASSWD: ALL'
+
+    # Deny access to the root user
+  deny:
+    logins:
+    - root
+```
+
+<Admonition
+  type="note"
+  title="Deny Rules"
+>
+  Deny rules will match greedily. In the example above, a server session
+  attempting to use the "root" server user  account will be rejected.
+</Admonition>
+
+## Template variables
+
+Similar to role fields for accessing other resources in Teleport, server-related fields support template variables.
+
+Variables with the format `{{external.xyz}}` are replaced with values from external [SSO](../access-controls/sso.mdx)
+providers. For OIDC logins, `{{external.xyz}}` refers to the "xyz" claim; for
+SAML logins, `{{external.xyz}}` refers to the "xyz" assertion.
+
+For example, here is what a role may look like if you want to assign allowed
+server environment types and allowed logins from the user's Okta `environments` and 
+`allowedlogins` assertions:
+
+```yaml
+spec:
+  allow:
+    node_labels:
+    - env:  '{{external.environments}}'
+    logins:
+    - '{{external.allowedlogins}}'
+```
+
+The `{{internal.logins}}` variable applies to local users
+and works with Teleport Trusted Clusters. Trusted Clusters allow
+connecting via a root Teleport cluster to resources connected to other Teleport clusters.
+Those Teleport clusters, identified as leaf clusters, allow the connection
+by trusting the root Teleport cluster.
+
+For example, suppose a user in the root cluster has the following role.  As a
+local user they could have the `logins` trait of `jeff` so they have two logins, `jeff`
+and `ubuntu`.
+
+```yaml
+spec:
+  allow:
+    logins: ['{{internal.logins}}', ubuntu]
+```
+
+The role on the leaf cluster can be set up to use the user's allowed server
+accounts and names. The leaf cluster will then include the same logins allowed from the root
+cluster when the `{{internal.logins}}` template variable is used.
+
+```yaml
+spec:
+  allow:
+    logins: ["{{internal.logins}}"]
+```
+
+## Server role options
+
+The `allow` and `deny` sections described above are used for controlling
+the servers and logins allowed. Role options provide the Teleport features
+available for users with the specified role. These options apply to Server access.
+
+```yaml
+spec:
+  allow:
+    #....
+  options:
+    # Controls whether this role supports auto provisioning of users.
+    create_host_user: true
+    # forward_agent controls whether SSH agent forwarding is allowed
+    forward_agent: true
+    # port_forwarding controls whether TCP port forwarding is allowed for SSH
+    port_forwarding: true
+    # ssh_file_copy controls whether file copying (SCP/SFTP) is allowed.
+    # Defaults to true.
+    ssh_file_copy: false
+    # client_idle_timeout determines if SSH sessions to cluster nodes are
+    # forcefully terminated after no activity from a client (idle client).
+    # It overrides the global cluster setting. examples: "30m", "1h" or "1h30m"
+    client_idle_timeout: never
+    # Determines if the clients will be forcefully disconnected when their
+    # certificates expire in the middle of an active session.
+    # It overrides the global cluster setting.
+    disconnect_expired_cert: no
+    # max_sessions is total number of session channels that can be established
+    # across a single connection. Setting it to 10 matches OpenSSH default behavior.
+    max_sessions: 10
+    # Defines which events are recorded by the BPF-based session recorder.
+    enhanced_recording:
+    - command
+    - disk
+    - network
+    # permit_x11_forwarding allows users to use X11 forwarding with openssh
+    # clients and servers through the proxy
+    permit_x11_forwarding: true
+    # The Enterprise-only max_connections field sets a limit of concurrent sessions within a
+    # cluster. This setting slows down Teleport performance because it has to track
+    # connections cluster-wide.
+    max_connections: 2
+    # Define how Teleport deals with session recording failures, such as a full
+    # disk error. The value can be set to either `best_effort` or `strict`. If
+    # set to `strict`, the session will terminate immediately. If set to
+    # `best_effort`, the session won’t be terminated, and the recording will be
+    # disabled. The configuration is done per service (currently, only `ssh` is
+    # supported).
+    record_session:
+      # Optional: the default session recording mode to use when a
+      # protocol-specific mode is not set.
+      default: best_effort|strict
+      # Optional: Session recording mode for SSH sessions. 
+      # If not set, the value set on default will be used.
+      ssh: best_effort|strict
+    # Enterprise-only: when enabled, the source IP that was used to log in is embedded in the SSH
+    # certificate, preventing a compromised certificate from being used on other
+    # devices. The default is false.
+    # Note: Source IP pinning is currently in Preview mode.
+    pin_source_ip: true
+    # Specify a list of names and associated values to be included in user SSH keys.
+    # The key type can only be "ssh" and the mode can only be "extension".
+    # The name and value fields can be arbitrary strings and the value field
+    # supports variable interpolation.
+    cert_extensions:
+     - type: ssh
+       mode: extension
+       name: [email protected]
+       value: "{{ external.github_login }}"
+```
-Original file line number
+Diff line change
@@ Expand Up / @@ -750,6 +750,10 @@ @@
                   "slug": "/server-access/guides/ansible/"
                 }
               ]
+            },
+            {
+              "title": "Access Controls",
+              "slug": "/server-access/rbac/"
             }
           ]
         },
@@ Expand Down @@