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.

Short term access tokens and mandatory refreshing of refresh tokens and access tokens

Access tokens are only valid short term. For long term access of an API consumer, the API consumer must refresh its access tokens. This refresh is done without user interaction. When an access token is refreshed, both a new access token and a new refresh token are issued by the API server. The API consumer MUST discard the old refresh token. When the new access token or the new refresh token is used for the first time, the old refresh token is automatically invalidated by the server.

Applications running in the users web-browser (i.e. JavaScript applications) and non-interactive read-only API consumers are exempted from this refresh. Applications running in the users web-browser can't get long term access at all, but will require the user to authorize the application for every session. Non-interactive read-only API consumers refresh their access token by sending their client credentials.

Optional invalidation of previously issued refresh tokens

In case of using the OAuth authorization code grant, the API consumer may request to automatically invalidate previously issued refresh tokens to increase security, if only one refresh token per member is needed at a time. Do do this, the parameter 'single_token' can be set to true, when exchanging the authorization code for the access and refresh token.

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 (string) Always set to "code" (mandatory)

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

scope (string) The requested access level (mandatory)

state (string) 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 (string) An authorization code, which has to be used by the API consumer in the next step (mandatory)

state (string) 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 (string) Always set to "authorization_code" (mandatory)

single_token (boolean) Set to true, if only one refresh token for a member is needed at a time. Old refresh tokens are automatically invalidated in this case. (optional)

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

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

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

scope (string) 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 (string) The access token to be used for API calls (mandatory)

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

expires_in (integer) Life time of access token in seconds (mandatory)

refresh_token (string) 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 (string) Always set to "refresh_token" (mandatory)

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

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

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

scope (string) 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 (string) The access token to be used for API calls (mandatory)

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

expires_in (integer) Life time of access token in seconds (mandatory)

refresh_token (string) 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 (string) Always set to "token" (mandatory)

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

scope (string) The requested access level (mandatory)

state (string) 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 (string) The access token to be used for API calls (mandatory)

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

expires_in (integer) Life time of access token in seconds (mandatory)

state (string) 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 (string) Always set to "client_credentials" (mandatory)

client_id (string) Set to the issued client identifier (mandatory)

client_secret (string) Used to authenticate the client (mandatory)

scope (string) 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 (string) The access token to be used for API calls (mandatory)

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

expires_in (integer) 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.