sso

2026-01-25 14:36:01 +01:00
commit fdf1e0e8ed
22 changed files with 1269 additions and 0 deletions
--- a/docs/api_reference.md
+++ b/docs/api_reference.md
@@ -0,0 +1,140 @@
+# ASF SSO API Reference
+
+This document details the API endpoints available in the ASF SSO service.
+
+## Base URL
+`https://sso.nabd-co.com` (or `http://localhost:8001` for local dev)
+
+---
+
+## 1. SSO Verification (External Apps)
+This is the primary endpoint used by external applications to authenticate users.
+
+### `POST /verify`
+
+**Description**: Verifies a user's credentials and checks if they are authorized for the calling application.
+
+**Headers**:
+- `Content-Type: application/json`
+
+**Request Body**:
+```json
+{
+  "username": "jdoe",
+  "password": "secretpassword",
+  "api_key": "YOUR_APP_API_KEY"
+}
+```
+
+**Response (Success - 200 OK)**:
+```json
+{
+  "authorized": true,
+  "message": "Authorized",
+  "user": {
+    "username": "jdoe",
+    "email": "jdoe@example.com",
+    "is_active": true,
+    "is_admin": false,
+    "id": 5,
+    "created_at": "2026-01-25T12:00:00",
+    "updated_at": "2026-01-25T12:00:00"
+  }
+}
+```
+
+**Response (Failure - 200 OK)**:
+*Note: The API returns 200 OK even for auth failures, but with `authorized: false`.*
+```json
+{
+  "authorized": false,
+  "message": "Invalid username or password" 
+  // OR "User not authorized for this application"
+  // OR "User account is inactive"
+}
+```
+
+**Example Usage (cURL)**:
+```bash
+curl -X POST https://sso.nabd-co.com/verify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "testuser",
+    "password": "password123",
+    "api_key": "abc123xyz"
+  }'
+```
+
+---
+
+## 2. Admin Authentication
+These endpoints are for the Admin Dashboard.
+
+### `POST /token`
+
+**Description**: Login as an administrator to get an access token.
+
+**Request Body (Form Data)**:
+- `username`: admin
+- `password`: admin_password
+
+**Response**:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1Ni...",
+  "token_type": "bearer"
+}
+```
+
+---
+
+## 3. User Management (Admin Only)
+**Requires Header**: `Authorization: Bearer <access_token>`
+
+### `GET /users/`
+**Description**: List all users.
+
+### `POST /users/`
+**Description**: Create a new user.
+**Body**:
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "password123",
+  "is_admin": false
+}
+```
+
+### `PUT /users/{user_id}`
+**Description**: Update a user.
+**Body**:
+```json
+{
+  "email": "newemail@example.com",
+  "is_active": false
+}
+```
+
+### `POST /users/{user_id}/assign/{app_id}`
+**Description**: Assign a user to an application.
+
+---
+
+## 4. Application Management (Admin Only)
+**Requires Header**: `Authorization: Bearer <access_token>`
+
+### `GET /apps/`
+**Description**: List all registered applications.
+
+### `POST /apps/`
+**Description**: Register a new application.
+**Body**:
+```json
+{
+  "name": "OpenProject",
+  "url": "https://openproject.nabd-co.com"
+}
+```
+**Response**:
+Returns the created app object, including the **`api_key`**.
--- a/docs/user_guide.md
+++ b/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`.