161sh/Gatekeeper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update Docs

Browse Source
This commit is contained in:
Root 2023-11-04 18:05:32 +01:00
parent d69fe93f09
commit e9470b709e
1 changed files with 82 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/API/README.md
View File

@ -1,82 +1,128 @@
=== General === # General
The API is using versioning to provide compatibility with legacy services. The API is using versioning to provide compatibility with legacy services.
The base URL looks like this: The base URL looks like this:
/api/<version>/<interface>/<action>(/<id or attibute>)
/api/<version>/<interface>/<action>(/<id or attibute>)
So, for example, So, for example,
/api/v1/user/provision/maxmuster
=== Request body: Service authentication === /api/v1/user/provision/maxmuster
In order to use APIs that are limited to access by their corresponding service,
add the following parameters in request body:
{ ## Request body: Service authentication
"auth": {
"service": "<servicename>", In order to use APIs that are limited to access by their corresponding service, add the following parameters in request body:
"token": "<servicetoken>"
{
"auth": {
"service": "<servicename>",
"token": "<servicetoken>"
}
} }
}
=== Request body: Request data === ## Request body: Request data
In order to provide additional parameters with a request, add them to the data node. 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 : The request body might have a similar structure to this :
{ {
"auth": { "auth": {
"service": "<servicename>", "service": "<servicename>",
"token": "<servicetoken>" "token": "<servicetoken>"
}, },
"data": { "data": {
"<key>": "<value>", "<key>": "<value>",
"<key>": "<value>" "<key>": "<value>"
}
} }
}
=== Browser Authorization Flow: Fully interactive === ## Browser Authorization Flow: Fully interactive
_Insert explanation here_
*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". 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) 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" 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/<grant id> 4. The Service now has the obligation to redirect the user to `domain.tld/sso/<grant id>`
5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) 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 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) 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 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 -> The user is logged into the service now
=== Browser Authorization Flow: Partially interactive === ## Browser Authorization Flow: Partially interactive
_Insert explanation here_ _Insert explanation here_
Pre. The user indicates some kind of wish to authenticate 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) 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" 2. On success, Gatekeeper API returns the Grant ID for the service to save in memory, with result status "created"
_User Perspective_ _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/<grant id>
3.2 The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) 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/<grant id>
3.3 A session ticket is generated (internally) and the browser window closes
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_ _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) 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 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 -> The user is logged into the service now
=== Browser Authorization Flow: OTP === ## Browser Authorization Flow: OTP
_Insert explanation here_ _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". 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) 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/<grant id> 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/<grant id>`
5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission) 4. 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) 5. 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 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 -> The user is logged into the service now
=== Browser Authorization Flow: Reverse OTP === ## Browser Authorization Flow: Reverse OTP
_Insert explanation here_ _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". 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) 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" 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 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) 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 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) 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 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
-> 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": "<Generated Grant ID, Alphanumeric>",
"service": "<Requesting Service's Name, Alphanumeric>",
"create": "<Unix Timestamp at creation time, Numeric>",
"result": "created"
}