Configure RBAC

This topic explains how to configure role-based access control (RBAC) in Tanzu Kubernetes Grid.

About Configuring RBAC

If you intend to use standard, non-admin kubeconfig files for cluster access, you must configure RBAC authorization after enabling and configuring identity management. For more information about kubeconfig files, see Admin and Non-Admin kubeconfig Files below.

To configure RBAC authorization, you create one or more role bindings for each management and workload cluster where you want to use standard, non-admin kubeconfig files:

After you enable and configure identity management as decribed in Configure Identity Management, create one or more role bindings for the management cluster. For instructions, see Configure RBAC for a Management Cluster below.
Create one or more role bindings for each workload cluster. For instructions, see Configure RBAC for a Workload Cluster below.

For more information about role bindings, see Roles and Role Bindings below.

Admin and Non-Admin `kubeconfig` Files

To give users access to a management or a workload cluster, you generate a kubeconfig file and then share the file with those users. If you provide them with the admin kubeconfig for the cluster, they have full access to the cluster and do not need to be authenticated. However, if you provide users with the standard, non-admin kubeconfig, they must have a user account in your OIDC or LDAP identity provider and you must configure RBAC on the cluster to grant access permissions to the designated user.

To generate a kubeconfig file for a management or a workload cluster, you run tanzu mc kubeconfig get against the management cluster or tanzu cluster kubeconfig get against the workload cluster. When running either of these commands with or without the --admin option, the command works as follows:

With --admin, the command generates an admin kubeconfig that contains embedded credentials. With this admin version of the kubeconfig, any users with whom you share it will have full access to the cluster and identity provider (IdP) authentication is bypassed.
Without --admin, the command generates a standard, non-admin kubeconfig that prompts users to authenticate with an external identity provider. The identity provider then verifies the user’s identity before the user can access the cluster’s resources.

For more information about these commands, see:

Roles and Role Bindings

A role defines a set of permissions. You can define a role within a specific namespace by creating a Role or cluster-wide role by creating a ClusterRole. To grant the permissions defined in that role to a user or group of users, you must create a role binding.

Resource	Scope	Description
`Role`	Namespace	Defines permissions that can be used in a namespace-specific `RoleBinding`.
`ClusterRole`	Cluster	Defines permissions that can be used in a `ClusterRoleBinding` or namespace-specific `RoleBinding`.
`RoleBinding`	Namespace	Grants permissions within a specific namespace. Can reference a `Role` or `ClusterRole`.
`ClusterRoleBinding`	Cluster	Grants permissions across all namespaces in the cluster. Can reference only a `ClusterRole`.

Default user roles include:

cluster-admin: Full access to the cluster. When used in a RoleBinding, this role gives full access to any resource in the namespace specified in the binding.
admin: Admin access to most resources in a namespace. Can create and modify roles and role bindings within the namespace.
edit: Read-write access to most objects in a namespace, such as deployments, services, and pods. Cannot view, create, or modify roles and role bindings.
view: Read-only access to most objects in a namespace. Cannot view, create, or modify roles and role bindings.

For more information about these roles, see Using RBAC Authorization in the Kubernetes documentation.

Configure RBAC for a Management Cluster

This section explains how to:

Generate and Test a Non-Admin kubeconfig File for the Management Cluster
Create a Role Binding on the Management Cluster

Generate and Test a Non-Admin `kubeconfig` File for the Management Cluster

This procedure allows you to test the login step of the authentication process if a browser is present on the machine on which you are running tanzu and kubectl commands. If the machine does not have a browser, see Authenticate Users on a Machine Without a Browser (LDAP).

Export the standard kubeconfig for the management cluster to a local file, for example, /tmp/id_mgmt_test_kubeconfig. Note that the command does not include the --admin option, so the kubeconfig that is exported is the standard kubeconfig, not the admin version.
```
tanzu mc kubeconfig get --export-file /tmp/id_mgmt_test_kubeconfig
```
You should see confirmation that You can now access the cluster by specifying '--kubeconfig /tmp/id_mgmt_test_kubeconfig' flag when using 'kubectl' command.
Connect to the management cluster by using the newly created kubeconfig file:
```
kubectl get pods -A --kubeconfig /tmp/id_mgmt_test_kubeconfig
```
The authentication process requires a browser to be present on the machine from which users connect to clusters because running kubectl commands automatically opens the IdP login page so that users can log in to the cluster. Your browser should open and display the login page for your OIDC provider or an LDAPS login page.

LDAPS:

OIDC:

Enter the credentials of a user account that exists in your OIDC or LDAP server. After a successful login, the browser should display the following:
Go back to the terminal in which you run tanzu and kubectl commands:
- If you already configured a role binding on the cluster for the authenticated user, the output of kubectl get pods -A appears, displaying the pod information.
- If you have not configured a role binding on the cluster, you see a message denying the user account access to the pods: Error from server (Forbidden): pods is forbidden: User "user@example.com" cannot list resource "pods" in API group "" at the cluster scope. This happens because the user has been successfully authenticated, but they are not yet authorized to access any resources on the cluster. To authorize the user to access the cluster resources, you must Create a Role Binding on the Management Cluster as described below.

Create a Role Binding on the Management Cluster

To give non-admin users access to a management cluster, you generate and distribute a kubeconfig file as described in Generate and Test a Non-Admin kubeconfig File for the Management Cluster above. To make this kubeconfig work, you must first set up RBAC by creating a role binding on the management cluster. This role binding assigns role-based permissions to individual authenticated users or user groups.

To create a role binding:

