62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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`.
|