API Authentication

Work In Progress!

API Authentication

This page describes the authentication mechanism for the HTTP API.

Introduction

Users of the Tasking Manager web interface "log into" the application using their OSM credentials. Tasking Manager uses Oauth for that. What Tasking Manager gets from OSM is the user's id and display_name.

What is important to note and is that Tasking Manager doesn't have its own authentication system. And Tasking Manager doesn't have user passwords in its database. Using OAuth OSM grants Tasking Manager access to the user details.

For the API we need a way to identify the application that sends requests to change states in Tasking Manager (change task states, …). We cannot rely on OAuth, because users of the application should not need to "log in". They may not even be OSM users.

Token-based HTTP Basic

One way to solve the problem involves using HTTP Basic with tokens.

Let's consider the following roles:

• TM = Tasking Manager
• TM Admin = the person who administrates TM
• App = the 3rd-party web application based on the TM API
• App Admin = the person who administrates App

This is the workflow:

1. App Admin creates an OSM user for App
2. App Admin logs into TM using that OSM user
3. App Admin goes to a specific TM web page to get a token for OSM user
4. App Admin configures App to use OSM user + token as HTTP Basic credentials

Note: for security reasons the token created by App Admin will be visible once and only once on the screen. This is also how GitHub does it for Personal access tokens.

Implementation details

Tasking Manager already uses an AuthTktAuthenticationPolicy. This is to be able to "remember" and "forget" the user identity. For the API a BasicAuthAuthenticationPolicy should also be used. To be able to use two authentication policies the pyramid_multiauth package will be used. This package provides an authentication policy that proxies to a stack of authentication policies.

Restrictions

In order to avoid massive unintentional modifications on the Tasking Manager data, the following restrictions could be added for API users:

• Project creation or update should be managed in the Tasking Manager only. The API wouldn't expose any way to create or modify a project. Project creation seems to be too specific to be proposed in an API.
• When using the API (token based authentication), updates on tasks including task creation would be limited to a given list of projects (not all).

To restrict the list of projects on which a 3rd-party application have the rights to modify tasks, the idea is to associate a project to a list of project managers. As a bonus, this list of project managers for a project could be exposed to contributors, and would help users to know who they can contact or refer to in case of questions or problems.

Final notes

One advantage of using HTTP Basic is simplicity. The main disadvantage is that the username and password (the token in our case) are sent in clear with every request. Given the nature of Tasking Manager using HTTP Basic is acceptable. In the future other authentication scheme like Hawk can be considered.