LATEST VERSION: v1.3 - RELEASE NOTES
Pivotal Container Service v1.1

Managing Users in PKS with UAA

Page last updated:

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

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 these credentials when you installed Ops Manager.

Note: If you lose your credentials, 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.

  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.

  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 an Admin section to manage 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 an Admin section to manage users with UAAC.

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.

  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 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.
    • ROOT-CA-FILENAME is the certificate file you downloaded in Configuring PKS API Access.

    For example:

    $ uaac target api.pks.example.com:8443 --ca-cert my-cert.cert
    

    Note: If you receive an Unknown key: Max-Age = 86400 warning message, you can safely ignore it because it has no impact.

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

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.

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.

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

    $ uaac member add pks.clusters.admin alana

Grant Control Plane 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.

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.

The PKS control plane enables users to deploy and manage Kubernetes clusters.

To grant control plane 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 Cluster Access to a Client

To grant cluster 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 with one or more of the UAA scopes defined in Grant Cluster 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
    

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

Create a pull request or raise an issue on the source for this page in GitHub