Creating and Managing Users with the UAA CLI (UAAC)

Page last updated: August 15, 2015

Using the UAA Command Line Interface (UAAC), an administrator can create users and manage organization and space roles.

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

• UAA Overview
• UAA Sysadmin Guide
• Other UAA Documentation

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 [email protected]
   

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.

   $ 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: [email protected]
     emails:
   value: [email protected]
     emails:
   value: [email protected]
   

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: [email protected]