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.

Transport layer security

All communication between the involved LiquidFeedback API server, the API consumer and the user agent (if any) must be secured with Transport Layer Security (TLS, e.g. HTTPS). The only exception is communication to the API server when using public read access without any authorization involved.

When using TLS, the API consumer must check the identity of the API server before making a request or sending credentials.

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.

Authorization Code Grant

This autorization scheme is used by native applications and server based web applications.

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

This authorization scheme is used by JavaScript applications running in a users web browser

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

response_type Always set to "token" (mandatory)

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

scope The requested access level (mandatory)

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 application/x-www-form-urlencoded as URI fragment (after the '#'):

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)

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 uses the access token to accesses API server methods until the access token expires.

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

Client Credentials Grant

This authorization scheme is used by non-interactive applications which only need read access.

When using this grant type, the API is limited to read only access level.

1. 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 "client_credentials" (mandatory)

client_id Set to the issued client identifier (mandatory)

client_secret Used to authenticate the client (mandatory)

scope May be set to a lower scope than maximum scope registered for the application (optional)

2. 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)

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

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.