summaryrefslogtreecommitdiff
path: root/api
diff options
context:
space:
mode:
authorAmir Zarrinkafsh <nightah@me.com>2021-01-03 15:28:46 +1100
committerGitHub <noreply@github.com>2021-01-03 15:28:46 +1100
commit3487fd392e770c3e4c7af9aa5ef8e3e25b9a73eb (patch)
tree3cf3be7e2239df1c9acdf94b729c080da14b4c0b /api
parent689fd7cb954afd5eaeab49e122cdd2ee86bc6c82 (diff)
[FEATURE] Add API docs and swagger-ui (#1544)
* [FEATURE] Add API docs and swagger-ui This change will serve out swagger-ui at the `/api/` root path. * Update descriptions and summaries in API spec * Utilise frontend assets from unit testing for Docker build steps * Fix tag for /api/user/* endpoints * Fix response schema for /api/user/info/2fa_method * Template and inject the session name during runtime into swagger-ui This change also factorises and renames index.go into template.go, this can now be generically utilised to template any file. * Fix integration tests * Add U2F endpoints * Change swagger directory to api This change is to more closely conform to the golang-standards project layout. * Add authentication for u2f endpoints * Modify u2f endpoint descriptions * Rename and fix u2f 2fa sign endpoints * Fix request body for /api/secondfactor/u2f/sign endpoint Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>
Diffstat (limited to 'api')
-rw-r--r--api/index.html60
-rw-r--r--api/openapi.yml752
2 files changed, 812 insertions, 0 deletions
diff --git a/api/index.html b/api/index.html
new file mode 100644
index 000000000..070b716e4
--- /dev/null
+++ b/api/index.html
@@ -0,0 +1,60 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <title>Swagger UI</title>
+ <link rel="stylesheet" type="text/css" href="{{.Base}}/api/swagger-ui.css" >
+ <link rel="icon" type="image/png" href="{{.Base}}/api/favicon-32x32.png" sizes="32x32" />
+ <link rel="icon" type="image/png" href="{{.Base}}/api/favicon-16x16.png" sizes="16x16" />
+ <style nonce="{{.CSPNonce}}">
+ html
+ {
+ box-sizing: border-box;
+ overflow: -moz-scrollbars-vertical;
+ overflow-y: scroll;
+ }
+
+ *,
+ *:before,
+ *:after
+ {
+ box-sizing: inherit;
+ }
+
+ body
+ {
+ margin:0;
+ background: #fafafa;
+ }
+ </style>
+ </head>
+
+ <body>
+ <div id="swagger-ui"></div>
+
+ <script src="{{.Base}}/api/swagger-ui-bundle.js" charset="UTF-8"> </script>
+ <script src="{{.Base}}/api/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+ <script nonce="{{.CSPNonce}}">
+ window.onload = function() {
+ // Begin Swagger UI call region
+ const ui = SwaggerUIBundle({
+ url: "{{.Base}}/api/openapi.yml",
+ dom_id: '#swagger-ui',
+ deepLinking: true,
+ presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIStandalonePreset
+ ],
+ plugins: [
+ SwaggerUIBundle.plugins.DownloadUrl
+ ],
+ layout: "StandaloneLayout"
+ })
+ // End Swagger UI call region
+
+ window.ui = ui
+ }
+ </script>
+ </body>
+</html>
diff --git a/api/openapi.yml b/api/openapi.yml
new file mode 100644
index 000000000..646f5dd6a
--- /dev/null
+++ b/api/openapi.yml
@@ -0,0 +1,752 @@
+---
+openapi: 3.0.0
+info:
+ title: Authelia API
+ description: Authelia is an open-source authentication and authorization server providing 2-factor authentication and single sign-on (SSO) for your applications via a web portal.
+ contact:
+ name: Authelia Support
+ url: https://github.com/authelia/authelia#contact-options
+ email: team@authelia.com
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0
+ version: 1.0.0
+tags:
+ - name: State
+ description: Configuration, health and state endpoints
+ - name: Authentication
+ description: Authentication and verification endpoints
+ - name: Password Reset
+ description: Password reset endpoints
+ - name: User Information
+ description: User configuration endpoints
+ - name: Second Factor
+ description: TOTP, U2F and Duo endpoints
+paths:
+ /api/configuration:
+ get:
+ tags:
+ - State
+ summary: Application Configuration
+ description: The configuration endpoint provides detailed information including available second factor methods, if any second factor policies exist and the TOTP period configuration.
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.configuration.ConfigurationBody'
+ "403":
+ description: Forbidden
+ security:
+ - authelia_auth: [ ]
+ /api/health:
+ get:
+ tags:
+ - State
+ summary: Application Health
+ description: The health check endpoint provides information about the health of Authelia.
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ /api/state:
+ get:
+ tags:
+ - State
+ summary: User Application State
+ description: The state endpoint provides detailed information including the user, current authenticate level and Authelia's configured default redirection URL.
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.StateResponse'
+ /api/verify:
+ get:
+ tags:
+ - Authentication
+ summary: Verification
+ description: The verify endpoint provides the ability to verify if a user has the necessary permissions to access a specified domain.
+ parameters:
+ - name: X-Original-URL
+ in: header
+ description: Redirection URL
+ required: true
+ style: simple
+ explode: true
+ schema:
+ type: string
+ responses:
+ "200":
+ description: Successful Operation
+ headers:
+ remote-user:
+ description: Username
+ schema:
+ type: string
+ example: john
+ remote-name:
+ description: Name
+ schema:
+ type: string
+ example: John Doe
+ remote-email:
+ description: Email
+ schema:
+ type: string
+ example: john.doe@authelia.com
+ remote-groups:
+ description: Comma separated list of Groups
+ schema:
+ type: string
+ example: admin,devs
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+ head:
+ tags:
+ - Authentication
+ summary: Verification
+ description: The verify endpoint provides the ability to verify if a user has the necessary permissions to access a specified domain.
+ parameters:
+ - name: X-Original-URL
+ in: header
+ description: Redirection URL
+ required: true
+ style: simple
+ explode: true
+ schema:
+ type: string
+ responses:
+ "200":
+ description: Successful Operation
+ headers:
+ remote-user:
+ description: Username
+ schema:
+ type: string
+ example: john
+ remote-name:
+ description: Name
+ schema:
+ type: string
+ example: John Doe
+ remote-email:
+ description: Email
+ schema:
+ type: string
+ example: john.doe@authelia.com
+ remote-groups:
+ description: Comma separated list of Groups
+ schema:
+ type: string
+ example: admin,devs
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+ /api/firstfactor:
+ post:
+ tags:
+ - Authentication
+ summary: Login
+ description: The firstfactor endpoint allows a user to login and generates an authentication cookie for authorization.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.firstFactorRequestBody'
+ responses:
+ "200":
+ description: Successful Operation
+ headers:
+ Set-Cookie:
+ style: simple
+ explode: false
+ schema:
+ type: string
+ example: authelia_session=kTTCSLupEUirZVfLeZTijezewFQnNOgs; Path=/
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.redirectResponse'
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+ /api/logout:
+ post:
+ tags:
+ - Authentication
+ summary: Logout
+ description: The logout endpoint allows a user to logout and destroy a sesssion.
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: [ ]
+ /api/reset-password/identity/start:
+ post:
+ tags:
+ - Password Reset
+ summary: Identity Verification Token Creation
+ description: "This endpoint is step 1 of 3 in the password reset process.\n\nIt validates the user session and sends the user an email with a token and a link to reset their password. This step also generates a session cookie for the rest of the process.\n\nThe same session cookie must be used for all steps in this process."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.resetPasswordStep1RequestBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/reset-password/identity/finish:
+ post:
+ tags:
+ - Password Reset
+ summary: Identity Verification Token Validation
+ description: "This endpoint is step 2 of 3 in the password reset process.\n\nIt validates the user session and reset token.\n\nThe same session cookie must be used for all steps in this process."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/reset-password:
+ post:
+ tags:
+ - Password Reset
+ summary: Password Reset
+ description: "This endpoint is step 3 of 3 in the password reset process.\n\nIt validates the user session and changes the password.\n\nThe same session cookie must be used for all steps in this process."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.resetPasswordStep2RequestBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/user/info:
+ get:
+ tags:
+ - User Information
+ summary: User Configuration
+ description: The user info endpoint provides detailed information including a users display name, preferred and registered second factor method(s).
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.UserInfo'
+ "403":
+ description: Forbidden
+ security:
+ - authelia_auth: [ ]
+ /api/user/info/2fa_method:
+ post:
+ tags:
+ - User Information
+ summary: User Configuration
+ description: The user info 2fa_method endpoint sets the users preferred second factor method.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.UserInfo.MethodBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ "403":
+ description: Forbidden
+ security:
+ - authelia_auth: [ ]
+ /api/secondfactor/totp/identity/start:
+ post:
+ tags:
+ - Second Factor
+ summary: Identity Verification TOTP Token Creation
+ description: "This endpoint performs identity verification to begin the TOTP device registration process.\n\nThe session generated from this endpoint must be utilised for the subsequent step in the `/api/secondfactor/totp/identity/finish` endpoint."
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/totp/identity/finish:
+ post:
+ tags:
+ - Second Factor
+ summary: Identity Verification TOTP Token Validation and Device Creation
+ description: "This endpoint performs identity and token verification, upon success also generates TOTP device secret and registers said device.\n\nThe session cookie generated from the `/api/secondfactor/totp/identity/start` endpoint must be utilised for the step here"
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.TOTPKeyResponse'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/totp:
+ post:
+ tags:
+ - Second Factor
+ summary: Second Factor Authentication - TOTP
+ description: "This endpoint performs second factor authentication with a TOTP key."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.signTOTPRequestBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.redirectResponse'
+ "401":
+ description: Unauthorized
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.ErrorResponse'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/u2f/sign_request:
+ post:
+ tags:
+ - Second Factor
+ summary: Second Factor Authentication - U2F (Request)
+ description: "This endpoint starts the second factor authentication process with the U2F key."
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/u2f.WebSignRequest'
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+ /api/secondfactor/u2f/sign:
+ post:
+ tags:
+ - Second Factor
+ summary: Second Factor Authentication - U2F
+ description: "This endpoint completes second factor authentication with a U2F key."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/handlers.signU2FRequestBody"
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.redirectResponse'
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+ /api/secondfactor/u2f/identity/start:
+ post:
+ tags:
+ - Second Factor
+ summary: Identity Verification U2F Token Creation
+ description: "This endpoint performs identity verification to begin the U2F device registration process.\n\nThe session generated from this endpoint must be utilised for the subsequent steps in the `/api/secondfactor/u2f/identity/finish` and `/api/secondfactor/u2f/register` endpoints."
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/u2f/identity/finish:
+ post:
+ tags:
+ - Second Factor
+ summary: Identity Verification U2F Token Validation
+ description: "This endpoint performs identity and token verification, upon success generates a U2F device registration challenge.\n\nThe session cookie generated from the `/api/secondfactor/u2f/identity/start` endpoint must be utilised for the subsequent steps here and in the `/api/secondfactor/u2f/register` endpoint."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.IdentityVerificationFinishBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/u2f.WebRegisterRequest'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/u2f/register:
+ post:
+ tags:
+ - Second Factor
+ summary: U2F Device Registration
+ description: "This endpoint performs U2F device registration."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/u2f.RegisterResponse'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/middlewares.OkResponse'
+ security:
+ - authelia_auth: []
+ /api/secondfactor/duo:
+ post:
+ tags:
+ - Second Factor
+ summary: Second Factor Authentication - Duo Mobile Push
+ description: "This endpoint performs second factor authentication with a Duo Mobile Push."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.signDuoRequestBody'
+ responses:
+ "200":
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/handlers.redirectResponse'
+ "401":
+ description: Unauthorized
+ security:
+ - authelia_auth: []
+components:
+ schemas:
+ handlers.configuration.ConfigurationBody:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ available_methods:
+ type: array
+ items:
+ type: string
+ example: [totp, u2f, mobile_push]
+ second_factor_enabled:
+ type: boolean
+ description: If second factor is enabled.
+ totp_period:
+ type: integer
+ example: 30
+ handlers.firstFactorRequestBody:
+ required:
+ - username
+ - password
+ type: object
+ properties:
+ username:
+ type: string
+ example: john
+ password:
+ type: string
+ example: password
+ targetURL:
+ type: string
+ example: https://home.example.com
+ keepMeLoggedIn:
+ type: boolean
+ example: true
+ handlers.redirectResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ redirect:
+ type: string
+ example: https://home.example.com
+ handlers.resetPasswordStep1RequestBody:
+ required:
+ - username
+ type: object
+ properties:
+ username:
+ type: string
+ example: john
+ handlers.resetPasswordStep2RequestBody:
+ required:
+ - password
+ type: object
+ properties:
+ password:
+ type: string
+ example: password
+ handlers.signDuoRequestBody:
+ type: object
+ properties:
+ targetURL:
+ type: string
+ example: https://secure.example.com
+ handlers.signTOTPRequestBody:
+ type: object
+ properties:
+ token:
+ type: string
+ example: "123456"
+ targetURL:
+ type: string
+ example: https://secure.example.com
+ handlers.signU2FRequestBody:
+ type: object
+ properties:
+ targetURL:
+ type: string
+ example: https://secure.example.com
+ signResponse:
+ type: object
+ properties:
+ clientData:
+ type: string
+ example: 6prxyWqSsR6MXFchtQRzwZVTedWq7Zdc6XreLt6xRDXKeqJN7vzKAfYcKwRD3AT57bP4YFL4hbxat4LUysBNss
+ keyHandle:
+ type: string
+ example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
+ signatureData:
+ type: string
+ example: p3Pe26B6T2E7EEEc59P4p869qwxy8cQAU2ttyGtGrQHb4XL2ZxCpWrawsSHNSTRZQd7jEW59Y3Ku9vSNRzj7Ly
+ handlers.StateResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ username:
+ type: string
+ example: john
+ authentication_level:
+ type: integer
+ example: 1
+ default_redirection_url:
+ type: string
+ example: https://home.example.com
+ handlers.TOTPKeyResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ base32_secret:
+ type: string
+ example: 5ZH7Y5CTFWOXN7EOLGBMMXADRNQFHVUDZSYKCN5HMFAIRSLAWY3Q
+ otpauth_url:
+ type: string
+ example: otpauth://totp/auth.example.com:john?algorithm=SHA1&digits=6&issuer=auth.example.com&period=30&secret=5ZH7Y5CTFWOXN7EOLGBMMXADRNQFHVUDZSYKCN5HMFAIRSLAWY3Q
+ handlers.UserInfo:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ display_name:
+ type: string
+ example: John Doe
+ method:
+ type: string
+ enum: [totp, u2f, mobile_push]
+ example: totp
+ has_u2f:
+ type: boolean
+ example: false
+ has_totp:
+ type: boolean
+ example: true
+ handlers.UserInfo.MethodBody:
+ required:
+ - method
+ type: object
+ properties:
+ method:
+ type: string
+ enum: [totp, u2f, mobile_push]
+ example: totp
+ middlewares.ErrorResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ example: KO
+ message:
+ type: string
+ example: Authentication failed, please retry later.
+ middlewares.IdentityVerificationFinishBody:
+ required:
+ - token
+ type: object
+ properties:
+ token:
+ type: string
+ example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDc5MjU1OTYsImlzcyI6IkF1dGhlbGlhIiwiYWN0aW9uIjoiUmVzZXRQYXNzd29yZCIsInVzZXJuYW1lIjoiQW1pciJ9.636yqRrUCGCe4jsMCsonleX5CYWHncYqZum-YYb6VaY
+ middlewares.OkResponse:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ u2f.RegisterResponse:
+ type: object
+ properties:
+ version:
+ type: string
+ registrationData:
+ type: string
+ clientData:
+ type: string
+ u2f.WebRegisterRequest:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ appId:
+ type: string
+ example: https://auth.example.com
+ registerRequests:
+ type: array
+ items:
+ type: object
+ properties:
+ version:
+ type: string
+ example: U2F_V2
+ challenge:
+ type: string
+ example: XGYKUzSmTpM1KxxpekArviW0w0OU2pwwRAocgn8TkVQ
+ registeredKeys:
+ type: array
+ items:
+ type: object
+ properties:
+ appId:
+ type: string
+ example: https://auth.example.com
+ version:
+ type: string
+ example: U2F_V2
+ keyHandle:
+ type: string
+ example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
+ u2f.WebSignRequest:
+ type: object
+ properties:
+ status:
+ type: string
+ example: OK
+ data:
+ type: object
+ properties:
+ appId:
+ type: string
+ example: https://auth.example.com
+ challenge:
+ type: string
+ example: XGYKUzSmTpM1KxxpekArviW0w0OU2pwwRAocgn8TkVQ
+ registeredKeys:
+ type: array
+ items:
+ type: object
+ properties:
+ appId:
+ type: string
+ example: https://auth.example.com
+ version:
+ type: string
+ example: U2F_V2
+ keyHandle:
+ type: string
+ example: pWgBrwr9meS5vArdffPtD4Px6AqZS7MfGEf776Rz438ujwHjeXwQEZuK53sRQ4wjeAgRCW4wX9VRj8dyKjc273
+ securitySchemes:
+ authelia_auth:
+ type: apiKey
+ name: "{{.Session}}"
+ in: cookie \ No newline at end of file