Managing Users in Enterprise PKS with UAA

Page last updated:

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

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 or Google Cloud Platform (GCP).

To install UAAC locally, see Component: User Account and Authentication (UAA) Server.

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 your credentials in the Prepare vSphere section of Deploying Ops Manager on vSphere for your Ops Manager version.

Note: If you lose your password, you must shut down the Ops Manager VM in the vSphere UI and reset the password. See vCenter Password Requirements and Lockout Behavior in the vSphere documentation for more information.

Warning: If you deployed Ops Manager v2.6.x on vSphere, you can only SSH into the Ops Manager VM with a private SSH key. If you do not have a private SSH key, you must add a public key to your .ova or .ovf file and then use the private key to SSH onto the Ops Manager VM. If you do not add a key, Ops Manager shuts down automatically because it cannot find a key and may enter a reboot loop.

To SSH into the Ops Manager VM on vSphere, do one of the following:

  • If you set a password when you installed Ops Manager:

    1. SSH into the Ops Manager VM by running the following command:

      ssh ubuntu@OPS-MANAGER-FQDN
      

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

    2. When prompted, enter the password that you set during the .ova deployment into vCenter. For example:

      $ ssh ubuntu@my-opsmanager-fqdn.example.com
      Password: ***********
      

    3. Proceed to the Log in as a UAA Admin section to manage users with UAAC.

  • If you set a SSH key when you installed Ops Manager:

    1. Change the permissions for your private SSH key by running the following command:

        chmod 600 PRIVATE-KEY
      

      Where PRIVATE-KEY is the name of your private SSH key.

    2. SSH into the Ops Manager VM by running the following command:

        ssh -i PRIVATE-KEY ubuntu@OPS-MANAGER-FQDN
      

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

      For example:

      $ ssh -i id_rsa ubuntu@my-opsmanager-fqdn.example.com

    3. Proceed to the Log In as a UAA Admin section to create admin users with UAAC.

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 in the Google Cloud Platform documentation for more information.

  2. From the GCP console, click Compute Engine.

  3. Locate the Ops Manager VM in the VM Instances list.

  4. Click the SSH menu button.

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

  6. Paste the command into your terminal window to SSH to the Ops Manager VM. For example:

    $ gcloud compute ssh om-pcf-1a --zone us-central1-b
    

  7. Run sudo su - ubuntu to switch to the ubuntu user.

  8. Proceed to the Log in as a UAA Admin section to manage users with UAAC.

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 FQDN on the AWS EC2 instances page.

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

    $ chmod 600 ops_mgr.pem
    
  3. 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 FQDN of Ops Manager. For example:

    $ ssh -i ops_mgr.pem ubuntu@my-opsmanager-fqdn.example.com
    
  4. Proceed to the Log in as a UAA Admin section to manage users with UAAC.

SSH into the Ops Manager VM on Azure

To SSH into the Ops Manager VM with SSH in Azure, you need the SSH key pair you used when you created the Ops Manager VM. If you need to reset the SSH key, locate the Ops Manager VM in the Azure portal and click Reset Password.

To log in to the Ops Manager VM with SSH in Azure, do the following:

  1. From the Azure portal, locate the Ops Manager FQDN by selecting the VM.

  2. Change the permissions for your SSH private key by running the following command:

    chmod 600 PRIVATE-KEY
    

    Where PRIVATE-KEY is the name of your SSH private key.

  3. SSH into the Ops Manager VM by running the following command:

    ssh -i PRIVATE-KEY ubuntu@OPS-MANAGER-FQDN
    

    Where:

    • OPS-MANAGER-FQDN is FQDN of Ops Manager.
    • PRIVATE-KEY is the name of your SSH private key.

    For example:

    $ ssh -i id_rsa ubuntu@my-opsmanager-fqdn.example.com

  4. Proceed to the Log in as a UAA Admin section to manage users with UAAC.

Log in as a UAA Admin

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

  1. In a web browser, navigate to the FQDN of Ops Manager and click the Enterprise PKS tile.

  2. Click Credentials.

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

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

    uaac target https://PKS-API:8443 --ca-cert CERTIFICATE-PATH
    

    Where:

    • PKS-API is the URL to your PKS API server. You configured this URL in the PKS API section of Installing Enterprise PKS for your IaaS. For example, see Installing Enterprise PKS on vSphere. If you are logged in to the Ops Manager VM, the root certificate is located at /var/tempest/workspaces/default/root_ca_certificate.
    • CERTIFICATE-PATH is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL. For example:
      $ uaac target api.pks.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 safely ignore it because it has no impact.

  5. 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 username is admin.

