User Management Module

👥 Secure Access Control

The User Management Module provides comprehensive functionality for managing user accounts, authentication, authorization, and password operations in PyAutomation. This module implements a role-based access control (RBAC) system that ensures secure access to system resources while providing flexible permission management for different user roles.

Overview

PyAutomation's user management system enables:

• User Account Management: Create, update, and delete user accounts
• Role-Based Access Control: Assign roles with different permission levels to control system access
• Secure Authentication: Token-based authentication system for API and web interface access
• Password Management: Change and reset user passwords with proper authorization
• Session Management: Control user sessions and API token lifecycle
• Third-Party Integration: Generate tokens for external system integration

User Roles and Permissions

PyAutomation implements a hierarchical role-based access control system where each role has a permission level. Lower numbers indicate higher privileges.

Available Roles

The system includes the following default roles (ordered by permission level):

• sudo (level 0): Highest privilege level

  • System administrator with full access to all system functions
  • Can manage all users and roles
  • Can create Third Party Tokens (TPT)
  • Cannot change their own password (security feature)
  • Use Case: System administrators, IT managers

• admin (level 1): Administrative access

  • Full access to most system functions
  • Can manage users with role_level >= admin
  • Can change passwords of users with role_level >= admin
  • Use Case: Plant managers, department supervisors

• supervisor (level 2): Supervisory access

  • Enhanced access beyond operator level
  • Can monitor and manage operational aspects
  • Use Case: Shift supervisors, senior operators

• operator (level 10): Operator access

  • Standard operational access
  • Can perform routine operations and monitor systems
  • Use Case: Plant operators, field technicians

• auditor (level 100): Read-only access for auditing

  • View-only access to system data and logs
  • Cannot modify system configurations or data
  • Use Case: Compliance auditors, quality inspectors

• guest (level 256): Limited guest access

  • Minimal access privileges
  • Use Case: Visitors, temporary access

Permission Hierarchy

When a user has a lower role level number, they have permissions to manage users with equal or higher role level numbers. For example:

• A sudo user (level 0) can manage all users
• An admin user (level 1) can manage admin, supervisor, operator, auditor, and guest users
• A supervisor user (level 2) can manage supervisor, operator, auditor, and guest users

This hierarchy ensures that higher-privileged users can manage lower-privileged users, but not vice versa.

The System User

PyAutomation includes a special built-in user account called system that is automatically created and maintained by the application. This user is essential for internal system operations and automated processes.

Purpose

The system user is designed for:

• Automated Internal Actions: System-level operations that require authentication
• Background Processes: Tasks that need to execute without human intervention
• System Integration: Internal API calls and service-to-service communication
• Bootstrap Operations: Initial system setup and configuration

Automatic Creation and Maintenance

The system user is automatically created or updated every time PyAutomation starts:

1. On First Start: If the system user doesn't exist, PyAutomation creates it automatically with:
2. Username: system
3. Role: sudo (highest privilege level)
4. Email: system@intelcon.com
5. Name: System
6. Last Name: Intelcon

7. Password: Set from the AUTOMATION_SUPERUSER_PASSWORD environment variable

8. On Subsequent Starts: If the system user already exists, PyAutomation automatically resets its password to match the current value of AUTOMATION_SUPERUSER_PASSWORD in the environment configuration.

This ensures that the system user's password always matches the configuration defined in your .env file, providing a consistent and manageable way to control this critical account.

Configuring the System User Password

The system user's password is controlled exclusively through the environment variable AUTOMATION_SUPERUSER_PASSWORD in your .env file.

Configuration via .env File

1. Locate or Create .env File:
2. The .env file should be in the root directory of your PyAutomation installation

3. If it doesn't exist, create it

4. Set the Password:

   AUTOMATION_SUPERUSER_PASSWORD="your_secure_password_here"
   

5. Security Recommendations:

6. Use a strong, unique password for the system user
7. Change the default password before deploying to production
8. Never commit the .env file to version control
9. Store the password securely (consider using secrets management systems)

10. Rotate the password periodically for enhanced security

11. Password Requirements:

