User Management
===============

This section covers user account management, profile settings, and IP responsibility features.

User Profiles
-------------

Overview
~~~~~~~~

Each user account in the Vulnerability Scanner can have:

- **Username**: Unique identifier for login
- **Full Name**: Display name (optional)
- **Email Address**: Contact email (optional)
- **Admin Status**: Whether the user has administrative privileges
- **IP Responsibilities**: List of IP addresses the user is responsible for

Accessing Your Profile
~~~~~~~~~~~~~~~~~~~~~~

1. Log in to the application
2. Click on your username in the top-right corner
3. Select **"Manage"** from the dropdown menu
4. You'll be taken to ``/profile`` where you can manage your account

Profile Management
------------------

Updating Profile Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users can update their profile information:

.. note::
   Email addresses are synchronized with Contact Person records if linked.

**Fields:**

- **Full Name**: Your display name
- **Email**: Your contact email address

**To update:**

1. Navigate to your profile page
2. Edit the **Full Name** or **Email** fields
3. Click **"Update Profile"**


.. _Changing-Password:

Changing Password
~~~~~~~~~~~~~~~~~

.. warning::
   Passwords must meet the following requirements:
   
   - Minimum 8 characters
   - At least one uppercase letter
   - At least one lowercase letter  
   - At least one digit
   - At least one special character

**To change your password:**

1. Navigate to your profile page
2. In the **Change Password** section:

   - Enter your **Current Password**
   - Enter your **New Password**
   - Confirm your **New Password**

3. Click **"Change Password"**

IP Responsibility Management
-----------------------------

Overview
~~~~~~~~

Users can be assigned responsibility for specific IP addresses. This links them to vulnerability scan results for those IPs.

Viewing Your IP Addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~

Your assigned IP addresses are displayed on your profile page under **"My IP Responsibilities"**.

Removing IP Responsibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're no longer responsible for an IP address:

1. Navigate to your profile page
2. Find the IP address in **"My IP Responsibilities"**
3. Click the **red X button** next to the IP
4. Confirm the removal

.. caution::
   Removing IP responsibility means you will no longer receive notifications for vulnerabilities on that IP.

Transferring IP Responsibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To transfer an IP to another user:

1. Navigate to your profile page
2. Find the IP address in **"My IP Responsibilities"**
3. Click the **transfer icon** (arrow) next to the IP
4. Enter the **target username**
5. Click **"Transfer"**

.. note::
   The target user must have an account and a linked Contact Person record.

Admin User Management
---------------------

Overview
~~~~~~~~

Administrators have access to a comprehensive user management interface at ``/admin/users``.

Managing All Users
~~~~~~~~~~~~~~~~~~

Administrators can:

- View all user accounts
- See each user's IP responsibilities
- Edit user profiles (full name, email, admin status)
- Remove IP assignments from any user
- Transfer IPs between users

Editing User Accounts
~~~~~~~~~~~~~~~~~~~~~~

1. Navigate to **Admin** → **User Management**
2. Click the **pencil icon** next to a user
3. Edit the following fields:

   - **Full Name**
   - **Email**
   - **Admin Status** (checkbox)

4. Click **"Save"**

Managing User IP Assignments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**To remove an IP from a user:**

1. In the User Management table, find the user
2. Click the **X** on the IP chip
3. Confirm the removal

**To transfer an IP between users:**

1. Click the **transfer icon** next to the user's IP list
2. Select the IP to transfer
3. Enter the target username
4. Click **"Transfer"**

Contact Person Integration
---------------------------

Overview
~~~~~~~~

Users and Contact Persons are linked via email address. This integration:

- Automatically links users to contact persons when emails match
- Synchronizes email changes bidirectionally
- Enables IP responsibility tracking

Auto-Linking
~~~~~~~~~~~~

When a user is created or updated:

- If a Contact Person exists with the same email, they are automatically linked
- The user inherits IP responsibilities from the Contact Person

When a Contact Person is created or updated:

- If a User exists with the same email, they are automatically linked
- Email changes sync to the linked User account

Account Status Indicator
~~~~~~~~~~~~~~~~~~~~~~~~~

