Managing User Accounts and Permissions via CDA and CWMS-CLI

This guide is intended to help you manage user accounts and permissions in CWBI environments (DEV, TEST, PROD) via CDA and CWMS-CLI (version 0.4.0 or higher).

Step 1: Log In to the Target Environment

Before assigning roles, you must initialize your account in the target environment.

  1. Navigate to the CDA Swagger UI.
    1. e.g., https://water.dev.cwbi.us/cwms-data/swagger-ui
  2. Click Authorize.
  3. Scroll up until you find the OpenIDConnect (OAuth2, authorization_code with PKCE) option.
  4. Click Authorize and complete the CAC login in the new tab.
    1. If a Keycloak connection error appears, wait a moment and retry.
  5. The screen will display the following information once you are connected.
  6. Close the Available Authorizations window.

Step 2: Authenticate Your Session

Now you should authenticate your session by running a test endpoint.

  1. Under the Authorization section, expand the Get auth keys option and click Try it out.
  2. You should expect to see a 403 "Missing roles {Role{name='CWMS Users'}}" error.
    1. If you receive a token error, repeat the authorization step (Step 1 above).
  3. Provide your user ID to a CWMS ADMIN so they can complete Step 3.

Step 3: Manage Roles using CWMS-CLI

Administrative users with CWMS ADMIN privileges can manage user roles using CWMS-CLI (version 0.4.0 or greater).

Finding Users

#list all users in the database
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY

#list all users with permissions for a specific office
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY -o MVP

#search for users matching a text pattern (in this example any user with wilson in anyplace in the user ID will be shown)
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY -ul wilson

Viewing Roles

#view all roles assigned to a user across all offices
cwms-cli users roles list-user -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455

#view roles assigned to a user for a specific office
cwms-cli users roles list-user -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 -o SWL

Assigning Roles

Roles can be assigned individually or by using shorthand keywords (readonly, readwrite, admin) to apply standard role bundles automatically.

#show all available roles
cwms-cli users roles list-all -a $CDA_URL -k $CDA_API_KEY

#assign readwrite permissions to a user for office SWL
cwms-cli users roles add -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 --roles readwrite -o SWL

#assign specific roles to a user for office SWT
cwms-cli users roles add -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 --roles "CWMS Users,All Users" -o SWT

Removing Roles


#remove all roles for a user for a specific office (Note: 'All Users' cannot be deleted)
cwms-cli users roles delete -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.1102680282 --roles all -o SWL

#delete specific roles from a user for a specific office
cwms-cli users roles delete -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.1102680282 --roles "CWMS USER" -o SWT

Step 4: Create an API Key (Optional)

This step is only required for automated scripts or CDA functions that use an API key. You must have active user permissions before generating a key.

  1. Authorize your session on the target environment's Swagger page following the steps outlined in Step 1 above.
  2. Locate your exact user ID (typically formatted as LASTNAME.FIRSTNAME.MIDDLE.EDIPI, viewable via the user profile endpoint).
  3. Go to the POST auth/keys endpoint and click Try it out.
  4. Submit the JSON body containing your key name and expiration date by clicking Execute.
  5.  Copy and securely save the generated API key from the response.