12. The password should be strong and secure
13. Avoid using default or easily guessable passwords
14. Consider using a password generator for production environments

Example .env Configuration

# PyAutomation Configuration
AUTOMATION_PORT=8050
AUTOMATION_HMI_PORT=3000
AUTOMATION_APP_SECRET_KEY="your_secret_key_here"

# System User Password
AUTOMATION_SUPERUSER_PASSWORD="super_secure_password_123!@#"

Changing the System User Password

To change the system user's password:

1. Update .env File:
2. Edit the .env file and set a new value for AUTOMATION_SUPERUSER_PASSWORD

3. Save the file

4. Restart PyAutomation:

5. Restart the PyAutomation application
6. On startup, PyAutomation will automatically reset the system user's password to the new value

Important Notes: * The system user password is only controlled through the environment variable * Password changes made through the User Management interface will be overwritten on the next restart * The system user cannot change its own password through the normal password change mechanism * Always restart PyAutomation after changing AUTOMATION_SUPERUSER_PASSWORD to ensure the change takes effect

Using the System User

The system user can be used for:

• Initial Bootstrap: Log in with the system user to create your first admin user
• Recovery: If all admin users are lost or locked out, use the system user to recover access
• Automation: Use the system user credentials for automated scripts and integrations
• System Maintenance: Perform system-level operations that require sudo privileges

Security Warning: Because the system user has sudo privileges, protect the AUTOMATION_SUPERUSER_PASSWORD value carefully. Anyone with access to this password has full system control.

User Management Dashboard

The User Management interface provides a comprehensive view of all user accounts and their configurations.

Dashboard Features

The User Management dashboard displays:

• Username: Unique identifier for each user
• Email: User's email address
• Name: User's first name
• Last Name: User's last name
• Role: User's assigned role (displayed as a colored badge)
• Role Level: Numeric permission level
• Actions: Management buttons for each user (Edit, Reset Password, Delete)

Dashboard Actions

• Manage Roles: Button to access role management (shield icon)
• Create User: Button to create new user accounts
• Edit User: Edit icon to modify user information
• Reset Password: Key icon to reset user passwords
• Delete User: Delete icon to remove user accounts
• Pagination: Navigate through multiple pages when many users exist

Authentication

PyAutomation uses token-based authentication for secure access to the system. Users authenticate once and receive an API token that is used for subsequent requests.

Login Process

To authenticate and obtain an API token:

1. Navigate to Login Screen: Access the PyAutomation login interface

1. Enter Credentials:
2. Enter your username
3. Enter your password
4. Optionally check "Remember me" to persist your session

1. Submit Login: Click the "Login" button

2. Receive Token: Upon successful authentication, you receive an API token and are redirected to the main dashboard

Login via API

To authenticate programmatically via the API:

Endpoint: POST /api/users/login

Request Body:

{
  "username": "your_username",
  "password": "your_password"
}

Successful Response:

{
  "apiKey": "your_token_here",
  "role": "admin",
  "role_level": 1,
  "datetime": "MM/DD/YYYY, HH:MM:SS",
  "timezone": "America/Lima"
}

Using the Token: Include the token in subsequent API requests using the X-API-KEY header:

curl -X GET 'http://localhost:8050/api/tags/' \
  -H 'X-API-KEY: your_token_here'

Logout

To invalidate your session token:

Via Web Interface: Click logout in the user menu

Via API: Endpoint: POST /api/users/logout

Include your token in the X-API-KEY header. After logout, the token is invalidated and cannot be used for further requests.

Creating User Accounts

New user accounts can be created through the web interface or via the API.

Creating Users via Web Interface

1. Access Signup: Click "Create a new account" on the login screen or navigate to the signup page

1. Fill User Information:
2. Username: Unique identifier for the user (required)
3. Email: User's email address (required)
4. Password: Initial password for the user (required)
5. Name: User's first name (optional)

6. Last Name: User's last name (optional)

7. Submit Registration: Click "Sign Up" to create the account

8. Default Role: New users are typically assigned the "guest" role by default, which can be changed later by administrators

Creating Users via API

Endpoint: POST /api/users/signup

Request Body:

