Managing Tanzu Kubernetes Grid Integrated Edition Users with UAA

This topic describes how to manage users in VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) with User Account and Authentication (UAA).

Overview

UAA is the identity management service for Tanzu Kubernetes Grid Integrated Edition. Tanzu Kubernetes Grid Integrated Edition includes a UAA server, which is hosted on the TKGI API VM.

To interact with the UAA server, you can use the UAA Command Line Interface (UAAC). You can either run UAAC commands from the Ops Manager VM or install UAAC on your local workstation.

UAA Scopes for Tanzu Kubernetes Grid Integrated Edition Users

By assigning UAA scopes, you grant users the ability to create, manage, and audit Kubernetes clusters in Tanzu Kubernetes Grid Integrated Edition.

A UAA admin user can assign the following UAA scopes to Tanzu Kubernetes Grid Integrated Edition users:

pks.clusters.admin: Accounts with this scope can create and access all clusters.
pks.clusters.manage: Accounts with this scope can create and access their own clusters.
pks.clusters.admin.read: Accounts with this scope can access any information about all clusters except for cluster credentials.

You can assign these scopes to individual users, external identity provider groups, or clients for automation purposes.

For more information about UAA scopes in Tanzu Kubernetes Grid Integrated Edition, see UAA Scopes.

Prerequisites

Before managing users for Tanzu Kubernetes Grid Integrated Edition, you must connect to the TKGI API VM. To connect to the TKGI API VM, you need one of the following:

SSH access to the Ops Manager VM
A machine that can connect to your TKGI API VM

For instructions on how to connect to the TKGI control plane, see Connect to the TKGI API VM for your IaaS.

Log In as a UAA Admin

Before creating TKGI users, you must log in to the UAA server as a UAA admin. To log in to the UAA server, do the following:

Retrieve the UAA management admin client secret:
1. In a web browser, navigate to the Ops Manager Installation Dashboard and click the Tanzu Kubernetes Grid Integrated Edition tile.
2. Click the Credentials tab.
3. Click Link to Credential next to Pks Uaa Management Admin Client and copy the value of
  secret.
Target your UAA server by running the following command:
```
uaac target https://TKGI-API:8443 --ca-cert CERTIFICATE-PATH
```
Where:
- TKGI-API is the domain name of your TKGI API server. You entered this domain name in the Tanzu Kubernetes Grid Integrated Edition tile > TKGI API > API Hostname (FQDN).
- CERTIFICATE-PATH is the path to your Ops Manager root CA certificate. Provide this certificate to validate the TKGI API certificate with SSL.
  - If you are logged in to the Ops Manager VM, specify /var/tempest/workspaces/default/root_ca_certificate as the path. This is the default location of the root certificate on the Ops Manager VM.
  - If you downloaded the Ops Manager root CA certificate to your machine, specify the path where you stored the certificate.
  For example:
```
$ uaac target api.tkgi.example.com:8443 --ca-cert /var/tempest/workspaces/default/root_ca_certificate
```
  Note: If you receive an Unknown key: Max-Age = 86400 warning message, you can ignore it because it has no impact.
Authenticate with UAA by running the following command:
```
uaac token client get admin -s ADMIN-CLIENT-SECRET
```
Where ADMIN-CLIENT-SECRET is your UAA management admin client secret that you retrieved in a previous step. The client user name is admin.

Grant Tanzu Kubernetes Grid Integrated Edition Access to an Individual User

To create a new UAA user with Tanzu Kubernetes Grid Integrated Edition access, do the following:

If you are not logged in as the UAA admin, perform the steps in Log In as a UAA Admin.
Create a new user by running the following command:
```
uaac user add USERNAME --emails USER-EMAIL -p USER-PASSWORD
```
For example:
```
$ uaac user add cody --emails [email protected] -p password
```
Note: If your operator has configured Tanzu Kubernetes Grid Integrated Edition to use a SAML identity provider, you must add –origin SAML-ORIGIN to the above command.SAML-ORIGIN is the domain name for your SAML identity provider. To find SAML-ORIGIN, click the TKGI tile, select Settings > UAA > SAML, and locate the Provider Name. For information about configuring SAML, see Connecting Tanzu Kubernetes Grid Integrated Edition to a SAML Identity Provider.
Assign a TKGI cluster scope to the new user by running the following command:
```
uaac member add UAA-SCOPE USERNAME
```
Where:
- UAA-SCOPE is one of the UAA scopes described in UAA Scopes for Tanzu Kubernetes Grid Integrated Edition Users.
- USERNAME is the user that you created in the previous step.
For example:
```
$ uaac member add pks.clusters.admin cody
```

