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.

Multiple authorizations per member for a single client

Proposal: When authorizing a client, the user shall see any previously issued long-term authorizations for that client, which are still active. Any previous long-term authorization shall be revoked by default, thus invalidating previously issued refresh tokens for that client, unless the user explicitly agrees to a duplicate authorization (e.g. for multiple native client on different smartphones). For manually registered clients, the behaviour regarding previously issued authorizations may be configured (field code_grant_multiple in table api_client), thus avoiding an interactive decision by the user.

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_idis 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 (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)

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

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)

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.