In the **Contact Persons** overview (``/manage/contact-persons``):

- **Green checkmark**: Contact person has a linked user account
- **Yellow warning**: No associated user account

API Endpoints
-------------

User Profile Endpoints
~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: /users/me/profile

   Get the current user's profile information.

   **Response:**
   
   .. code-block:: json

      {
        "id": 1,
        "username": "alice.smith",
        "full_name": "Alice Smith",
        "email": "alice.smith@example.com",
        "is_admin": true,
        "ips": ["192.168.1.10", "192.168.1.11"],
        "contact_person_id": 1
      }

.. http:put:: /users/me/profile-v2

   Update the current user's profile.

   **Request Body:**
   
   .. code-block:: json

      {
        "full_name": "Alice Smith",
        "email": "alice.smith@example.com"
      }

.. http:put:: /users/me/change-password

   Change the current user's password.

   **Request Body:**
   
   .. code-block:: json

      {
        "old_password": "OldPassword123!",
        "new_password": "NewPassword123!"
      }

.. http:delete:: /users/me/ips/{ip_address}

   Remove an IP from the current user's responsibilities.

   :param ip_address: The IP address to remove

.. http:post:: /users/me/ips/{ip_address}/transfer

   Transfer an IP to another user.

   :param ip_address: The IP address to transfer

   **Request Body:**
   
   .. code-block:: json

      {
        "target_username": "bob.jones"
      }

Admin Endpoints
~~~~~~~~~~~~~~~

.. http:get:: /admin/users

   Get all users with their IP assignments (admin only).

   **Response:**
   
   .. code-block:: json

      [
        {
          "id": 1,
          "username": "alice.smith",
          "full_name": "Alice Smith",
          "email": "alice.smith@example.com",
          "is_admin": true,
          "ips": ["192.168.1.10"],
          "contact_person_id": 1
        }
      ]

.. http:put:: /admin/users/{user_id}

   Update any user's profile (admin only).

   **Request Body:**
   
   .. code-block:: json

      {
        "full_name": "Alice Smith",
        "email": "alice.smith@example.com",
        "is_admin": true
      }

.. http:delete:: /admin/users/{user_id}/ips/{ip_address}

   Remove an IP from any user (admin only).

.. http:post:: /admin/users/{from_user_id}/ips/{ip_address}/transfer/{to_user_id}

   Transfer an IP between users (admin only).

Best Practices
--------------

For Users
~~~~~~~~~

1. **Keep your email updated**: This ensures you receive vulnerability notifications
2. **Use strong passwords**: Follow the password policy requirements
3. **Review your IPs regularly**: Remove or transfer IPs you're no longer responsible for
4. **Link your account**: Ensure your user account is linked to a Contact Person record

For Administrators
~~~~~~~~~~~~~~~~~~

1. **Regular audits**: Review user accounts and IP assignments periodically
2. **Proper onboarding**: Link new users to Contact Persons during account creation
3. **Offboarding**: Remove IP responsibilities when users leave
4. **Email synchronization**: Be aware that email changes sync between Users and Contact Persons

Troubleshooting
---------------

Profile Update Fails
~~~~~~~~~~~~~~~~~~~~

**Issue**: 422 Unprocessable Entity error when updating profile

**Solution**: Ensure email format is valid. Use ``null`` for empty fields rather than empty strings.

IP Transfer Fails
~~~~~~~~~~~~~~~~~

**Issue**: "Target user has no contact person" error

**Solution**: The target user must have a linked Contact Person record. Create one or link an existing Contact Person.

Auto-Linking Not Working
~~~~~~~~~~~~~~~~~~~~~~~~~

**Issue**: User and Contact Person with same email are not linked

**Solution**: 

1. Check that emails match exactly (case-sensitive)
2. Try updating the email on either record to trigger re-linking
3. Use the admin interface to manually verify the link

Password Change Rejected
~~~~~~~~~~~~~~~~~~~~~~~~~

**Issue**: Password doesn't meet requirements

**Solution**: Ensure your password has:

- At least 8 characters
- One uppercase letter
- One lowercase letter
- One digit
- One special character (e.g., !, @, #, $)