Auth-N Documentation

Auth-N is an API designed for managing user authentication, providing security features and flexible user management.

CRITICAL WARNING: This project is currently a work in progress. It is explicitly stated that it should NOT be used in production environments.

The system implements a Role-Based Access Control (RBAC) model using four primary database tables to manage user permissions and system access:

• Roles Table: Stores available roles and their descriptions. Administrators can create, update, or delete roles.
• Permissions Table: Stores specific permissions and descriptions. Administrators manage these to define what actions are possible within the system.
• User_Roles Table: Maps users to roles. This allows users to view their assigned roles and tracks who assigned the role and when.
• Role_Permissions Table: Maps roles to specific permissions. This determines the actual access rights a user has based on the roles they are assigned.

This structure enables fine-grained access control and allows multiple administrators to collaborate on user permission management.

Role-Based Access Control (RBAC) is a policy-neutral access control mechanism where access rights are managed through roles rather than assigned directly to users. In this model, permissions are grouped into roles, and users are then assigned to those roles to inherit the associated permissions. This decoupling simplifies user assignment and scaling of access management.

Key components include:

• User: An entity assigned to one or more roles to gain access rights.
• Role: A collection of permissions used to group users with similar access requirements.
• Permission: The specific right to perform an operation on a resource.
• Resource: The object being accessed (e.g., API endpoints).

Contributors can support Auth N through several avenues:

• Code Contributions: Implementing new features, fixing bugs, or improving existing functionality.
• Documentation: Writing or improving READMEs, installation guides, API documentation, and tutorials.
• Bug Reporting: Reporting issues via the project's issue tracker with reproduction steps, expected behavior, and actual behavior.
• Testing: Running automated tests, performing manual testing, and providing UX feedback.
• Code Review: Reviewing pull requests from other contributors to ensure standards and guidelines are met.

The system determines a user's effective permissions by merging roles from their group memberships and individual assignments. The merging process follows a specific order of precedence to ensure correct inheritance and overrides:

1. Group Hierarchy Merge: Roles are merged based on the group hierarchy. Roles from parent groups are inherited by child groups and the users within them.
2. User-Level Merge: If a user has roles assigned directly to their account, these are merged with the inherited group roles.
3. Precedence: User-level roles take precedence over merged group roles, allowing individual overrides of group-level permissions.

Constraints:

• Every user must be assigned to at least one group; users cannot exist without a group.
• It is recommended to define roles at the group level rather than the user level for better scalability.

To contribute to Auth-N, developers should have the following tools and environment setup:

• Python: Version 3.10 or higher (Python 3.12 is recommended).
• Virtual Environments: Experience using Python's venv.
• Version Control: Familiarity with Git and GitHub.
• IDE: A code editor of choice (Visual Studio Code is recommended).
• Containerization: Docker and Docker Compose (recommended, though not strictly required).

The Auth N project maintains several key files in its root directory to guide contributors and users:

• CONTRIBUTING.md: Instructions and standards for project contributions.
• CODE_OF_CONDUCT.md: Guidelines for community participation and inclusivity.
• CODEOWNERS: List of individuals/teams responsible for specific project areas.
• SECURITY.md: Procedures for reporting security vulnerabilities.
• SUPPORT.md: Information on how to seek help and access support channels.
• TODO.md: A list of planned tasks, features, and improvements.
• LICENSE: Legal terms and conditions for project distribution.
• README.md: Project overview, installation, and usage guidelines.

For optimal performance and stability, it is strongly recommended to install Auth-N on a dedicated server. The server must meet the following minimum specifications:

• Operating System: Any Debian-based Linux distribution (e.g., Ubuntu, Debian).
• CPU: Minimum 2 cores.
• RAM: Minimum 2GB.
• Disk Space: 10GB recommended (covers logs, database, etc.).
• Network: A public IP address is required for API access.
• Ports: Ports 80 and 443 must be open for HTTP and HTTPS access.
• Domain: A valid domain name associated with the server is required for SSL certificates.

Note: If the database is hosted on a separate server, that server must also meet these minimum requirements.

Before installing Auth-N, ensure the following dependencies are installed on the server:

1. Docker: Auth-N is distributed as a Docker container.
2. Docker Compose: Used to manage the multiple containers required by Auth-N.