> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/alliance-risk-analysis-tool/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management

> Add users, manage permissions, assign admin roles, and control access to the platform

# User Management

This guide covers how administrators manage users and control access to the CGIAR Risk Intelligence Tool. All user management features require **Admin** role privileges.

<Note>
  **Admin Access Required**: Only users with administrator privileges can access user management features. Regular users can only manage their own profile.
</Note>

## Overview

The platform uses **AWS Cognito** for user authentication and access control. Administrators can:

* Create new user accounts
* Assign roles and permissions
* Enable or disable accounts
* Reset user passwords
* View user activity
* Delete accounts

## Accessing User Management

<Steps>
  ### Navigate to Admin Panel

  1. Click your profile menu in the top-right corner
  2. Select **"Admin Panel"** from the dropdown
  3. Click **"User Management"** in the admin navigation

  <Screenshot>
    **Admin Panel Navigation**
    Show: Top navigation with user dropdown expanded, "Admin Panel" highlighted. Left sidebar showing "User Management" tab active.
  </Screenshot>

  ### User Management Dashboard

  The main view displays all platform users in a paginated table with:

  **Columns**:

  * **User**: Avatar, name, and last login date
  * **Email**: User's email address (also username)
  * **Role**: Admin or User badge (color-coded)
  * **Status**: Active (green) or Inactive (gray) badge
  * **Actions**: Edit and delete buttons

  **Table Features**:

  * Search by name or email
  * Filter by role (All, Admin, User)
  * Filter by status (All, Active, Inactive)
  * Pagination (60 users per page)

  <Screenshot>
    **User Management Table**
    Show: Clean table layout with 5-6 user rows showing avatars with initials, names, emails, role badges (Admin in purple, User in blue), status badges (Active in green), and edit/delete icons.
  </Screenshot>
</Steps>

## Creating New Users

