API security specification

As explained in the LiquidFeedback API specification, the current authentication interface is preliminary and only provided for testing purposes. On this page the necessary TODOs will be discussed, to create a new authorization scheme.

It is currently planned to use  OAuth 2.0 for this purpose.

Fields of activity

• Client registration (system-wide and per user)
  • Concept for registration
  • Extend database scheme in lfcore, see  liquid_feedback_core source repository
• Change API specification and lfapi implementation to comply with the  Bearer Token specification
• Provide Authorization Endpoint(s) and Token Endpoint(s) in API specification and lfapi implementation

Important things to keep in mind for implementation

The authorization server MUST include the HTTP "Cache-Control" response header field (RFC2616) with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field (RFC2616) with a value of "no-cache".

Parameters sent without a value MUST be treated as if they were omitted from the request. The authorization server MUST ignore unrecognized request parameters. Request and response parameters MUST NOT be included more than once.

Client registration

Two forms of client registration are supported. System-wide client registration and per-member client registration. Registered clients are stored in the api_client table of the LiquidFeedback Core. For system-wide clients, the field member_id is set to NULL, while for member-registered clients, the field member_id is set to the id of the member, who registered this client for him/herself.

Unregistered clients use a client_id identical to their redirection endpoint, when directing the member to the authorization endpoint. The member is then asked automatically if he/she wants to register this client for him/herself.

Supported authorization grant types

Authorization Code Grant

1. The API consumer ("the application") (re)directs the users web browser to the API server, passing the following values as GET parameters:

response_type Always set to "code" (mandatory)

client_id Set to the redirection endpoint URI of the API consumer (mandatory)

scope The requested access level (mandatory)

duration How many seconds the OAuth authorization should be valid, 0 for infinity (optional)

state Passed value, which will be send back to the API consumer redirection endpoint, to be used for Cross Site Request Forgery protection (optional)

2. The users web browser and the API server negotiate the client authorization. The API consumer is not involved here.

3. The web browser is redirected back to the API consumer, passing the following values as GET parameters:

code An authorization code, which has to be used by the API consumer in the next step (mandatory)

state The same value as passed in step 1, which can be used by the API consumer to protect against Cross Site Request Forgery (optional)

4. The API consumer exchanges its authorization code for a refresh token and an access token by calling the POST /token method with the following parameters as GET or POST parameters:

grant_type Always set to "authorization code" (mandatory)

client_id Set to the redirection endpoint URI of the API consumer (mandatory)

client_secret Used to authenticate the client (mandatory, if client has been registered with a client secret)

code Authorization code, which was received in step 3 (mandatory)

scope May be set to a lower scope than the scope set in step 1 (optional)

5. The following values are returned by the API server as a JSON document:

access_token The access token to be used for API calls (mandatory)

token_type Always set to "Bearer", must be checked by the API consumer (mandatory)

expires_in Life time of access token in seconds (mandatory)

refresh_token A refresh token, which is to be used to issue a new refresh token and a new access token, when the access token has expired. (mandatory)

6. The API consumer uses the access token to accesses API server methods until the access token expires.

7. The API consumer refreshes its access and refresh tokens by calling the POST /token method with the following parameters as GET or POST parameters:

grant_type Always set to "refresh_token" (mandatory)

client_id Set to the redirection endpoint URI of the API consumer (optional, but mandatory if client has been registered with a client secret)

client_secret Used to authenticate the client (mandatory, if client has been registered with a client secret)

refresh_token The last refresh token returned by the POST /token method (mandatory)

scope May be set to a lower scope than the scope set in step 1 (optional)

8. The following values are returned by the API server as a JSON document:

access_token The access token to be used for API calls (mandatory)

token_type Always set to "Bearer", must be checked by the API consumer (mandatory)

expires_in Life time of access token in seconds (mandatory)

refresh_token A refresh token, replacing the previously issued refresh token (mandatory)

Implicit Grant

[TODO]

As there is no refresh token issued, access tokens can not be refreshed. If an access token has expired, the end-user must be redirected to the LiquidFeedback Security Center, to confirm access for the API consumer again.

Resource Owner Password Credentials Grant

Not supported for security reasons.

Client Credentials Grant

Supports read access only.

[TODO]

As there is no refresh token issued, access tokens acquired by this grant type can not be refreshed using a refresh token. However at any time an API consumer can use its client credentials again, to receive a new access token.