manage-users.html.md.erb

---
title: Managing Users in PKS with UAA
owner: PKS
---

<strong><%= modified_date %></strong>

This topic describes how to manage users in Pivotal Container Service (PKS) with User Account and Authentication (UAA).
Create and manage users in UAA with the UAA Command Line Interface (UAAC).

## <a id='uaac'></a>How to Use UAAC

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

To run UAAC commands from the Ops Manager VM, see the following SSH procedures for [vSphere](#ssh-vsphere) or [Google Cloud Platform (GCP)](#ssh-gcp).

To install UAAC locally, see [Component: User Account and Authentication (UAA) Server](https://docs.pivotal.io/pivotalcf/concepts/architecture/uaa.html).

### <a id='ssh-vsphere'></a>SSH into the Ops Manager VM on vSphere

To SSH into the Ops Manager VM on vSphere, you need the credentials used to import the PCF .ova or .ovf file into your virtualization system.
You set these credentials when you installed Ops Manager.

<p class="note"><strong>Note</strong>: If you lose your credentials, you must shut down the Ops Manager VM in the vSphere UI and reset the password. See <a href="https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.security.doc/GUID-4BDBF79A-6C16-43B0-B0B1-637BF5516112.html">vCenter Password Requirements and Lockout Behavior</a> in the vSphere documentation for more information.</p>

1. From a command line, run the following command to SSH into the Ops Manager VM:

    ```
    ssh ubuntu@OPS-MANAGER-FQDN
    ```
    Where `OPS-MANAGER-FQDN` is the fully qualified domain name (FQDN) of Ops Manager.

1. When prompted, enter the password that you set during the .ova deployment
into vCenter. For example:
  <pre class="terminal">
  $ ssh ubuntu&#64;my-opsmanager-fqdn.example.com
  Password: ***********
  </pre>

1. Proceed to the [Log in as an Admin](#uaa-admin-login) section to manage users with UAAC.

### <a id='ssh-gcp'></a>SSH into the Ops Manager VM on GCP

To SSH into the Ops Manager VM in GCP, do the following:

1. Confirm that you have installed the gcloud CLI. See [Downloading gcloud](https://cloud.google.com/sdk/gcloud/#downloading_gcloud) in the Google Cloud Platform documentation for more information.

1. From the GCP console, click **Compute Engine**.

1. Locate the Ops Manager VM in the **VM Instances** list.

1. Click the **SSH** menu button.

1. Copy the SSH command that appears in the popup window.

1. Paste the command into your terminal window to SSH to the Ops Manager VM. For example:
    <pre class="terminal">
    $ gcloud compute ssh om-pcf-1a --zone us-central1-b
    </pre>

1. Run `sudo su - ubuntu` to switch to the `ubuntu` user.

1. Proceed to the [Log in as an Admin](#uaa-admin-login) section to manage users with UAAC.

### <a id='ssh-aws'></a>SSH into the Ops Manager VM on AWS

To SSH into the Ops Manager VM on AWS, you need the key pair you used when you
created the Ops Manager VM. To see the name of the key pair, click on the Ops
Manager VM in the AWS console and locate the `key pair name` in the properties.

To SSH into the Ops Manager VM on AWS, do the following:

1. From the AWS console, locate the Ops Manager fully qualified domain name on the AWS **EC2 instances** page.

1. Run `chmod 600 ops_mgr.pem` to change the permissions on the `.pem` file to be more restrictive. For example:

	<pre class="terminal">
	$ chmod 600 ops_mgr.pem
	</pre>

1. Run the following command to SSH into the Ops Manager VM:

    ```
    ssh -i ops_mgr.pem ubuntu@OPS-MANAGER-FQDN
    ```
    Where `OPS-MANAGER-FQDN` is the fully qualified domain name of Ops Manager. For example:

	<pre class="terminal">
	$ ssh -i ops_mgr.pem ubuntu@my-opsmanager-fqdn.example.com
	</pre>

1. Proceed to the [Log in as an Admin](#uaa-admin-login) section to manage users with UAAC.

##<a id='uaa-admin-login'></a> Log in as a UAA Admin

To retrieve the PKS UAA management admin client secret, do the following:

1. In a web browser, navigate to the fully qualified domain name of Ops Manager and click the **Pivotal Container Service** tile.

1. Click **Credentials**.

1. To view the secret, click **Link to Credential** next to **Pks Uaa Management Admin Client**. The client username is `admin`.

1. On the command line, run the following command to target your UAA server:

    ```
    uaac target https://PKS-API:8443 --ca-cert ROOT-CA-FILENAME
    ```

    Where:
    * `PKS-API` is the URL to your PKS API server. You configured this URL in the PKS API section of _Installing PKS_ for your IaaS. For example, see [Installing PKS on vSphere](installing-pks-vsphere.html#pks-api).
    * `ROOT-CA-FILENAME` is the certificate file you downloaded in [Configuring PKS API Access](configure-api.html#access).

    For example:
    <pre class="terminal">
    $ uaac target api.pks.example.com:8443 --ca-cert my-cert.cert
    </pre>
    <p class="note"><strong>Note</strong>: If you receive an <code>Unknown key: Max-Age = 86400</code> warning message, you can safely ignore it because it has no impact.</p>

1. Run the following command to authenticate with UAA using the secret you retrieved in a previous
step:

    ```
    uaac token client get admin -s ADMIN-CLIENT-SECRET
    ```
    Where `ADMIN-CLIENT-SECRET` is your PKS UAA management admin client secret.

##<a id='pks-access'></a> Grant PKS Access

PKS access gives users the ability to deploy and manage Kubernetes clusters.
As an Admin user, you can assign the following UAA scopes to users, external LDAP groups, and clients:

  * `pks.clusters.manage`: Accounts with this scope can create and access their own clusters.
  * `pks.clusters.admin`: Accounts with this scope can create and access all clusters.

###<a id='uaa-user'></a> Grant PKS Access to a User

You can create a new UAA user with PKS access by performing the following steps:

1. Log in as the UAA admin using the procedure in [Log in as a UAA Admin](#uaa-admin-login).

1. To create a new user, run the following command:

    ```
    uaac user add USERNAME --emails USER-EMAIL -p USER-PASSWORD
    ```

    For example:
    <pre class="terminal">$ uaac user add alana --emails alana&#64;example.com -p password</pre>

1. Run the following command to assign a scope to the user to allow them to access Kubernetes
clusters:

    ```
    uaac member add UAA-SCOPE USERNAME
    ```
    Where `UAA-SCOPE` is one of the UAA scopes defined in [Grant PKS Access](#pks-access). For 
    example:
    <pre class="terminal">$ uaac member add pks.clusters.admin alana</pre>

###<a id='external-group'></a> Grant PKS Access to an External LDAP Group

Connecting PKS to a LDAP external user store allows the User Account and Authentication (UAA) server to delegate authentication to existing enterprise user stores.

<p class='note'><strong>Note</strong>: When integrating with an external identity provider such as
LDAP, authentication within the UAA becomes chained. UAA first attempts to authenticate with a
user's credentials against the UAA user store before the external provider, LDAP. For more
information, see <a href="https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-LDAP.md#chained-authentication">Chained Authentication</a> in the <em>User Account and Authentication LDAP Integration</em> GitHub documentation.
</p>

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 Pivotal Cloud Foundry](https://community.pivotal.io/s/article/Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry) Knowledge Base article.

To grant PKS access to an external LDAP group, perform the following steps:

1. Log in as the UAA admin using the procedure in [Log in as a UAA Admin](#uaa-admin-login).

1. To assign the `pks.clusters.manage` scope to all users in an LDAP group, run the following command:

    ```
    uaac group map --name pks.clusters.manage GROUP-DISTINGUISHED-NAME
    ```
    Where `GROUP-DISTINGUISHED-NAME` is the LDAP Distinguished Name (DN) for the group. For example:
    <pre class="terminal">
    $ uaac group map --name pks.clusters.manage cn=operators,ou=groups,dc=example,dc=com
    </pre>
    For more information about LDAP DNs, see the [LDAP DNs and RDNs](https://ldap.com/ldap-dns-and-rdns/) in the LDAP documentation.

1. (Optional) To assign the `pks.clusters.admin` scope to all users in an LDAP group, run the following command:

    ```
    uaac group map --name pks.clusters.admin GROUP-DISTINGUISHED-NAME
    ```
    Where `GROUP-DISTINGUISHED-NAME` is the LDAP DN for the group. For example:
    <pre class="terminal">
    $ uaac group map --name pks.clusters.admin cn=operators,ou=groups,dc=example,dc=com
    </pre>

###<a id='uaa-client'></a> Grant PKS Access to a Client

To grant PKS access to an automated client for a script or service, perform the following steps:

1. Log in as the UAA admin using the procedure [Log in as a UAA Admin](#uaa-admin-login).

1. Run the following command to create a client with the desired scopes:

    ```
    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 fines one or more of the UAA scopes defined in [Grant PKS Access
](#pks-access), separated by a comma. For example:
    <pre class="terminal">
    $ uaac client add automated-client \
    -s randomly-generated-secret
    --authorized_grant_types client_credentials  \
    --authorities pks.clusters.admin,pks.clusters.manage
    </pre>

##<a id='cluster-access'></a> Grant Cluster Access

You can grant a user or a group access to an entire cluster with a `ClusterRole` or to a namespace
within a given cluster with a `Role`.

The admin of the cluster must then create a `ClusterRoleBinding` or a `RoleBinding` for that Kubernetes end user.

For more information, see [RoleBinding and ClusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) in the Kubernetes documentation.

###<a id='cluster-access-user'></a> Grant Cluster Access to a User

After being granted cluster access, the Kubernetes end user can use the Kubernetes Command Line
Interface (kubectl) to connect to the cluster and perform actions as configured by their cluster
admin. However, even with this access, Kubernetes end users cannot create, resize, or delete
clusters. 

The following diagram outlines the workflow you use to grant cluster access to a
user who belongs to an LDAP group:

<a href="images/enterprise-id.png"><img src="images/enterprise-id.png" alt="This diagram shows the workflow that operators and cluster admins use to grant cluster access to users."></a>

<p class='note'><strong>Note</strong>: In order for cluster admins to grant cluster access to Kubernetes end users, cluster admins must ensure that they have selected <strong>Enable UAA as OIDC provider</strong> in the UAA section of the PKS tile. Once you enable OIDC, you must run <code>get-credentials</code> again to update your existing kubeconfig.</p>

To grant cluster access to other users, the cluster admin must perform the following actions:

1. Run the following command to log in to PKS client using LDAP credentials:

    ```
    pks login -u LDAP-NAME -p LDAP-PASSWORD -a PKS-API --ca-cert ROOT-CA-FILENAME
    ```
    Where:
    * `LDAP-USER-NAME` is the cluster admin's LDAP username.
    * `LDAP-PASSWORD` is the cluster admin's LDAP password.
    * `PKS-API` is the fully qualified domain name you use to access the PKS API.

1. Run the following command to confirm that you can successfully connect to a cluster and use
kubectl as a cluster admin:

    ```
    pks get-credentials CLUSTER-NAME
    ```
    This step creates a `ClusterRoleBinding` for the LDAP cluster admin.

1. When prompted, re-enter your LDAP password.

1. Create a spec YML file with either the `Role` or `ClusterRole` for your Kubernetes end user.

    ```
    kind: ROLE-TYPE
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      namespace: NAMESPACE
      name: ROLE-OR-CLUSTER-ROLE-NAME
    rules:
    - apiGroups:
      resources: RESOURCE
      verbs: API-REQUEST-VERB
    ```
    Where:
    * `ROLE-TYPE` is the type of role you are creating. This must be either `Role` or `ClusterRole`.
    * `NAMESPACE` is the namespace within the cluster. This is omitted when creating a `ClusterRole`.
    * `ROLE-OR-CLUSTER-ROLE-NAME` is the name of the `Role` or `ClusterRole` you are creating. This name is created by the cluster admin.
    * `RESOURCE` is the resource you are granting access to. It must be specified in a comma-separated array. An example resource could be `["pod-reader"]`. 
    * `API-REQUEST-VERB` is used to specify resource requests. For more information, see
	 [Determine the Request Verb](https://kubernetes.io/docs/reference/access-authn-authz/authorization/#determine-the-request-verb) in the Kubernetes documentation.

1. Run the following command to create the `Role` or `ClusterRole` resource based on your spec file:

    ```
    kubectl create -f ROLE-SPEC.yml
    ```

1. Create a spec YML file containing either a `ClusterRoleBinding` or `RoleBinding` for the Kubernetes end user.

    ```
    kind: ROLE-BINDING-TYPE
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      namespace: NAMESPACE
    subjects:
    - kind: User
      name: USERNAME
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: ROLE-TYPE
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      apiGroup: rbac.authorization.k8s.io
    ```
    Where:
    * `ROLE-BINDING-TYPE` is the type of role binding you are creating. This must be either `RoleBinding` or `ClusterRoleBinding`.
    * `ROLE-OR-CLUSTER-ROLE-BINDING-NAME` is the name of the role binding. This name is created by the cluster admin.
    * `NAMESPACE` is the namespace within the cluster. This is omitted when creating a `ClusterRole`.
    * `USERNAME` is the Kubernetes end user's username. If your organization uses LDAP, for example, this is your LDAP username.
    * `ROLE-TYPE` is the type of role you created in the previous step. This must be either `Role` or `ClusterRole`.
    * `ROLE-OR-CLUSTER-ROLE-NAME` is the name of the `Role` or `ClusterRole` you are creating.

1. Run the following command to create the above defined `ClusterRoleBinding` resource in the cluster:

    ```
    kubectl apply -f ROLE-BINDING-SPEC.yml
    ```

1. The cluster admin partially completes the `kubeconfig` by detailing the following: 
  + `clusters.cluster.certificate-authority-data`
  + `clusters.cluster.server`
  + `cluster.name`
  + `contexts.context.cluster`
  + `contexts.context.name`
  + `current-context`
  + `users.user.auth-provider.config.idp-issuer-url`

1. The cluster admin sends the partially completed `kubeconfig` to their Kubernetes end user. Review the example kubeconfig file below. For more information about organizing information using kubeconfig, see [Organizing Cluster Access Using kubeconfig Files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) in the Kubernetes documentation.

    ```
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: PROVIDED-BY-ADMIN
        server: PROVIDED-BY-ADMIN
      name: PROVIDED-BY-ADMIN
    contexts:
    - context:
        cluster: PROVIDED-BY-ADMIN
        user: PROVIDED-BY-USER
      name:  PROVIDED-BY-ADMIN
    current-context: PROVIDED-BY-ADMIN
    kind: Config
    preferences: {}
    users:
    - name: PROVIDED-BY-USER
      user: 
        auth-provider:
          config:
            client-id: pks_cluster_client
            cluster_client_secret: ""
            id-token: PROVIDED-BY-USER
            idp-issuer-url: <span>https:</span>//PROVIDED-BY-ADMIN:8443/oauth/token
            refresh-token:  PROVIDED-BY-USER
          name: oidc
    ```

###<a id='obtain-cluster-access'></a> Obtain Cluster Access as a User

To obtain cluster access, the end user must perform the following actions:

1. Run the following command to obtain the `users.user.auth-provider.config.id-token` and `users.user.auth-provider.config.refresh-token`:

    ```
    curl 'https://PKS-API:8443/oauth/token' -k -XPOST -H 
    'Accept: application/json' -d "client_id=pks_cluster_client&client_secret=""&grant_type=password
     &username=UAA-USERNAME&response_type=id_token" --data-urlencode password=UAA-PASSWORD
    ```
    Where:
    * `PKS-API` is the FQDN you use to access the PKS API.
    * `UAA-USERNAME` is the Kubernetes end user's UAA username.
    * `UAA-PASSWORD` is the Kubernetes end user's UAA password. 

1. Edit the `kubeconfig` by providing the following:
  * `contexts.context.user`
  * `users.name`
  * `users.user.auth-provider.config.id-token`
  * `users.user.auth-provider.config.refresh-token`

1. Save the `kubeconfig` to the `$HOME/.kube/config` directory. After doing so, the Kubernetes end user can connect to the cluster using `kubectl`. 

<div class='note'><strong>Note</strong>: To automate this process, follow the instructions in one
of the following Knowledge Base Articles:<br>
<ul>
  <li>
    <a href="https://community.pivotal.io/s/article/script-to-automate-generation-of-the-kubeconfig-for-the-kubernetes-user">Script to automate generation of the kubeconfig for the kubernetes user</a>
  </li>
  <li>
    <a href="https://community.pivotal.io/s/article/powershell-script-to-automate-generation-of-kubeconfig-for-the-kubernetes-use">Powershell script to automate generation of kubeconfig for the kubernetes user</a>
  </li>
</ul>
</div>

###<a id='cluster-access-group'></a> Grant Cluster Access to a Group

Cluster admins can also grant cluster-wide access to an LDAP Group by creating a `ClusterRoleBinding` for that LDAP group. This feature is only available if LDAP is used as your identity provider for UAA.

<p class='note'><strong>Note</strong>: You must confirm that the group you are referencing in your <code>ClusterRoleBinding</code> has been whitelisted in the PKS tile. To do so, review the <strong>External Groups Whitelist</strong> field in the UAA section of the PKS tile.</p>

The process for granting cluster access to an LDAP is similar to the process described in [Grant Cluster Access to a User](#cluster-access-user).

The only difference is that when the cluster admin is creating the spec file containing the `RoleBinding` or `ClusterRoleBinding` for a group, the spec file must reflect the following:

```
kind: ROLE-BINDING-TYPE
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
  namespace: NAMESPACE
subjects:
- kind: Group
  name: NAME-OF-GROUP
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ROLE-TYPE
  name: ROLE-OR-CLUSTER-ROLE-NAME
  apiGroup: rbac.authorization.k8s.io
```

Where:

* `ROLE-BINDING-TYPE` is the type of role binding you are creating. This must be either `RoleBinding` or `ClusterRoleBinding`.
* `ROLE-OR-CLUSTER-ROLE-BINDING-NAME` is the name of your `RoleBinding` or `ClusterRoleBinding`. This is created by the cluster admin.
* `NAME-OF-GROUP` is the LDAP group name. This name is case sensitive.
* `ROLE-TYPE` is the type of role you are creating. This must be either `Role` or `ClusterRole`.
* `ROLE-OR-CLUSTER-ROLE-NAME` is the name of your `Role` or `ClusterRole`. This is created by the cluster admin.