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

Manage Users in 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 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 ssh ubuntu@OPS-MANAGER-FQDN to SSH into the Ops Manager VM. Replace OPS-MANAGER-FQDN with the fully qualified domain name 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 Retrieve UAA Admin Credentials section to manage users with UAAC.

SSH into the Ops Manager VM on GCP

To SSH into the Ops Manager VM in GCP, follow these instructions:

  1. Confirm that you have installed the gcloud CLI. See 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 Retrieve UAA Admin Credentials section to manage users with UAAC.

Log in as an 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 (FQDN) 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
    Replace PKS-API with the URL to your PKS API server. You configured this URL in the PKS API section of Installing and Configuring PKS. Replace ROOT-CA-FILENAME with the certificate file you downloaded in Configure Access to the PKS API. 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. Authenticate with UAA using the secret you retrieved in a previous step. Run the following command, replacing ADMIN-CLIENT-SECRET with your PKS UAA management admin client secret:

    uaac token client get admin -s ADMIN-CLIENT-SECRET

Grant Cluster Access

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 Cluster Access to a User

To create a new UAA user with cluster access, perform the following steps:

  1. Log in as the UAA admin using the procedure above.

  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. Assign a scope to the user to allow them to access Kubernetes clusters. Run uaac member add UAA-SCOPE USERNAME, replacing UAA-SCOPE with one of the UAA scopes defined above. 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 above.

  2. To grant control plane access to all users in an LDAP group, run the following command:

    uaac group map --name pks.clusters.manage GROUP-DISTINGUISHED-NAME
    Replace GROUP-DISTINGUISHED-NAME with the LDAP Distinguished Name (DN) for the group. For example:
    $ uaac group map --name pks.clusters.manage Operators
    

  3. (Optional) To grant control plane access to all users in an LDAP group, run the following command:

    uaac group map --name pks.clusters.admin GROUP-DISTINGUISHED-NAME
    Replace GROUP-DISTINGUISHED-NAME with the LDAP DN for the group. For example:
    $ uaac group map --name pks.clusters.admin cn=Administrators,ou=Groups,dc=ldap,dc=example,dc=com
    

Where:

  • cn is the common name.
  • ou is the organizational unit.
  • dc is the domain component.

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

  2. 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
    Replace CLIENT-NAME and CLIENT-SECRET with the client credentials. Replace UAA-SCOPES with one or more of the UAA scopes defined above, 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