Gatekeeper/docs/API/README.md

General

The API is using versioning to provide compatibility with legacy services.

The base URL looks like this:

/api/<version>/<interface>/<action>(/<id  or  attibute>)

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": "<servicename>",
        "token": "<servicetoken>"
    }
}

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": "<servicename>",
        "token": "<servicetoken>"
    },
    "data": {
        "<key>": "<value>",
        "<key>": "<value>"
    }
}

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/<grant id>
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/
4. 2. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
5. 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/<grant id>
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

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

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"
}

Errors:

{
    "error": {
        "message": "<Exception Message>" (500)
    }
}

Grant: Destroy (E)

Deletes the identified grant from the system and invalidates all Session Tickets potentially issued in name of the Grant

Request:

URL:
/api/v1/grant/destroy/<Grant ID>
    
Body:
{
    ... auth ...
    "data": {}
}

Response:

{
    "result": "destroyed"
}

Errors:

{
    "error": {
        "message": "not found" (404) //
        "message": "<Exception Message>" (500)
    }
}

Grant: Status (E)

Fetch Authorization Status of Grant and get a list of data associated with the grant, such as creation time

Request:

URL:
/api/v1/grant/status/<Grant ID>
    
Body:
{
    ... auth ...
    "data": {}
}

Response:

{
    "grant": "<Generated  Grant  ID,  Alphanumeric>",
    "service": "<Requesting  Service's  Name,  Alphanumeric>",
    "create": "<Unix  Timestamp  at  creation  time,  Numeric>",
    "status": "created",//
    "status": "approved",
    -> "ticket": "<Ticket ID>",
    "result": "ok"
}

Errors:

{
    "error": {
        "message": "not found" (404) //
        "message": "<Exception Message>" (500)
    }
}