sso/docs/user_guide.md

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.