<Steps>
  ### Open Create User Modal

  Click **"Add User"** button in the top-right corner of the User Management page.

  <Screenshot>
    **Add User Button**
    Show: Top-right corner of user management page with green "Add User" button highlighted.
  </Screenshot>

  ### Enter User Details

  Provide the following information:

  **Required Fields**:

  * **Email**: User's email address (becomes their username)
  * **Temporary Password**: Initial password (minimum 8 characters)

  **Optional Settings**:

  * **Send Welcome Email**: Toggle to automatically email login instructions
  * **Assign Admin Role**: Check to grant administrator privileges

  **Password Requirements**:

  * Minimum 8 characters
  * At least one uppercase letter
  * At least one lowercase letter
  * At least one number
  * At least one special character (!@#\$%^&\*)

  <Screenshot>
    **Create User Modal**
    Show: Dialog with Email input field, Password input field, "Send Welcome Email" toggle (enabled), and "Assign Admin Role" checkbox (unchecked). "Create User" button at bottom.
  </Screenshot>

  ### Assign Role

  Choose the appropriate access level:

  | Role               | Permissions                                                | Use For                                         |
  | ------------------ | ---------------------------------------------------------- | ----------------------------------------------- |
  | **User** (default) | Create assessments, view own reports, add comments         | Risk analysts, project managers, standard users |
  | **Admin**          | All User permissions + user management + prompt management | Platform administrators, technical leads        |

  <Note>
    **Admin Privileges**: Admin users can access User Management, Prompt Manager, and all system configuration areas. Grant this role carefully.
  </Note>

  ### Create Account

  1. Review all entered information
  2. Click **"Create User"**
  3. System creates the account in Cognito
  4. If "Send Welcome Email" was enabled, user receives login instructions
  5. New user appears in the table immediately
</Steps>

## Welcome Email

When enabled, new users receive an automated email with:

* Platform welcome message
* Login URL: `https://[your-domain]/login`
* Their username (email address)
* Temporary password
* Instructions to change password on first login

<Warning>
  **Password Change Required**: All new users must change their temporary password on first login. This is a Cognito security requirement.
</Warning>

## Editing User Details

<Steps>
  ### Open Edit User Modal

  Click the **pencil icon** (✏️) next to any user in the table.

  ### Update User Attributes

  You can modify:

  **Editable Attributes**:

  * **Email**: Change user's email address
  * **Name**: Update display name
  * **Role**: Add or remove admin privileges
  * **Custom attributes**: Any additional Cognito attributes

  **Read-Only Information**:

  * Username (cannot be changed)
  * Account creation date
  * Last login timestamp
  * Cognito user ID

  <Screenshot>
    **Edit User Modal**
    Show: Dialog showing user avatar, email field with "[john.doe@example.com](mailto:john.doe@example.com)", Name field with "John Doe", Groups section showing "admin" tag, and action buttons: "Reset Password", "Disable User", "Delete User" in different colors.
  </Screenshot>

  ### Manage Groups

  Assign or remove user from groups:

  **Available Groups**:

  * **admin**: Grants full administrative access
  * Additional groups can be created via Cognito console

  **To add admin privileges**:

  1. In the Edit modal, locate "Groups" section
  2. Click **"Add to admin group"**
  3. User immediately gains admin permissions

  **To remove admin privileges**:

  1. Click the **×** next to "admin" tag
  2. Confirm removal
  3. User reverts to standard user permissions

  ### Save Changes

  Click **"Save Changes"** to apply updates. Changes take effect immediately.
</Steps>

## Resetting User Passwords

Administrators can set new temporary passwords for users:

<Steps>
  ### Access Password Reset

  1. Click **Edit** (✏️) on the user
  2. In the Edit User modal, click **"Reset Password"** button

  ### Set Temporary Password

  1. Enter a new temporary password meeting requirements
  2. Click **"Reset Password"**
  3. System updates the password in Cognito

  ### Notify the User

  After resetting:

  * Share the temporary password securely (not via email)
  * Inform user they'll need to change it on next login
  * User will see "NEW\_PASSWORD\_REQUIRED" challenge when logging in

  <Warning>
    **Forced Password Change**: Users with reset passwords cannot access the platform until they set a new permanent password through the login flow.
  </Warning>
</Steps>

## Enabling and Disabling Users

### Disable a User Account

To temporarily revoke access without deleting:

1. Click **Edit** (✏️) on the user
2. Click **"Disable User"** button
3. Confirm the action
4. User status changes to **Inactive** (gray badge)

**Effects of disabling**:

* User cannot log in
* Active sessions are terminated
* All data and assessments are preserved
* Account can be re-enabled at any time

<Screenshot>
  **Disabled User State**
  Show: User table row with "Inactive" status badge in gray, showing user still listed but clearly marked as disabled.
</Screenshot>

### Re-enable a User Account

1. Click **Edit** (✏️) on the disabled user
2. Click **"Enable User"** button
3. Confirm the action
4. User status changes to **Active** (green badge)
5. User can immediately log in again

**Use Cases for Disabling**:

* Employee on extended leave
* Suspected security issues requiring investigation
* Temporary suspension pending review
* Account cleanup before final deletion

## Deleting Users

<Warning>
  **Permanent Action**: Deleting a user is irreversible. The user account and all authentication data are permanently removed from Cognito. Their assessments and data remain in the database.
</Warning>

<Steps>
  ### Initiate Deletion

  From the user table:

  1. Click the **trash icon** (🗑️) next to the user, or
  2. Click **Edit** → **"Delete User"** button in the modal

  ### Confirm Deletion

  A confirmation dialog appears:

  ```
  Delete User

  Are you sure you want to delete [email]?
  This action cannot be undone.

  [Cancel] [Delete]
  ```

  Click **"Delete"** to proceed.

  ### What Gets Deleted

  **Removed**:

  * Cognito user account
  * Login credentials
  * User attributes and groups
  * MFA settings

  **Preserved**:

  * Assessments created by the user (ownership transferred to system)
  * Comments and activity logs (attributed to deleted user ID)
  * Historical audit trails
</Steps>

## Searching and Filtering

### Search Users

Use the search bar at the top of the table:

1. Type user name or email (partial matches work)
2. Results filter in real-time
3. Search is case-insensitive
4. Clear search to see all users

<Screenshot>
  **Search Bar**
  Show: Search input field with magnifying glass icon, showing "john" typed in and filtered results below showing only users with "john" in name or email.
</Screenshot>

### Filter by Role

Use the **Role** dropdown:

* **All Roles**: Show everyone (default)
* **Admin**: Show only administrators
* **User**: Show only regular users

Filtering resets to page 1.

### Filter by Status

Use the **Status** dropdown:

* **All Statuses**: Show everyone (default)
* **Active**: Show only enabled users
* **Inactive**: Show only disabled users

Combine with role filter for precise queries (e.g., "Show inactive admins").

### Combined Filtering

All filters work together:

* Search: "smith"
* Role: "Admin"
* Status: "Active"

Result: Active administrators with "smith" in name or email.

## Pagination

The user table supports cursor-based pagination:

**Navigation**:

* **Previous** button (◀): Go back one page
* **Page indicator**: Shows current page number
* **Next** button (▶): Advance to next page

**Limits**:

* Maximum 60 users per page (Cognito limit)
* Default: 60 users per page
* Filters reset pagination to page 1

<Screenshot>
  **Pagination Controls**
  Show: Bottom of table with pagination controls - "◀" previous button (disabled), page "1" indicator, "▶" next button (enabled). Text showing "Showing 60 results — page 1".
</Screenshot>

<Note>
  **Large User Bases**: For organizations with 500+ users, use filters and search to narrow results instead of browsing all pages.
</Note>

## User Activity Tracking

Each user row displays activity information:

**Last Login**: Timestamp of most recent successful login

* Shown below user name in the table
* Format: "Last login: Mar 4, 2026"
* Updates after each successful authentication

**Account Created**: Available in the Edit User modal

* Shows original account creation date
* Useful for auditing user tenure

<Screenshot>
  **User Activity Info**
  Show: User table row highlighting the "Last login: Feb 28, 2026" timestamp below the user name.
</Screenshot>

## Best Practices

<Accordion title="Password Management">
  **Creating Secure Temporary Passwords**:

  * Use random, complex passwords
  * Don't use patterns (e.g., "Welcome123!")
  * Never reuse passwords across users
  * Share passwords securely (encrypted channels)
  * Document that user must change on first login

  **Password Reset Policy**:

  * Only reset when user forgets password
  * Verify user identity before resetting
  * Log all password reset actions
  * Consider MFA for sensitive accounts
</Accordion>

<Accordion title="Role Assignment">
  **Admin Role Guidelines**:

  * Limit admin access to essential personnel only
  * Review admin list quarterly
  * Remove admin privileges when no longer needed
  * Use separate admin accounts for automation

  **When to Grant Admin**:

  * Platform administrators
  * Technical leads managing prompts
  * User onboarding coordinators
  * Senior analysts needing system oversight

  **When NOT to Grant Admin**:

  * Standard risk analysts
  * Temporary contractors
  * External consultants
  * Users who only create assessments
</Accordion>

<Accordion title="Account Lifecycle">
  **New User Onboarding**:

  1. Create account with role appropriate to duties
  2. Send welcome email with instructions
  3. Verify first login within 48 hours
  4. Provide platform training
  5. Assign initial test assessment

  **Offboarding Users**:

  1. Disable account immediately upon departure
  2. Review and reassign their assessments
  3. Export any user-specific reports needed
  4. Delete account after 30-day retention period
  5. Document deletion in admin log
</Accordion>

<Accordion title="Regular Maintenance">
  **Monthly Tasks**:

  * Review inactive users (no login in 90+ days)
  * Disable or delete unused accounts
  * Audit admin user list
  * Check for anomalous login patterns

  **Quarterly Tasks**:

  * Export full user list for records
  * Review role assignments
  * Update user onboarding documentation
  * Verify contact information is current
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User Can't Log In">
    **Check account status**:

    * Is account Active or Inactive? (Enable if needed)
    * Was password recently reset? (User must change it)
    * Is email address correct?

    **Verify credentials**:

    * Username is their email address
    * Password is case-sensitive
    * No extra spaces in email or password

    **Try reset**:

    * Admin reset password
    * User tries "Forgot Password" flow
    * Check spam folder for reset emails
  </Accordion>

  <Accordion title="User Can't Access Admin Features">
    **Verify admin role**:

    * Check Groups section in Edit User modal
    * Should show "admin" tag
    * If missing, click "Add to admin group"

    **Session refresh needed**:

    * User must log out and back in
    * Admin permissions require new session
    * Wait 1-2 minutes for Cognito sync

    **Browser issues**:

    * Clear browser cache and cookies
    * Try incognito/private window
    * Check for JavaScript errors in console
  </Accordion>

  <Accordion title="Can't Create or Edit Users">
    **Permission errors**:

    * Verify you have admin role
    * Check Cognito console for service errors
    * Ensure Cognito user pool is healthy

    **Validation failures**:

    * Email must be valid format
    * Password must meet all requirements
    * No duplicate emails allowed

    **Network issues**:

    * Check internet connection
    * Verify API Gateway is reachable
    * Look for CORS errors in browser console
  </Accordion>

  <Accordion title="User List Not Loading">
    **Cognito connectivity**:

    * Check AWS service health dashboard
    * Verify API Lambda has Cognito permissions
    * Review CloudWatch logs for errors

    **Large result sets**:

    * If 1000+ users, Cognito may be slow
    * Use filters to narrow query
    * Wait up to 30 seconds for initial load

    **Session timeout**:

    * Refresh the page
    * Log out and back in
    * Check auth token expiration
  </Accordion>
</AccordionGroup>

## Security Considerations

<Warning>
  **Admin Account Security**:

  * Use strong, unique passwords for admin accounts
  * Enable MFA for all administrators
  * Never share admin credentials
  * Log all admin actions for audit trail
  * Review admin activity logs monthly
</Warning>

**Access Control Best Practices**:

* Follow principle of least privilege
* Regularly review and remove unnecessary permissions
* Disable accounts immediately when users leave
* Monitor for suspicious login patterns
* Enforce password expiration policies

**Compliance and Auditing**:

* Export user lists quarterly for compliance
* Maintain logs of all user management actions
* Document role assignment rationale
* Review access controls during security audits

## Next Steps

* [Configure authentication settings →](/admin/authentication)
* [Set up multi-factor authentication →](/admin/mfa)
* [View audit logs →](/admin/audit-logs)
* [Manage user groups and permissions →](/admin/groups)