Managing Enterprise PKS Users 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).

Overview

UAA is the identity management service for Enterprise PKS. Enterprise PKS includes a UAA server, which is hosted on the PKS control plane 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 Enterprise PKS Users

By assigning UAA scopes, you grant users the ability to create, manage, and audit Kubernetes clusters in Enterprise PKS.

A UAA admin user can assign the following UAA scopes to Enterprise PKS users:

  • 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.
  • 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 Enterprise PKS, see UAA Scopes.

Prerequisites

Before managing users for Enterprise PKS, you must connect to the PKS control plane VM. To connect to the PKS control plane VM, you need one of the following:

  • SSH access to the Ops Manager VM
  • A machine that can connect to your PKS control plane VM

For instructions on how to connect to the PKS control plane, see Connect to the PKS Control Plane VM for your IaaS.

Log In as a UAA Admin

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

  1. Retrieve the UAA management admin client secret:

    1. In a web browser, navigate to the Ops Manager Installation Dashboard and click the Enterprise PKS tile.
    2. Click the Credentials tab.
    3. Click Link to Credential next to Pks Uaa Management Admin Client and copy the value of
      secret.
  2. Target your UAA server by running the following command:

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

    Where:

    • PKS-API is the domain name of your PKS API server. You entered this domain name in the Enterprise PKS tile > PKS API > API Hostname (FQDN).
    • CERTIFICATE-PATH is the path to your Ops Manager root CA certificate. Provide this certificate to validate the PKS 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.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 ignore it because it has no impact.

  3. 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 to an Individual User

To create a new UAA user with Enterprise PKS access, do the following:

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

  2. 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 cody@example.com -p password

    Note: If your operator has configured Enterprise PKS 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 on the PKS tile, select Settings > UAA > SAML, and locate the Provider Name. For information about configuring SAML, see Configure SAML as an Identity Provider in the Installing topic for your IaaS.

  3. Assign a PKS cluster scope to the new user by running the following command:

    uaac member add UAA-SCOPE USERNAME
    

    Where:

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

Grant Enterprise PKS Access to an External Group

Connecting Enterprise PKS 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 Pivotal Cloud Foundry Knowledge Base article.

To grant Enterprise PKS access to an external identity provider group, do one the following procedures:

Grant Enterprise PKS Access to an External LDAP Group

To grant Enterprise PKS access to an external LDAP group, do the following:

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

  2. Assign a PKS cluster scope to all users in an LDAP group by running the following command:

    uaac group map --name UAA-SCOPE GROUP-DISTINGUISHED-NAME
    

    Where:

    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 Enterprise PKS Access to an External SAML Group

To grant Enterprise PKS access to an external SAML group, do the following:

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

  2. Assign a PKS 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 Enterprise PKS 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 on the PKS tile, select Settings > UAA > SAML, and locate the Provider Name.

    For example:

    $ uaac group map --name pks.clusters.manage pks-devs --origin my-sso.example.com
    

Grant Enterprise PKS Access to a Client

To grant Enterprise PKS access to a client for a script or service automation, do the following:

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

  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
    

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

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