{
  "username": "new_user",
  "email": "user@example.com",
  "password": "secure_password",
  "name": "John",
  "lastname": "Doe",
  "role_name": "operator"
}

Authorization: Requires admin or sudo privileges to specify a role_name. Regular users can only create accounts with default guest role.

Managing Users

Viewing Users

The User Management dashboard provides a comprehensive list of all users with their details and current configurations.

Editing Users

To modify an existing user's information:

1. Locate the user in the User Management dashboard
2. Click the Edit icon (pencil/square icon) in the Actions column
3. Modify the desired fields (Email, Name, Last Name, Role)
4. Save changes

Note: Username typically cannot be changed after creation. Password changes are handled separately through password management functions.

Deleting Users

To remove a user account:

1. Locate the user in the User Management dashboard
2. Click the Delete icon (trash icon) in the Actions column
3. Confirm the deletion in the confirmation dialog
4. The user account will be permanently removed

Important: * Deleting a user removes their account and all associated data * Ensure backups are in place if historical data retention is required * Only users with appropriate permissions can delete other users

Password Management

PyAutomation provides two distinct methods for password management, each designed for specific use cases and with different authorization requirements.

Changing Password

Use the change password functionality when you know your current password and want to update it.

When to Use: * You remember your current password * You want to update your password as a security measure (regular rotation) * An administrator wants to change another user's password (with proper authorization)

Requirements: * When changing your own password: current_password is required * When an admin changes another user's password: current_password is not required

Authorization Rules: * Sudo users: Can change passwords of users with role "admin" only (cannot change their own password) * Admin users: Can change passwords of users with role_level >= admin (level 1 or higher) * Other roles: Can only change their own password

Via Web Interface: 1. Access user settings or password change interface 2. Enter current password 3. Enter new password 4. Confirm new password 5. Submit changes

Via API: Endpoint: POST /api/users/change_password

Request Body:

{
  "target_username": "john_doe",
  "new_password": "newSecurePassword123",
  "current_password": "oldPassword"
}

Headers: Include your API token in X-API-KEY header

Resetting Password

Use the reset password functionality when a password has been forgotten or needs to be reset without knowing the current password.

When to Use: * You have forgotten your password * An administrator needs to reset a user's password without knowing the current one * Password recovery scenarios * Security incidents requiring immediate password reset

Requirements: * No current_password is required * Still requires proper authorization based on user roles

Authorization Rules: * Sudo users: Can reset passwords of users with role "admin" only (cannot reset their own password) * Admin users: Can reset passwords of users with role_level >= admin (level 1 or higher) * Other roles: Can only reset their own password (if they have a valid session token)

Via Web Interface: 1. Click the Reset Password icon (key icon) next to the user in User Management 2. Enter new password 3. Confirm password reset

Via API: Endpoint: POST /api/users/reset_password

Request Body:

{
  "target_username": "john_doe",
  "new_password": "newSecurePassword123"
}

Headers: Include your API token in X-API-KEY header

Password Management Scenarios

Scenario 1: User Changing Own Password

Situation: A regular user wants to update their password.

Steps: 1. User authenticates to obtain a token 2. User accesses password change interface 3. Enters current password and new password 4. Submits change request

Result: Password is updated if current password is correct.

Scenario 2: Admin Resetting Operator Password

Situation: An admin needs to reset an operator's forgotten password.

Steps: 1. Admin authenticates to obtain a token 2. Admin navigates to User Management 3. Admin clicks Reset Password icon for the operator 4. Admin sets new password and confirms

Result: Operator's password is reset (admin has permission because operator role_level >= admin).

Scenario 3: User Forgot Password

Situation: A user has forgotten their password and needs to reset it.

Steps: 1. If user has a valid session token, they can reset their own password 2. If user cannot authenticate, they must contact an administrator 3. Administrator resets the password using Reset Password functionality

Note: If the user cannot authenticate at all, they will need to contact an administrator to reset their password, as there is no self-service password recovery mechanism.

Role Management

Roles define the permission levels and access rights for users. The User Management module includes functionality to manage roles, though the default roles are typically sufficient for most use cases.

