sso

docs/user_guide.md

@@ -0,0 +1,61 @@
+# ASF SSO Application - User Guide
+
+## Overview
+The **ASF SSO (Single Sign-On)** application is a centralized authentication service designed to manage user access across multiple web applications within the ASF ecosystem. It provides a secure and unified way to handle user credentials and application permissions.
+
+## Key Features
+- **Centralized User Management**: Create, update, and manage users from a single admin portal.
+- **Application Management**: Register new applications and generate secure API keys.
+- **Access Control**: Assign specific users to specific applications.
+- **SSO Verification**: Secure API for external applications to verify user credentials and access rights.
+- **Email Notifications**: Automatically sends welcome emails and password update notifications to users.
+- **Modern UI**: A responsive, dark-themed dashboard for administrators.
+
+## Architecture
+- **Backend**: Python FastAPI (High performance, easy to maintain).
+- **Database**: SQLite (Self-contained, easy to backup).
+- **Frontend**: Vanilla HTML/CSS/JavaScript (Lightweight, no build step required).
+- **Deployment**: Docker & Docker Compose (Containerized for consistency).
+
+## Workflows
+
+### 1. Admin Login
+The application is protected by an admin login.
+- **URL**: `https://sso.nabd-co.com`
+- **Default Credentials**: `admin` / `admin` (Change this immediately after first login).
+
+### 2. Managing Users
+- **Create User**:
+    1. Navigate to the **Users** tab.
+    2. Click **Add User**.
+    3. Enter Username, Email, and Password.
+    4. Click **Save**.
+    5. *Result*: The user is created, and a welcome email is sent to them.
+- **Edit User**: Click **Edit** next to a user to update their details or reset their password.
+
+### 3. Managing Applications
+- **Register Application**:
+    1. Navigate to the **Applications** tab.
+    2. Click **Add Application**.
+    3. Enter the Application Name and URL.
+    4. Click **Save**.
+    5. *Result*: The application is listed, and a unique **API Key** is generated.
+    6. **Important**: Copy the API Key. You will need to configure it in the external application.
+
+### 4. Assigning Access
+Users cannot log in to an application unless they are explicitly assigned to it.
+1. Go to the **Users** tab.
+2. Click **Assign App** next to the user.
+3. Select the target application from the dropdown.
+4. Click **Assign**.
+
+## Integration Logic
+When a user tries to log in to an external application (e.g., OpenProject):
+1. The external app collects the username and password from the user.
+2. The external app sends a secure request to the SSO `verify` endpoint.
+3. The SSO service checks:
+    - Is the API Key valid?
+    - Are the username and password correct?
+    - Is the user assigned to this application?
+    - Is the user account active?
+4. If all checks pass, SSO returns `Authorized`. Otherwise, it returns `Unauthorized`.