After you assign this scope, the user can create and manage Kubernetes clusters. For more information, see Managing Kubernetes Clusters and Workloads.

Grant Tanzu Kubernetes Grid Integrated Edition Access to an External Group

Connecting Tanzu Kubernetes Grid Integrated Edition to an external LDAP or SAML user store enables the UAA server to delegate authentication to existing enterprise user stores.

Note: When integrating UAA with an external identity provider, authentication within UAA becomes chained. UAA first attempts to authenticate with user credentials against the UAA user store before the external identity provider. For more information about integrating LDAP, see Chained Authentication in the User Account and Authentication LDAP Integration GitHub documentation.

For more information about the process used by the UAA server when it attempts to authenticate a user through LDAP, see the Configuring LDAP integration with VMware Tanzu Application Service (TAS) for VMs Knowledge Base article.

To grant Tanzu Kubernetes Grid Integrated Edition access to an external identity provider group, do one the following procedures:

Grant Tanzu Kubernetes Grid Integrated Edition Access to an External LDAP Group
Grant Tanzu Kubernetes Grid Integrated Edition Access to an External SAML Group

Grant Tanzu Kubernetes Grid Integrated Edition Access to an External LDAP Group

To grant Tanzu Kubernetes Grid Integrated Edition access to an external LDAP group, do the following:

If you are not logged in as the UAA admin, do the steps in Log In as a UAA Admin.
Assign a TKGI cluster scope to all users in an LDAP group by running the following command:
```
uaac group map --name UAA-SCOPE GROUP-DISTINGUISHED-NAME
```
Where:
- UAA-SCOPE is one of the UAA scopes described in UAA Scopes for Tanzu Kubernetes Grid Integrated Edition Users.
- GROUP-DISTINGUISHED-NAME is the LDAP Distinguished Name (DN) for the group.
For example:
```
$ uaac group map --name pks.clusters.manage cn=operators,ou=groups,dc=example,dc=com
```
For more information about LDAP DNs, see the LDAP DNs and RDNs in the LDAP documentation.

Grant Tanzu Kubernetes Grid Integrated Edition Access to an External SAML Group

To grant Tanzu Kubernetes Grid Integrated Edition access to an external SAML group, do the following:

If you are not logged in as the UAA admin, do the steps in Log In as a UAA Admin.
Assign a TKGI cluster scope to all users in a SAML group by running the following command:
```
uaac group map --name UAA-SCOPE SAML-GROUP --origin SAML-ORIGIN
```
Where:
- UAA-SCOPE is one of the UAA scopes described in UAA Scopes for Tanzu Kubernetes Grid Integrated Edition Users.
- SAML-GROUP is name of your SAML identity provider group.
- SAML-ORIGIN is the domain name for your SAML identity provider. To find SAML-ORIGIN, click the TKGI tile, select Settings > UAA > SAML, and locate the Provider Name.
For example:
```
$ uaac group map --name pks.clusters.manage tkgi-devs --origin my-sso.example.com
```

Grant Tanzu Kubernetes Grid Integrated Edition Access to a Client

To grant Tanzu Kubernetes Grid Integrated Edition access to a client for a script or service automation, do the following:

If you are not logged in as the UAA admin, perform the steps in Log In as a UAA Admin.

Create a client with the desired scopes by running the following command:

uaac client add CLIENT-NAME -s CLIENT-SECRET \
--authorized_grant_types client_credentials \
--authorities UAA-SCOPES

Where:

CLIENT-NAME and CLIENT-SECRET are the client credentials.
UAA-SCOPES is one or more of the UAA scopes described in UAA Scopes for Tanzu Kubernetes Grid Integrated Edition Users, separated by a comma.

For example:

$ uaac client add automated-client \
-s randomly-generated-secret
--authorized_grant_types client_credentials  \
--authorities pks.clusters.admin,pks.clusters.manage