141 lines
2.7 KiB
Markdown
141 lines
2.7 KiB
Markdown
# 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`**.
|