LATEST VERSION: 1.9 - CHANGELOG
Pivotal Cloud Foundry v1.7

Creating and Managing Users with the UAA CLI (UAAC)

Page last updated:

Using the UAA Command Line Interface (UAAC), an administrator can create users in the User Account and Authentication (UAA) server.

Note: The UAAC only creates users in UAA, and does not assign roles in the Cloud Controller database (CCDB). In general, administrators create users with Cloud Foundry Command Line Interface (cf CLI). The cf CLI both creates user records in the UAA and associates them with org and space roles in the CCDB. Before administrators can assign roles to the user, the user must log in via Apps Manager or the cf CLI in order for the user record to populate the CCDB. Review the Creating and Managing Users with the cf CLI topic for more information.

For additional details and information, refer to the following topics:

Create an Admin User

  1. Install the UAA CLI, uaac.

    $ gem install cf-uaac
    

  2. Use uaac target uaa.YOUR-DOMAIN to target your UAA server.

    $ uaac target uaa.example.com
    

  3. Record the uaa:admin:client_secret from your deployment manifest.

  4. Use uaac token client get admin -s ADMIN-CLIENT-SECRET to authenticate and obtain an access token for the admin client from the UAA server. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  5. Use uaac contexts to display the users and applications authorized by the UAA server, and the permissions granted to each user and application.

    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
        access_token: yJhbGciOiJIUzI1NiJ9.e
        token_type: bearer
        expires_in: 43200
        scope: uaa.admin clients.secret scim.read
        jti: 91b3-abcd1233
    
  6. In the output from uaac contexts, search in the scope section of the client_id: admin user for scim.write. The value scim.write represents sufficient permissions to create accounts.

  7. If the admin user lacks permissions to create accounts:

    • Use uaac client update admin --authorities "EXISTING-PERMISSIONS scim.write" to add the necessary permissions to the admin user account on the UAA server. Replace EXISTING-PERMISSIONS with the current contents of the scope section from uaac contexts.
    • Use uaac token delete to delete the local token.
    • Use uaac token client get admin to obtain an updated access token from the UAA server.
    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
      . . .
      scope: uaa.admin clients.secret scim.read
      . . .
    
    $ uaac client update admin --authorities "`uaac client get admin | \
      awk '/:/{e=0}/authorities:/{e=1;if(e==1){$1="";print}}'` scim.write"
    
    $ uaac token delete
    $ uaac token client get admin
    
  8. Use uaac user add NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD --emails NEW-ADMIN-EMAIL to create an admin user.

    $ uaac user add Adam -p newAdminSecretPassword --emails newadmin@example.com
    

  9. Use uaac member add GROUP NEW-ADMIN-USERNAME to add the new admin to the groups cloud_controller.admin, uaa.admin, scim.read, scim.write.

    $ uaac member add cloud_controller.admin Adam
    $ uaac member add uaa.admin Adam
    $ uaac member add scim.read Adam
    $ uaac member add scim.write Adam
    

Grant Admin Permissions to an LDAP Group

To grant all users under an LDAP Group admin permissions:

  1. Obtain the credentials of an admin client created using UAAC as above, or refer to the uaa: scim section of your deployment manifest for the user name and password of an admin user.

  2. Use uaac token client get admin -s ADMIN-CLIENT-SECRET to authenticate and obtain an access token for the admin client from the UAA server. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Run the following commands to grant all user under the mapped LDAP Group admin permissions:

    • uaac group map --name scim.read "GROUP-DISTINGUISHED-NAME"
    • uaac group map --name cloud_controller.admin "GROUP-DISTINGUISHED-NAME"

Create Users

  1. Obtain the credentials of an admin client created using UAAC as above, or refer to the uaa: scim section of your deployment manifest for the user name and password of an admin user.

  2. Use cf login -u NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD to log in.

    $ cf login -u Adam -p newAdminSecretPassword
    

  3. Use cf create-user NEW-USER-NAME NEW-USER-PASSWORD to create a new user.

    $ cf create-user Charlie aNewPassword
    

