cwms-cli version 0.4.0 required

At the moment, before our authorization contract in complete and a new "server-admin" application is created, user roles will need to be managed in CWBI environments (dev,test,prod) using CDA. Tools have been developed in cwms-cli to allow this management to occur using the command line.

Step 1: User Creation

Before roles can be assigned the user needs to be created in the environment. To do that, the user needs to goto the CDA swagger page for the environment they want a user in.

2. Find the OpenIDConnect (OAuth2, authorization_code with PKCE) authorization. It is near the top after apikey.

3. Hit the Authorize Button for that option.

4. It will open a new tab and prompt you for a CAC login. If it connects correctly you will see the following.

sometime it may have trouble connecting to CWBI keycloak. If that happens you will see the following error. Just wait a little and try hitting the authorize button again.

5. Then you need to do something that uses your authentication. Best endpoint to try is the get auth/keys. Hit try it out in the endpoint. This should give 403 "Missing roles {Role{name='CWMS Users'}}" error. If you get a Token error then you will likely need to try step 4 again.

6. Once the user has been created someone with CWMS ADMIN privileges can apply roles to the user using cwms-cli.

Step 2: Assigning Roles using CWMS-CLI

Once a user is created roles can assigned by a user who has CWMS ADMIN privileges for that office using cwms-cli. Make sure that you are using cwms-cli version > 0.4.0

The user can show a list of usernames or look up a user using the following command. Note if the user has environment variables set for CDA_API_ROOT and CDA_API_KEY the -a and -k parameters can be omitted and the script will grab those from the environment variable directly. Just be sure that they are set to the correct environment.

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

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

#all users that match with the like text (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

once the correct user id is obtained then roles can be assigned. Roles can be assigned using the specific role names or by using on of the following key words: readonly, readwrite, admin. using a key word will apply all the necessary CWMS roles to the user without having to list the individually.

#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

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

#show 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

roles can also be delete for a user. the key word 'all' can be used to delete all the roles from that user (note: ALL USERS role can not be deleted once added).

#delete all roles for a user for a specific office 
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 3: create an apikey

If you have a need for an api key then you can create one using the swagger page. This is only needed for running scripts or doing CDA functions that require a key. Your user will need permissions first before you can compete this step.

1) goto the swagger page for the environment you want a key for. Authorize your session using the steps in STEP1 1-5.

2) goto the post auth/keys endpoint. Hit TRY IT OUT and the fill in the json with your information like shown below. If you do not know your user-id it is usually your name as shown on your CAC card. Lastname.firstname.middlename (or initial).EDIPI (dod number). Add a key name and then up the expiration date. then hit post.

If you do not know you user-id you can look it up using the user management get user profile endpoint. Simply hit execute and it will list your user name in the responce.

3) grab the key from the response and save it.