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 using the 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 through Apps Manager or the cf CLI 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:

Note: UAAC requires Ruby v2.3.1 or later. If you have an earlier version of Ruby installed, install v2.3.1 or later before using the UAAC.

For more information about which roles can perform various operations in Cloud Foundry, see the Roles and Permissions topic.

Create an Admin User

  1. Install the UAA CLI, uaac.

    $ gem install cf-uaac
    

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

    $ uaac target uaa.example.com
    

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

  4. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  5. Use the uaac contexts command 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: aBcdEfg0hIJKlm123.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, add the permissions by following these steps:

    • Run 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.
    • Run uaac token delete to delete the local token.
    • Run 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. Run the following command to create an admin user: uaac user add NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD --emails NEW-ADMIN-EMAIL
    Replace NEW-ADMIN-USERNAME, NEW-ADMIN-PASSWORD, and NEW-ADMIN-EMAIL with appropriate information.

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

  9. Run uaac member add GROUP NEW-ADMIN-USERNAME to add the new admin to the groups cloud_controller.admin, uaa.admin, scim.read, and 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
    

Create an Admin Read-Only User

The admin read-only account can view but not modify all Cloud Controller API resources.

If you want to create an admin read-only user account, then perform the following steps:

  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. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Run the following command to create an admin read-only user: uaac user add NEW-USERNAME -p NEW-PASSWORD --emails NEW-EMAIL
    Replace NEW-USERNAME, NEW-PASSWORD, and NEW-EMAIL with appropriate information.

    $ uaac user add Bob -p SecretPassword --emails bob@example.com
    

  4. Run uaac member add GROUP NEW-USERNAME to add the new admin read-only account to the groups cloud_controller.admin_read_only and scim.read.

    $ uaac member add cloud_controller.admin_read_only Bob
    $ uaac member add scim.read Bob
    

Create a Global Auditor

The global auditor account has read-only access to all Cloud Controller API resources but cannot access secret data such as environment variables.

Perform the following steps to create a global auditor account.

  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. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Run uaac user add NEW-USERNAME -p NEW-PASSWORD --emails NEW-EMAIL to create a global auditor user. Replace NEW-USERNAME, NEW-PASSWORD, and NEW-EMAIL with appropriate information.

    $ uaac user add Alice -p SecretPassword --emails alice@example.com
    

  4. Ensure that the cloud_controller.global_auditor group exists.

    $ uaac group add cloud_controller.global_auditor
    

  5. Run uaac member add GROUP NEW-USERNAME to add the new global auditor account to the cloud_controller.global_auditor group.

    $ uaac member add cloud_controller.global_auditor Alice
    

Grant Admin Permissions to an External Group (SAML or LDAP)

Follow the steps below to grant all users under an external 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. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Run the commands below to grant all users under the mapped LDAP Group admin permissions. Replace GROUP-DISTINGUISHED-NAME with an appropriate group name.

    • uaac group map --name scim.read "GROUP-DISTINGUISHED-NAME"
    • uaac group map --name cloud_controller.admin "GROUP-DISTINGUISHED-NAME"
  4. Retrieve the name of your SAML provider by opening your Cloud Foundry manifest and recording the value of the login.saml.providers.provider-name property.

  5. Run the commands below to grant all users under the mapped SAML group admin permissions. Replace GROUP-NAME with the group name, and SAML-PROVIDER-NAME with the name of your SAML provider.

    • uaac group map --name scim.read "GROUP-NAME" --origin SAML-PROVIDER-NAME
    • uaac group map --name cloud_controller.admin "GROUP-NAME" --origin SAML-PROVIDER-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. Run cf login -u NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD to log in.

    $ cf login -u Adam -p newAdminSecretPassword
    

  3. Run 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. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  3. Run 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: aBcdEfg0hIJKlm123.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, add the permissions by following these steps:

    • Run uaac client update admin --scope "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.
    • Run uaac token delete to delete the local token.
    • Run 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 --scope "`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. Run 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.

Follow the steps below to retrieve user email addresses:

  1. Run 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. Run uaac token client get admin -s ADMIN-CLIENT-PASSWORD to authenticate and obtain an access token for the admin client from the UAA server. Replace ADMIN-CLIENT-PASSWORD with your admin password. UAAC stores the token in ~/.uaac.yml.

    $ uaac token client get admin -s MyAdminPassword
    

  4. Run 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: aBcdEfg0hIJKlm123.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, add the permissions by following these steps:

    • Run 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.
    • Run uaac token delete to delete the local token.
    • Run 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. Run 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. Run 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
    
Create a pull request or raise an issue on the source for this page in GitHub