Make sure that you are using the admin context of the management cluster:
```
kubectl config current-context
```
If the context is not the management cluster admin context, set kubectl to use that context. For example:
```
kubectl config use-context id-mgmt-test-admin@id-mgmt-test
```
List your existing roles:
- To see the full list of namespace-scoped roles, run:
```
kubectl get roles --all-namespaces
```
- To see the full list of cluster-scoped roles, run:
```
kubectl get clusterroles
```
To associate a given user with a role, create a role binding.
- A RoleBinding can reference a Role or ClusterRole.
- A ClusterRoleBinding can reference only a ClusterRole.
The following example creates a cluster role binding named id-mgmt-test-rb that binds the cluster role cluster-admin to the user user@example.com:
```
kubectl create clusterrolebinding id-mgmt-test-rb --clusterrole cluster-admin --user user@example.com
```
For --user, specify the OIDC or LDAP username of the user. You configured the username attribute and other identity provider details in the Identity Management section of the Tanzu Kubernetes Grid installer interface or by setting the LDAP_* or OIDC_* variables:
- OIDC: The username attribute is set in the Username Claim field under OIDC Identity Management Source in the installer interface or the OIDC_IDENTITY_PROVIDER_USERNAME_CLAIM configuration variable.
- LDAPS: The username attribute is set in the Username field under LDAPS Identity Management Source –> User Search Attributes in the installer interface or the LDAP_USER_SEARCH_NAME_ATTRIBUTE configuration variable.
For example, for OIDC, the username is often the email address of the user. For LDAPS, it is the LDAP username, not the email address.
Attempt to connect to the management cluster again by using the kubeconfig file that you created in the previous procedure:
```
kubectl get pods -A --kubeconfig /tmp/id_mgmt_test_kubeconfig
```
This time, because the user is bound to the cluster-admin role on this management cluster, the list of pods should be displayed. You can share the generated kubeconfig file with any users for whom you configure role bindings on the management cluster.

Configure RBAC for a Workload Cluster

This section explains how to:

Generate and Test a Non-Admin kubeconfig File for a Workload Cluster
Create a Role Binding on a Workload Cluster

Generate and Test a Non-Admin `kubeconfig` File for a Workload Cluster

To authenticate users on a workload cluster, perform the following steps:

Obtain the standard, non-admin kubeconfig for the workload cluster and export it to a file. The below example exports the kubeconfig for the cluster my-cluster to the file my-cluster-kubeconfig.
```
tanzu cluster kubeconfig get my-cluster --export-file /tmp/my-cluster-kubeconfig
```
Use the generated file to attempt to run an operation on the cluster. For example, run:
```
kubectl get pods -A --kubeconfig /tmp/my-cluster-kubeconfig
```
You should be redirected to the log in page for your identity provider. After successfully logging in with a user account from your identity provider, if you already configured a role binding on the cluster for the authenticated user, the output shows the pod information.

If you have not configured a role binding on the cluster, you see the message Error from server (Forbidden): pods is forbidden: User "<user>" cannot list resource "pods" in API group "" at the cluster scope. This happens because this user does not have any permissions on the cluster yet. To authorize the user to access the cluster resources, you must Create a Role Binding on a Workload Cluster.

Create a Role Binding on a Workload Cluster

To complete the identity management configuration of the workload cluster, you must create role bindings for the users who use the kubeconfig that you generated in the preceding step.

Set the kubectl context to the workload cluster’s admin kubeconfig. You need to switch to the workload cluster’s admin context so that you can create a role binding. For example, run the following two commands to change to the admin context:
1. Get the kubeconfig:
```
tanzu cluster kubeconfig get my-cluster --admin
```
2. Switch context:
```
kubectl config use-context my-cluster-admin@my-cluster
```
To view your existing roles:
- To see the full list of namespace-scoped roles, run:
```
kubectl get roles --all-namespaces
```
- To see the full list of cluster-scoped roles, run:
```
kubectl get clusterroles
```
To associate a given user with a role, create a role binding.
- A RoleBinding can reference a Role or ClusterRole.
- A ClusterRoleBinding can reference only a ClusterRole.
The following example creates a cluster role binding named workload-test-rb that binds the cluster role cluster-admin to the user user@example.com:
```
kubectl create clusterrolebinding workload-test-rb --clusterrole cluster-admin --user user@example.com
```
For --user, specify the OIDC or LDAP username of the user. You configured the username attribute and other identity provider details in the Identity Management section of the Tanzu Kubernetes Grid installer interface or by setting the LDAP_* or OIDC_* variables:
- OIDC: The username attribute is set in the Username Claim field under OIDC Identity Management Source in the installer interface or the OIDC_IDENTITY_PROVIDER_USERNAME_CLAIM configuration variable.
- LDAPS: The username attribute is set in the Username field under LDAPS Identity Management Source –> User Search Attributes in the installer interface or the LDAP_USER_SEARCH_NAME_ATTRIBUTE configuration variable.
For example, for OIDC, the username is often the email address of the user. For LDAPS, it is the LDAP username, not the email address.
Use the standard kubeconfig file that you generated above to attempt to run an operation on the cluster again. For example, run:
```
kubectl get pods -A --kubeconfig /tmp/my-cluster-kubeconfig
```
This time, you should see the list of pods that are running in the workload cluster. This is because the user of the my-cluster-kubeconfig file has both been authenticated by your identity provider and has the necessary permissions on the cluster. You can share the my-cluster-kubeconfig file with any users for whom you configure role bindings on the cluster.

What to Do Next

Share the generated kubeconfig files with other users to allow them access to the clusters.