From d69fe93f09f74f1c53d8846e33bf14a159f8e2b6 Mon Sep 17 00:00:00 2001 From: Root Date: Sat, 28 Oct 2023 22:23:09 +0200 Subject: [PATCH] Work on API Documentation --- docs/API/README.md | 82 ++++++++++++++++++++++++++++++++ src/Tor/Controller/TicketApi.php | 2 +- 2 files changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/API/README.md b/docs/API/README.md index e69de29..8b13161 100644 --- a/docs/API/README.md +++ b/docs/API/README.md @@ -0,0 +1,82 @@ +=== General === +The API is using versioning to provide compatibility with legacy services. +The base URL looks like this: +/api///(/) + +So, for example, +/api/v1/user/provision/maxmuster + +=== Request body: Service authentication === +In order to use APIs that are limited to access by their corresponding service, +add the following parameters in request body: + +{ + "auth": { + "service": "", + "token": "" + } +} + +=== Request body: Request data === +In order to provide additional parameters with a request, add them to the data node. +The request body might have a similar structure to this : + +{ + "auth": { + "service": "", + "token": "" + }, + "data": { + "": "", + "": "" + } +} + +=== Browser Authorization Flow: Fully interactive === +_Insert explanation here_ +1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO". +2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create) +3. On success, Gatekeeper API returns the Grant ID for the service to save in memory, with result status "created" +4. The Service now has the obligation to redirect the user to domain.tld/sso/ +5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) +6. A session ticket is generated (internally) and the user is being redirected back to the service's callback url +7. The service fetches the session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch) +8. The service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id +-> The user is logged into the service now + +=== Browser Authorization Flow: Partially interactive === +_Insert explanation here_ +Pre. The user indicates some kind of wish to authenticate +1. The corresponding service fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create) +2. On success, Gatekeeper API returns the Grant ID for the service to save in memory, with result status "created" +_User Perspective_ +3.1 The user might want to log into the service by clicking on a link, an action (might be a button or other actuator) targeting domain.tld/sso/ +3.2 The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) +3.3 A session ticket is generated (internally) and the browser window closes +_Service Perspective_ +6. The service regularly checks for a session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch) +7. On success the service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id +-> The user is logged into the service now + +=== Browser Authorization Flow: OTP === +_Insert explanation here_ +1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO". +2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create) +3. On success, Gatekeeper API returns the Grant ID for the service to add to a link, suggesting the user to visit: domain.tld/sso/ +5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) +6. The SSO calls a service's script that sets the OTP for the user (as a password or dedicated otp code) +7. On Success, a session ticket and an OTP Code is generated and the user is being presented with an openwith: Intent Link containing the user and otp code or instructions to enter the OTP Code in the OTP or Password field of the service ui +-> The user is logged into the service now + +=== Browser Authorization Flow: Reverse OTP === +_Insert explanation here_ +1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO". +2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create) +3. On success, Gatekeeper API returns the Grant ID and an OTP Code for the service to save in memory, with result status "created" +4. The Service instructs the user to manually visit domain.tld/otp/ +5. The User types in the OTP Code displayed by the service +6. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) +7. A session ticket is generated and the browser window closes +8. The service fetches the session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch) +9. The service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id +-> The user is logged into the service now \ No newline at end of file diff --git a/src/Tor/Controller/TicketApi.php b/src/Tor/Controller/TicketApi.php index e746473..84b3621 100644 --- a/src/Tor/Controller/TicketApi.php +++ b/src/Tor/Controller/TicketApi.php @@ -82,7 +82,7 @@ class TicketApi extends BaseApi { $result = [ 'start' => $ticket->start, - 'end' = $ticket->end, + 'end' => $ticket->end, 'result' => 'expired' ];