API Authentification¶

The following is a proposed authentication mechanism for handling mobile app requests. This is to facilitate other API endpoints allowing users to create cases, upload images and edit cases.

User authentification and authorisation¶

• Use the existing API Token for application authorisation
• Use a second token for the user authentification. This can be solved bei either one of the following options:
  • A: Using the existing django-based session ID, same as the web gui.
  • B: Create a Secondary authentication table, as follows:
    • One to many relationship to the Registered UserID (different mobile devices should be possible)
    • 3 fields --> 'UserID', UserToken' & 'time_stamp'
• When an API request to create a case, upload images or edit cases is received, follow the following use workflow:
1. Authenticate with the API Token to ensure user has access to API
2. Check if the Authenticated User has an 'unexpired' UserToken
   1. A time limit is used to designate stale/fresh User Tokens

• Use case 1: User has no UserToken:
1. User has to authenticate to receive a UserToken
2. Response is sent and the UserToken is included. This is the initial handshake
3. Time stamp is updated

• Use case 2: User has an Unexpired UserToken:
1. Request is accepted
2. Time stamp is extended
3. Response is served

• Use case 3: User has an Expired UserToken:
1. User is re-authenticated with the API Token
2. UserToken is refreshed
3. Response is sent and the new UserToken is included
4. Time stamp is updated

• Use case 4: User has Incorrect UserToken:
1. Invalid Response is sent

Case locking mechanism¶

Problem:

• The web application contains a locking mechanism: A draft version is locked as long as a case open in an editor/form. (* Timeout?*)
• This locking mechanism doesn't work with an offline application, because:
  • The server only knows when he sends or receives data, but it can't tell, if sent data is used for editing or view only.
  • Locking as long as the application is offline won't work, as that can take days.

• Possible solutions:

• The server receives case data (JSON) as POST on respective API endpoint (for a certain configuration/identifier):

1. Checking, if the latest version of the case is either 'active' or 'draft'
2. When latest version is 'draft', compares the last update timestamp to the timestamp of the UserToken

• *Use case 1: The latest version is 'active': *
1. Creates a new draft version with the sent JSON

• Use case 2: The latest version is not 'draft' and not 'active':
1. Data upload is rejected with: 'Case under review. Can't be updated'

• Use case 3: The latest version is 'draft':
1. Checks if timestamp of last update on server is newer than the UserToken timestamp

• Use case 4: UserToken timestamp is newer than update timestamp on server:
1. Merge sent JSON to draft version.

• User case 5: Update timestamp on server is newer than UserToken timestamp:
1. Case was updated over another device / or over website
2. Data upload is rejected with: 'Newer version exists.'