chore: add OpenAPI 3.0.3 spec for API documentation
This commit is contained in:
parent
38a69937d5
commit
fae2363360
1 changed files with 424 additions and 0 deletions
424
openapi.yml
Normal file
424
openapi.yml
Normal file
|
|
@ -0,0 +1,424 @@
|
|||
openapi: 3.0.3
|
||||
info:
|
||||
title: Authelia API Sidecar with Policy Management
|
||||
description: >
|
||||
An API sidecar for Authelia to manage users and access control policies dynamically.
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: http://127.0.0.1:8080
|
||||
description: Local development server
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
# --- User Management Endpoints ---
|
||||
/api/health:
|
||||
get:
|
||||
summary: Health Check
|
||||
security: [] # No auth required
|
||||
responses:
|
||||
'200':
|
||||
description: API status and version
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
version:
|
||||
type: string
|
||||
example: dev
|
||||
time:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-04-02T00:00:00Z"
|
||||
|
||||
/api/users:
|
||||
get:
|
||||
summary: List Users
|
||||
responses:
|
||||
'200':
|
||||
description: A list of users
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/UserResponse'
|
||||
|
||||
/api/users/bulk:
|
||||
post:
|
||||
summary: Bulk Create Users
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- users
|
||||
properties:
|
||||
users:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/UserCreate'
|
||||
responses:
|
||||
'200':
|
||||
description: Users successfully created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
created:
|
||||
type: integer
|
||||
example: 2
|
||||
users:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/UserCreatedDetails'
|
||||
|
||||
/api/users/{username}:
|
||||
delete:
|
||||
summary: Delete User
|
||||
parameters:
|
||||
- name: username
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: User deleted successfully
|
||||
'404':
|
||||
description: User not found
|
||||
|
||||
# --- User Policy Evaluation Endpoint ---
|
||||
/api/users/{username}/policies:
|
||||
get:
|
||||
summary: Get Policies Assigned to User
|
||||
description: >
|
||||
Evaluates and returns all access control policies that apply to this specific user,
|
||||
matching either their direct username (e.g., `user:username`) or any of the groups
|
||||
they belong to (e.g., `group:groupname`).
|
||||
parameters:
|
||||
- name: username
|
||||
in: path
|
||||
required: true
|
||||
description: The username to evaluate policies for.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: A list of policies applicable to the user, including the match criteria.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/UserPolicyMatch'
|
||||
'404':
|
||||
description: User not found
|
||||
|
||||
# --- Policy Management Endpoints ---
|
||||
/api/policies:
|
||||
get:
|
||||
summary: List Policies
|
||||
description: Retrieve all defined access control policies.
|
||||
responses:
|
||||
'200':
|
||||
description: A list of defined access control policies.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Policy'
|
||||
post:
|
||||
summary: Create Policy
|
||||
description: Create a new access control policy rule.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PolicyInput'
|
||||
responses:
|
||||
'201':
|
||||
description: Policy created successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Policy'
|
||||
'400':
|
||||
description: Invalid policy structure
|
||||
|
||||
/api/policies/{policy_id}:
|
||||
get:
|
||||
summary: Retrieve Policy details
|
||||
parameters:
|
||||
- name: policy_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Policy found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Policy'
|
||||
'404':
|
||||
description: Policy not found
|
||||
|
||||
put:
|
||||
summary: Update Policy
|
||||
description: Update an existing access control policy rule by replacing it.
|
||||
parameters:
|
||||
- name: policy_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PolicyInput'
|
||||
responses:
|
||||
'200':
|
||||
description: Policy updated successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Policy'
|
||||
'404':
|
||||
description: Policy not found
|
||||
|
||||
delete:
|
||||
summary: Remove Policy
|
||||
description: Delete an access control policy.
|
||||
parameters:
|
||||
- name: policy_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Policy deleted successfully
|
||||
'404':
|
||||
description: Policy not found
|
||||
|
||||
/api/policies/verify:
|
||||
post:
|
||||
summary: Verify Policy (Dry-run / Matcher Check)
|
||||
description: >
|
||||
Validates how a simulated request (domain, path, method, subject)
|
||||
would evaluate against the current policy rules.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- domain
|
||||
- path
|
||||
properties:
|
||||
domain:
|
||||
type: string
|
||||
example: "secure.example.com"
|
||||
path:
|
||||
type: string
|
||||
example: "/admin/dashboard"
|
||||
method:
|
||||
type: string
|
||||
example: "POST"
|
||||
username:
|
||||
type: string
|
||||
example: "test.user1"
|
||||
groups:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["developers", "admins"]
|
||||
responses:
|
||||
'200':
|
||||
description: Simulation completed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
matched:
|
||||
type: boolean
|
||||
description: True if a policy matched this pattern.
|
||||
example: true
|
||||
policy_id:
|
||||
type: string
|
||||
description: The ID of the policy rule that was matched.
|
||||
example: "pol_93f8s2"
|
||||
policy_name:
|
||||
type: string
|
||||
example: "Admin Dashboard Restrictions"
|
||||
action_required:
|
||||
type: string
|
||||
enum: [bypass, one_factor, two_factor, deny]
|
||||
example: "two_factor"
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
|
||||
schemas:
|
||||
# --- User Schemas ---
|
||||
UserCreate:
|
||||
type: object
|
||||
required:
|
||||
- username
|
||||
- display_name
|
||||
- email
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
example: john.doe
|
||||
display_name:
|
||||
type: string
|
||||
example: John Doe
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
example: john.doe@example.com
|
||||
groups:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["users", "admins"]
|
||||
|
||||
UserCreatedDetails:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/UserCreate'
|
||||
- type: object
|
||||
properties:
|
||||
placeholder_password:
|
||||
type: string
|
||||
example: "aB3$fG7!kL9*mN2@pQ"
|
||||
status:
|
||||
type: string
|
||||
example: created
|
||||
|
||||
UserResponse:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/UserCreate'
|
||||
- type: object
|
||||
properties:
|
||||
disabled:
|
||||
type: boolean
|
||||
example: false
|
||||
created_at:
|
||||
type: string
|
||||
example: "2026-04-02 00:00:00"
|
||||
updated_at:
|
||||
type: string
|
||||
example: "2026-04-02 00:00:00"
|
||||
|
||||
# --- Policy Schemas ---
|
||||
PolicyInput:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- domain
|
||||
- policy
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: A human-readable identifier for the policy rule.
|
||||
example: "Admin Dashboard Restrictions"
|
||||
domain:
|
||||
type: array
|
||||
description: Domain patterns this policy applies to (supports wildcards).
|
||||
items:
|
||||
type: string
|
||||
example: ["*.example.com", "secure.example.com"]
|
||||
resources:
|
||||
type: array
|
||||
description: Regex or exact match paths.
|
||||
items:
|
||||
type: string
|
||||
example: ["^/admin/.*$"]
|
||||
methods:
|
||||
type: array
|
||||
description: HTTP methods to restrict. If empty, all methods apply.
|
||||
items:
|
||||
type: string
|
||||
enum: [GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD]
|
||||
example: ["POST", "PUT", "DELETE"]
|
||||
subjects:
|
||||
type: array
|
||||
description: Specific users or groups this policy applies to.
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["group:admins", "user:test.user1"]
|
||||
policy:
|
||||
type: string
|
||||
description: The required authentication level to grant access.
|
||||
enum: [bypass, one_factor, two_factor, deny]
|
||||
example: "two_factor"
|
||||
|
||||
Policy:
|
||||
allOf:
|
||||
- type: object
|
||||
required:
|
||||
- id
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Unique system identifier for the policy.
|
||||
example: "pol_93f8s2"
|
||||
- $ref: '#/components/schemas/PolicyInput'
|
||||
|
||||
UserPolicyMatch:
|
||||
type: object
|
||||
required:
|
||||
- policy_id
|
||||
- name
|
||||
- match_reason
|
||||
- policy
|
||||
properties:
|
||||
policy_id:
|
||||
type: string
|
||||
example: "pol_93f8s2"
|
||||
name:
|
||||
type: string
|
||||
example: "Admin Dashboard Restrictions"
|
||||
match_reason:
|
||||
type: string
|
||||
description: Explains if the policy matched due to a direct username rule or a group membership.
|
||||
example: "Matched via group membership: admins"
|
||||
policy:
|
||||
type: string
|
||||
enum: [bypass, one_factor, two_factor, deny]
|
||||
example: "two_factor"
|
||||
domain:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["*.example.com"]
|
||||
resources:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["^/admin/.*$"]
|
||||
Loading…
Reference in a new issue