diff --git a/docs/API/README.md b/docs/API/README.md index 8b13161..5cecde7 100644 --- a/docs/API/README.md +++ b/docs/API/README.md @@ -1,82 +1,128 @@ -=== General === +# General + The API is using versioning to provide compatibility with legacy services. + The base URL looks like this: -/api///(/) + + /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: + /api/v1/user/provision/maxmuster -{ - "auth": { - "service": "", - "token": "" +## 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 === +## 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": { - "": "", - "": "" + { + "auth": { + "service": "", + "token": "" + }, + "data": { + "": "", + "": "" + } } -} -=== Browser Authorization Flow: Fully interactive === -_Insert explanation here_ +## 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/ +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 === +## 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 + +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 === +## 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 +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/` +4. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) +5. The SSO calls a service's script that sets the OTP for the user (as a password or dedicated otp code) +6. 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 === +## 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/ +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 + +-> The user is logged into the service now + +## Grant: Create (E) +_Generates a new grant and returns information useful for identifying the grant_ + +**Request:** + + URL: + /api/v1/grant/create + + Body: + { + ... auth ... + "data": {} + } + +**Response:** + + { + "grant": "", + "service": "", + "create": "", + "result": "created" + }