Change Passwords

  1. Obtain the credentials of an admin client created using UAAC as above, or refer to the uaa: scim section of your deployment manifest for the user name and password of an admin user.

  2. Use uaac token client get admin -s ADMIN-CLIENT-SECRET to authenticate and obtain an access token for the admin client from the UAA server. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Use uaac contexts to display the users and applications authorized by the UAA server, and the permissions granted to each user and application.

    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
        access_token: yJhbGciOiJIUzI1NiJ9.e
        token_type: bearer
        expires_in: 43200
        scope: uaa.admin clients.secret password.read
        jti: 91b3-abcd1233
    
  4. In the output from uaac contexts, search in the scope section of the client_id: admin user for password.write. The value password.write represents sufficient permissions to change passwords.

  5. If the admin user lacks permissions to change passwords:

    • Use uaac client update admin --authorities "EXISTING-PERMISSIONS password.write" to add the necessary permissions to the admin user account on the UAA server. Replace EXISTING-PERMISSIONS with the current contents of the scope section from uaac contexts.
    • Use uaac token delete to delete the local token.
    • Use uaac token client get admin to obtain an updated access token from the UAA server.
    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
      . . .
      scope: uaa.admin clients.secret password.read
      . . .
    
    $ uaac client update admin --authorities "`uaac client get admin | \
      awk '/:/{e=0}/authorities:/{e=1;if(e==1){$1="";print}}'` password.write"
    
    $ uaac token delete
    $ uaac token client get admin
    
  6. Use uaac password set USER-NAME -p TEMP-PASSWORD to change an existing user password to a temporary password.

    $ uaac password set Charlie -p ThisIsATempPassword
    

  7. Provide the TEMP-PASSWORD to the user. Have the user use cf target api.YOUR-DOMAIN, cf login -u USER-NAME -p TEMP-PASSWORD, and cf passwd to change the temporary password. See the Configuring UAA Password Policy topic to configure the password policy.

    $ cf target api.example.com
    $ cf login -u Charlie -p ThisIsATempPassword
    $ cf passwd

    Current Password>ThisIsATempPassword

    New Password>*******

    Verify Password>******* Changing password...

Retrieve User Email Addresses

Some Cloud Foundry components, like Cloud Controller, only use GUIDs for user identification. You can use the UAA to retrieve the emails of your Cloud Foundry instance users either as a list or for a specific user with that user’s GUID.

To retrieve user email addresses:

  1. Use uaac target uaa.YOUR-DOMAIN to target your UAA server.

    $ uaac target uaa.example.com
    

  2. Record the uaa:admin:client_secret from your deployment manifest.

  3. Use uaac token client get admin -s ADMIN-CLIENT-SECRET to authenticate and obtain an access token for the admin client from the UAA server. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  4. Use uaac contexts to display the users and applications authorized by the UAA server, and the permissions granted to each user and application.

    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
        access_token: yJhbGciOiJIUzI1NiJ9.e
        token_type: bearer
        expires_in: 43200
        scope: uaa.admin clients.secret
        jti: 91b3-abcd1233
    
  5. In the output from uaac contexts, search in the scope section of the client_id: admin user for scim.read. The value scim.read represents sufficient permissions to query the UAA server for user information.

  6. If the admin user lacks permissions to query the UAA server for user information:

    • Use uaac client update admin --authorities "EXISTING-PERMISSIONS scim.write" to add the necessary permissions to the admin user account on the UAA server. Replace EXISTING-PERMISSIONS with the current contents of the scope section from uaac contexts.
    • Use uaac token delete to delete the local token.
    • Use uaac token client get admin to obtain an updated access token from the UAA server.
    $ uaac contexts
    
    [1]*[admin]
      client_id: admin
      . . .
      scope: uaa.admin clients.secret
      . . .
    
    $ uaac client update admin --authorities "uaa.admin clients.secret scim.read"
    
    $ uaac token delete
    $ uaac token client get admin
    
  7. Use uaac users to list your Cloud Foundry instance users. By default, the uaac users command returns information about each user account including GUID, name, permission groups, activity status, and metadata. Use the --attributes emails or -a emails flag to limit the output of uaac users to email addresses.

    $ uaac users --attributes emails
    
    resources:
      emails:
    value: user1@example.com
      emails:
    value: user2@example.com
      emails:
    value: user3@example.com
    
  8. Use uaac users "id eq GUID" --attributes emails with the GUID of a specific user to retrieve that user’s email address.

    $ uaac users "id eq 'aabbcc11-22a5-87-8056-beaf84'" --attributes emails
    
    resources:
      emails:
    value: user1@example.com
    
Was this helpful?
What can we do to improve?
View the source for this page in GitHub