Grant Enterprise PKS Access

Enterprise 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.

Grant Enterprise PKS Access to a User

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

  1. Log in as the UAA admin using the procedure in Log in as a UAA Admin.

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

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

    For example:

    $ uaac user add alana --emails alana@example.com -p password

  3. 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 Enterprise PKS Access. For example:

    $ uaac member add pks.clusters.admin alana

Grant Enterprise PKS Access to an External LDAP Group

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

Note: 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 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 Pivotal Cloud Foundry Knowledge Base article.

To grant Enterprise 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.

  2. 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:

    $ 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.

  3. (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:

    $ uaac group map --name pks.clusters.admin cn=operators,ou=groups,dc=example,dc=com
    

Grant Enterprise PKS Access to a Client

To grant Enterprise 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.

  2. 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 one or more of the UAA scopes defined in Grant Enterprise PKS Access, 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
      

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 and Default Roles and Role Bindings in the Kubernetes documentation .

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.

Note: Before you can grant cluster access to Kubernetes end users, you must enable OpenID Connect (OIDC) by selecting Enable UAA as OIDC provider in the UAA section of the Enterprise PKS tile. Once you enable OIDC, you must run pks get-credentials again to update your existing kubeconfig.

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

This diagram shows the workflow that operators and cluster admins use to grant cluster access to users.

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:

    pks login -u USERNAME -p PASSWORD -a PKS-API --ca-cert CERTIFICATE-PATH
    

    Where:

    • USERNAME is the cluster admin’s username. If your organization uses LDAP, for example, this is your LDAP username.
    • PASSWORD is the cluster admin’s password.
    • PKS-API is the FQDN you use to access the PKS API.
    • CERTIFICATE-PATH is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL.
  2. 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 cluster admin.

  3. When prompted, re-enter your password.

  4. Create a spec YAML 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 in the Kubernetes documentation.
  5. Run the following command to create the Role or ClusterRole resource based on your spec file:

    kubectl create -f ROLE-SPEC.yml
    
  6. Create a spec YAML 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.
  7. Run the following command to create the above defined RoleBinding or ClusterRoleBinding resource in the cluster:

    kubectl apply -f ROLE-BINDING-SPEC.yml
    
  8. Share the following information with your Kubernetes end users:

    • FQDN of the PKS API
    • Cluster name

Obtain Cluster Access as a User

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

  1. Run the following command:

    pks get-kubeconfig CLUSTER-NAME -u USERNAME -a PKS-API --ca-cert CERTIFICATE-PATH
    

    Where:

    • CLUSTER-NAME is the cluster name provided by the cluster admin.
    • USERNAME is the Kubernetes end user’s username. If your organization uses LDAP, for example, this is your LDAP username.
    • PKS-API is the FQDN you use to access the PKS API.
    • CERTIFICATE-PATH is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL.

    For example:

    $ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com \
    --ca-cert /var/tempest/workspaces/default/root_ca_certificate
    

    Alternatively, if the CA is trusted, you can run the following command to fetch the kubeconfig:

    pks get-kubeconfig CLUSTER-NAME -u USERNAME -a PKS-API -k
    

    Where -k is the shortcut flag to skip SSL validation (--skip-ssl-validation).

    For example:

    $ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com -k
    

  2. When prompted, enter your password.

  3. The PKS CLI generates a kubeconfig for the cluster you have access to. Review the example kubeconfig file below.

    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
    
  4. Access the cluster using kubectl. For more information about kubectl commands, see Overview of kubectl the Kubernetes documentation.

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.

Note: You must confirm that the group you are referencing in your ClusterRoleBinding has been whitelisted in the Enterprise PKS tile. To do so, review the External Groups Whitelist field in the UAA section of the Enterprise PKS tile.

The process for granting cluster access to an LDAP group is similar to the process described in Grant Cluster Access to a 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.

Please send any feedback you have to pks-feedback@pivotal.io.