# 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`.