Introduction

This guide outlines the procedures for a Contract Admin to manage users within a contract they administer. This includes adding new users to the contract and changing the roles of existing members. These processes are designed with security in mind, ensuring that only authorized personnel can modify contract memberships. Access to this functionality is strictly controlled, and all actions are logged. Please follow these steps carefully.

Only users designated as a "Contract Admin" for a specific contract or platform "Superadmins" can manage members within that contract.

Note on User Identity Management

The Fubwer platform leverages Google Cloud Platform's (GCP) Firebase Authentication as the foundation for its user identity management. This means that core user account functionalities such as:

• User registration (creation of new accounts)
• Secure password storage and management
• Email address verification
• User sign-in and session management

are handled by the robust and secure infrastructure provided by Firebase.

Fubwer builds upon this standard identity layer by adding its own application-specific authorization and role management system. This includes defining roles like "Superadmin," "Contract Admin," "Editor," etc., and managing their permissions related to contracts, projects, and other platform resources. While Firebase handles who the user is, Fubwer defines what that user can do within the application.

This approach ensures that user identities are managed according to industry best practices for security and scalability, while allowing Fubwer to implement fine-grained access control tailored to its specific operational needs.

Adding a New User to a Contract

As a Contract Admin, you can add existing platform users to the contracts you administer.

Procedure:

1. Navigate to Contract Members:
   • Log in to the platform.
   • Go to your Dashboard.
   • Locate the contract you wish to manage and click on the "Manage Members" icon (usually a "users" or "group" icon) or navigate through the contract's "View Projects" link to find the member management section. This will take you to the "Manage Members" page for that specific contract.
2. Initiate Add Member:

   On the "Manage Members" page, look for an "Add Member" or "+" button. Click it to open the "Add New Member" dialog or form.

3. Search for User by Email:

   In the "Add New Member" dialog, you will be prompted to search for the user you wish to add. Enter the exact email address of the platform user you want to add to the contract. The system will search for the user.

4. User Not Found? Contact Superadmin:

   If the user is not found by email, it means they might not yet be registered on the platform, or there might be a typo in the email address.

   Action: Please reach out to a platform Superadmin to request the user(s) be added to the platform or to verify their existing registration. Provide the Superadmin with the following critical information for each user:

   • Full Name
   • Email Address
   • Desired initial role within your contract (e.g., "Editor All Projects", "Viewer")

   CSV Sample for Requesting Multiple Users: If you need multiple users added, you can provide the information in a CSV format like this:

   FullName,Email,DesiredContractRole
   Jack Joe,jack.joe@example.com,EDITOR
   Florean Maximilian,florean.maximilian@example.com,VIEWER
   Jane Doe,jane.doe@example.com,ADMIN

   Once the Superadmin confirms the user is on the platform, you can proceed to add them to your contract using steps 3-6.

5. Select User and Assign Role:

   If the user is found, their details (e.g., display name, email) will appear. Select the user from the search results. You will then be prompted to assign a role to this user within this contract. Refer to the "Contract Roles Explained" section below for details on each role.

   Note: As a Contract Admin, you cannot assign another user the "Contract Admin" role. This privilege is reserved for Superadmins.

6. Confirm Addition:

   Review the user and the selected role. Click the "Add Member", "Confirm", or "Save" button to add the user to the contract with the specified role.

7. Confirmation/Feedback:

   The system will process the request. You should receive a notification (e.g., a toast message) indicating whether the user was successfully added or if an error occurred. The newly added member should now appear in the contract's member list.

If you encounter any other issues, please contact a Superadmin for assistance.

Changing an Existing User's Role in a Contract

As a Contract Admin, you can modify the roles of users who are already members of your contract.

Procedure:

1. Navigate to Contract Members:

   Follow step 1 from the "Adding a New User" procedure to reach the "Manage Members" page for your contract.

2. Locate the User:

   In the list of contract members, find the user whose role you wish to change.

3. Initiate Role Change:

   Next to the user's name or in an "actions" column, look for an "Edit Role" button/icon (often a pencil icon). Click it. This will typically open an "Edit Member Role" dialog or modal.

4. Select New Role:

   The dialog will show the user's current role and provide a dropdown or list of available roles you can assign. Select the new desired role for the user from the available options. Refer to the "Contract Roles Explained" section below for details on each role.

   Note: As a Contract Admin, you cannot assign or change a user's role to "Contract Admin." This option will not be available to you. Only Superadmins can assign this role.

5. Confirm Role Change:

   Review the selected new role. Click the "Save Changes," "Update Role," or "Confirm" button.

6. Confirmation/Feedback:

   The system will process the role change. You should receive a notification indicating success or failure. The user's role in the member list should update to reflect the change.

Contract Roles Explained

The following roles can be assigned to users within a contract. Each role grants different levels of access and capabilities:

Note: The exact permissions for each role are defined by the settings in the application configuration. Not all these roles may be applicable to your contract. If you have questions about specific capabilities, please consult a Superadmin.

Technical Process Flow for Adding a User

When a Contract Admin adds a user to a contract, the following high-level technical steps occur:

1. The Frontend (FE) application (Manage Members Page) initiates a request to search for the user.
2. The FE calls the Backend (BE) API endpoint for user search, providing the email and the contractId.
3. The BE verifies the Contract Admin's authentication token.
4. The BE then authorizes the request, confirming the Contract Admin has the necessary contract_admin role for the specified contractId.
5. If authorized, the BE searches for the user by email.
6. The BE returns the found user's details to the FE.
7. The FE displays the user, and the Contract Admin confirms the addition and assigns a role.
8. The FE calls another BE API endpoint to add the user as a member to the contract, including their assigned role.
9. The BE validates this request and adds the user to the contract's member list in the database.

This ensures that all additions are authenticated, authorized, and correctly recorded.

Process Flow: Add, remove and edit a Member

          sequenceDiagram
              actor CA as Contract Admin
              participant FE as Frontend (Manage Members UI)
              participant BE_Search as Backend (User Search API)
              participant BE_Members as Backend (Contract Members API)
              participant AuthSvc as Auth Service (Token/Claims)
              participant DB as Database (Firestore)

              CA->>FE: Clicks "Add Member"
              FE->>CA: Shows "Add Member" dialog
              CA->>FE: Enters user's email & initiates search
              FE->>BE_Search: GET /api/users/search?email=...&contractId=... (with Auth Token)
              BE_Search->>AuthSvc: Verify Token
              AuthSvc-->>BE_Search: Token Valid (UID, Claims)
              BE_Search->>AuthSvc: Authorize: Is user Superadmin OR Contract Admin for contractId?
              Note over BE_Search,AuthSvc: Uses contractLevelAuthorizeUserRole
              AuthSvc-->>BE_Search: Authorization Granted
              BE_Search->>DB: Search user by email
              DB-->>BE_Search: User details (if found)
              BE_Search-->>FE: Returns user details
              FE->>CA: Displays found user
              CA->>FE: Selects user, assigns role, confirms addition
              FE->>BE_Members: POST /api/contracts/{contractId}/members (with user UID, role, Auth Token)
              BE_Members->>AuthSvc: Verify Token
              AuthSvc-->>BE_Members: Token Valid
              BE_Members->>AuthSvc: Authorize: Is caller Contract Admin for this contractId?
              AuthSvc-->>BE_Members: Authorization Granted
              BE_Members->>DB: Add user to contract members subcollection
              DB-->>BE_Members: Success/Failure
              BE_Members-->>FE: Confirmation
              FE->>CA: Shows success/error message
            

Diagram: Flow for adding, removing and edition a member on a contract.