From fae236336044ff5de2ddcb3135820502580caae8 Mon Sep 17 00:00:00 2001 From: cclohmar Date: Wed, 15 Jul 2026 14:28:54 +0000 Subject: [PATCH] chore: add OpenAPI 3.0.3 spec for API documentation --- openapi.yml | 424 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 openapi.yml diff --git a/openapi.yml b/openapi.yml new file mode 100644 index 0000000..8620c56 --- /dev/null +++ b/openapi.yml @@ -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/.*$"]