Managing Roles

Click the Manage Roles button (shield icon) in the User Management dashboard to access role management functionality.

Creating Custom Roles

While PyAutomation includes comprehensive default roles, custom roles can be created if needed for specific organizational requirements.

Considerations: * Custom roles should fit into the existing permission hierarchy * Role levels determine permission relationships * Lower level numbers = higher privileges * Ensure custom roles align with security policies

Third Party Tokens (TPT)

Third Party Tokens (TPT) are JWT (JSON Web Token) tokens designed for third-party system integration. These tokens allow external applications to authenticate with PyAutomation without requiring user login credentials.

Purpose

TPT tokens enable:

• Third-party integrations: Allow external systems to access PyAutomation APIs
• Automated services: Enable service-to-service communication without human intervention
• Long-lived access: Create tokens that don't expire with user sessions
• System integration: Connect PyAutomation with other industrial systems, SCADA systems, or enterprise software

Creating TPT Tokens

Who can create TPT tokens: * Only users with the sudo role can create TPT tokens

How to create a TPT token:

1. Authenticate as a sudo user to obtain your API token
2. Send a POST request to /api/users/create_tpt:

   {
     "role_name": "admin"
   }
   

3. Include your sudo user token in the X-API-KEY header

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "role": "admin",
  "created_on": "2024-01-15 10:30:45",
  "message": "Third Party Token created successfully"
}

Using TPT Tokens

TPT tokens can be used in the X-API-KEY header just like regular user tokens. The token contains: * Role: The role name embedded in the token * Created timestamp: When the token was created

Example usage:

curl -X GET 'http://localhost:8050/api/tags/' \
  -H 'X-API-KEY: tpt_token_here'

Security Considerations

Token Security: * TPT tokens are signed using AUTOMATION_APP_SECRET_KEY from your environment configuration * Store TPT tokens securely in third-party systems * Never commit TPT tokens to version control or expose them in logs * Use HTTPS when transmitting tokens over networks

Best Practices: * Regularly rotate TPT tokens for enhanced security * Use the minimum required role level for the token (principle of least privilege) * Create separate tokens for different integrations * Revoke and recreate tokens if they are compromised * Monitor token usage for suspicious activity

Token Scope: * Choose the appropriate role level for each integration * Don't use sudo-level tokens unless absolutely necessary * Consider using admin or operator level tokens for most integrations

Security Best Practices

Password Security

1. Use Strong Passwords:
2. Choose passwords with a mix of uppercase and lowercase letters, numbers, and special characters
3. Minimum length of 12-16 characters recommended

4. Avoid dictionary words, personal information, or common patterns

5. Change Passwords Regularly:

6. Update passwords periodically as a security measure
7. Rotate passwords every 90 days for production systems

8. Change passwords immediately if compromise is suspected

9. Protect the System User Password:

10. Use a very strong password for AUTOMATION_SUPERUSER_PASSWORD
11. Store the .env file securely and never commit it to version control
12. Limit access to the .env file to authorized personnel only

Token Security

1. Don't Share Tokens:
2. Keep your API tokens secure and don't share them with others
3. Each user should use their own token

4. Don't embed tokens in client-side code

5. Logout When Done:

6. Always logout when finished to invalidate your session token

7. Use logout functionality for API tokens when integration completes

8. Rotate TPT Tokens:

9. Regularly rotate Third Party Tokens
10. Revoke old tokens when creating new ones
11. Update integrations with new tokens

Access Control

1. Role-Based Access:
2. Understand your role's permissions and limitations
3. Assign users the minimum role level required for their job function

4. Regularly review user roles and permissions

5. Principle of Least Privilege:

6. Don't grant sudo or admin roles unless necessary
7. Use operator or supervisor roles for most users

8. Use auditor role for users who only need read access

9. Regular Audits:

10. Periodically review user accounts and remove inactive users
11. Verify that user roles match current job responsibilities
12. Audit TPT token usage and remove unused tokens

System Security

1. Environment Configuration:
2. Use strong values for AUTOMATION_APP_SECRET_KEY
3. Change default passwords before production deployment

4. Secure .env files and configuration files

