uaa-user-management.html.md.erb

---
title: Creating and Managing Users with the UAA CLI (UAAC)
---

<strong><%= modified_date %></strong>

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](../concepts/architecture/uaa.html)
* [UAA Sysadmin Guide](https://github.com/cloudfoundry/uaa/blob/master/docs/Sysadmin-Guide.rst)
* [Other UAA Documentation](https://github.com/cloudfoundry/uaa/tree/master/docs)

## <a id='creating-admin-users'></a>Create an Admin User ##

1. Install the UAA CLI, `uaac`.
    <pre class="terminal">
    $ gem install cf-uaac
    </pre>

1. Use `uaac target uaa.YOUR-DOMAIN` to target your UAA server.
    <pre class="terminal">
    $ uaac target uaa.example.com
    </pre>

1. Record the **uaa:admin:client_secret** from your deployment manifest.

1. 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`.
    <pre class="terminal">
    $ uaac token client get admin -s MyAdminPassword
    </pre>

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

    <pre class="terminal">
    $ 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
    </pre>

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

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

    <pre class="terminal">
    $ 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
    </pre>

1. Use `uaac user add NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD --emails NEW-ADMIN-EMAIL` to create an admin user.
    <pre class="terminal">
    $ uaac user add Adam -p newAdminSecretPassword --emails newadmin@example.com
    </pre>

1. 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`.
    <pre class="terminal">
    $ 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
    </pre>

## <a id='ldap-group'></a>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.

1. 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`.
    <pre class="terminal">
    $ uaac token client get admin -s MyAdminPassword
    </pre>

1. 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"`

## <a id='creating-users'></a>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.

1. Use `cf login -u NEW-ADMIN-USERNAME -p NEW-ADMIN-PASSWORD` to log in.
    <pre class="terminal">
    $ cf login -u Adam -p newAdminSecretPassword
    </pre>

1. Use `cf create-user NEW-USER-NAME NEW-USER-PASSWORD` to create a new
user.
    <pre class="terminal">
    $ cf create-user Charlie aNewPassword
    </pre>

## <a id='changing-passwords'></a>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.

1. 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`.
    <pre class="terminal">
    $ uaac token client get admin -s MyAdminPassword
    </pre>

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

    <pre class="terminal">
    $ 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
    </pre>

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

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

    <pre class="terminal">
    $ 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
    </pre>

1. Use `uaac password set USER-NAME -p TEMP-PASSWORD` to change an
existing user password to a temporary password.
    <pre class="terminal">
    $ uaac password set Charlie -p ThisIsATempPassword
    </pre>

1. 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.
    <pre class="terminal">
    $ cf target api.example.com
    $ cf login -u Charlie -p ThisIsATempPassword
    $ cf passwd

    Current Password>ThisIsATempPassword

    New Password>*******

    Verify Password>*******
    Changing password...
    </pre>

## <a id='retrieving-email-addresses'></a>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.
    <pre class="terminal">
    $ uaac target uaa.example.com
    </pre>

1. Record the **uaa:admin:client_secret** from your deployment manifest.

1. 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`.
    <pre class="terminal">
    $ uaac token client get admin -s MyAdminPassword
    </pre>

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

    <pre class="terminal">
    $ 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
    </pre>

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

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

    <pre class="terminal">
    $ 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
    </pre>

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

    <pre class="terminal">
    $ uaac users --attributes emails

    resources:
      emails:
    value: user1@example.com
      emails:
    value: user2@example.com
      emails:
    value: user3@example.com
    </pre>

1. Use `uaac users "id eq GUID" --attributes emails` with the GUID of a specific
user to retrieve that user's email address.

    <pre class="terminal">
    $ uaac users "id eq 'aabbcc11-22a5-87-8056-beaf84'" --attributes emails

    resources:
      emails:
    value: user1@example.com
    </pre>