5. Network Security:

6. Use HTTPS for production deployments
7. Restrict network access to PyAutomation services

8. Implement firewall rules to limit access

9. Monitoring and Logging:

10. Monitor authentication attempts and failed logins
11. Review operational logs regularly
12. Set up alerts for suspicious activity

Common Use Cases

Initial System Setup

1. Access System User:
2. Use the system user credentials (from AUTOMATION_SUPERUSER_PASSWORD) to log in
3. Create your first admin user account

4. Log out from system user

5. Create Admin Users:

6. Log in with admin credentials
7. Create additional admin users as needed
8. Configure user roles according to organizational structure

User Onboarding

1. Create User Account:
2. Admin creates new user account via User Management
3. Assign appropriate role based on job function

4. Set initial password or allow user to set password on first login

5. User First Login:

6. User logs in with initial credentials
7. User changes password (recommended)
8. User begins using the system

Password Recovery

1. User Forgot Password:
2. User contacts administrator
3. Administrator resets password using Reset Password function
4. Administrator provides new password to user securely
5. User changes password after first login

Integration Setup

1. Create TPT Token:
2. Sudo user creates TPT token with appropriate role level
3. Token is provided to integration team
4. Integration uses token in API requests
5. Token is stored securely in integration system

Troubleshooting

Authentication Issues

Problem: Cannot log in with valid credentials

Solutions: * Verify username and password are correct (check for typos) * Ensure user account exists and is active * Check that user role is properly configured * Verify database connection is working * Check system logs for authentication errors

Problem: Token not working in API requests

Solutions: * Verify token is included in X-API-KEY header * Check that token hasn't expired or been invalidated * Ensure token was obtained from successful login * Verify API endpoint URL is correct

Password Issues

Problem: Cannot change password

Solutions: * Verify current password is correct * Check that you have permission to change the password * Ensure new password meets requirements * For system user, password can only be changed via .env file

Problem: Admin cannot reset another user's password

Solutions: * Verify admin has appropriate role level * Check that target user's role level is >= admin's role level * Ensure admin token is valid and included in request

User Management Issues

Problem: Cannot create user with specific role

Solutions: * Verify you have permission to create users with that role * Check that role exists in the system * Ensure role level hierarchy allows the assignment

Problem: Cannot delete user

Solutions: * Verify you have permission to delete users * Check that user is not a system user (system user cannot be deleted) * Ensure user's role level allows deletion by your role

System User Issues

Problem: System user password not working

Solutions: * Verify AUTOMATION_SUPERUSER_PASSWORD is set correctly in .env file * Restart PyAutomation to ensure password is synchronized * Check that .env file is in the correct location * Verify environment variable is being loaded correctly

Problem: System user password changed but doesn't take effect

Solutions: * Restart PyAutomation after changing AUTOMATION_SUPERUSER_PASSWORD * The system user password is reset on every application start * Password changes made via User Management interface are overwritten on restart

Navigation to Related Modules

User Management integrates with other PyAutomation modules:

• Database: User accounts, roles, and authentication data are stored in the database
• Operational Logs: User actions, logins, and password changes are logged
• Events: Authentication events and user management actions generate system events
• Alarms: Users can be associated with alarm acknowledgments and management

Getting Started

To begin working with User Management:

1. Initial Access:

   • Use the system user credentials (from AUTOMATION_SUPERUSER_PASSWORD in .env) to log in
   • This provides sudo-level access for initial setup

2. Create Admin Users:

   • Create your first admin user account through the User Management interface
   • Assign the "admin" role to this user
   • Log out from system user and log in with admin credentials

3. Configure User Accounts:

   • Create user accounts for all personnel who will use the system
   • Assign appropriate roles based on job functions
   • Set initial passwords or allow users to set passwords on first login

4. Establish Security Practices:

   • Change the system user password from default value
   • Implement password policies
   • Review and configure role assignments
   • Set up monitoring for authentication and user management activities

5. Integrate with Systems:

   • If needed, create TPT tokens for third-party integrations
   • Configure integration systems with appropriate access tokens
   • Monitor token usage and rotate as needed