API Tokens proposal

[barreiro]

Motivation

The Machine Accounts feature was released on Horreum 0.14 as a step to allow for the usage of custom OIDC providers for authentication purposes, while providing an alternative mechanism. However, there are drawbacks to this approach. One being that these are accounts that are, by design, scoped to a single team. They use HTTP basic authentication that, although not considered insecure, it's not one of the best practices of the industry.

Also, the current token mechanism in Horreum (and the @WithToken annotation) bypasses many security checks and should be replaced by a more robust solution, but that will still continue to allow access to Test for reporting purposes.

The desired outcome is to have some kind of authentication mechanism (defined in this proposal as the API Token), that is associated with user account and allows authentication on behalf of the user.

Format

API Token format is to be defined but can be JWT, UUID, unique String, etc. The strategy currently used to generate random passwords for the bootstrap account and machine accounts can be reused.

Client

Currently the client authenticate with username and password provider by the user. These can be used to obtain a Bearer token from Keycloak or another OIDC provider, and if that is not successful, perform Basic authentication.

With this proposal a new alternative can be used. The user supplies the API Token that is what is sent to the server.

Sever authentication customization

The server should be prepared to accept the new credential type, as described in Quarkus security customization guide. The exact format is to be defined, but can be either a custom HTTP header (like X-Horreum-API-Token: ...) or a custom HTTP authetication scheme (Authenticate: Horreum-API ...).

The API Token should then be used to look up the user it corresponds to in the database, and with that info SecurityIdentity.

In case the provided API Token is not found, the server should reply with a 401 Unauthorized response.

Database schema changes

The current token table should be removed and a new table userinfo_token should be created to map a user to its tokens. This new table will have, at least, a column for each (unique) token, a foreign key to userinfo, a revoked flag and a description to be displayed in the ui.

If further restrictions to the usage of the API Token are to be applied, like for example an expiration date or scoping to single or multiple teams or tests, they should be stored in this table as well.

API Tokens shall not be removed from the DB to prevent reuse.

User Interface

There should be a new tab in the user panel, similar to the one now used for machine accounts, where the API Tokens for the logged in user are displayed. In this panel a user should be able to create new API Tokens or revoke existing ones.

In case there are restrictions associated with the API Token, these should be defined at token creation. The characteristics of the API Token should remain immutable and can only be revoked.

It's an open question if administrators can revoke API tokens in behalf of a user. In that case a new tab in the administrator panel needs to be added as well.

Token service

A new service for the user to manage its API tokens should be created with at least three basic operations:

• List exiting active tokens
• Create new token
• Revoke an exiting token

Further improvements

Implement a mandatory expiration data, like suggested before, and use the existing alerting service to notify the user when the API Token is about to expire.

[lampajr]

Hi, this sounds like a great improvement and AFAIK exposing an API token for development purposes (which is the case) is the best practice.. I am thinking for instance at the Twitter, Facebook or Google APIs where you need to get a Developer Token to interact with the API itself.

A couple of comments:

The API Token ...

With regard the name, we could also consider using "Developer token" as an alternative to the "API token", this seems a widely used name for such purposes. On the other hand I do not have a strong opinion on this either names are fine by me.

It's an open question if administrators can revoke API tokens in behalf of a user. In that case a new tab in the administrator panel needs to be added as well.

IMO, as long as the generated token is at user level, I wouldn't consider this case. Therefore, only the user itself can revoke its own tokens. Anyway if we decide to this, it can be added at later step as I don't see any specific requirement to decide this at early stage.

A new service for the user to manage its API tokens should be created with at least three basic operations:

• List exiting active tokens

What do you mean by this "List existing active tokens"? Do you mean that the user can see the actual token some time in the future? or get the created token ids and corresponding names (in the db) such that the user can revoke them?
I am asking this because, if we follow the best practices, I think the token should be ONLY visible during the creation of the token itself nd if lost the user can revoke and re-create a new one. This way we never pass the token back to the UI making its management a lot more secure.

Implement a mandatory expiration data, like suggested before, and use the existing alerting service to notify the user when the API Token is about to expire.

I think this would be a great feature which improves the token security ensuring proper token rotation.

[barreiro]

thanks for your comments @lampajr.

what about Authentication Token or (Horreum) Access Token ?? ... I don't think Developer Token is not the most appropriate name either.

What do you mean by this "List existing active tokens"? Do you mean that the user can see the actual token some time in the future? or get the created token ids and corresponding names (in the db) such that the user can revoke them?

it was not clear, but I meant the former. similar to what currently exists for the machine accounts where the password is displayed only once, on creation.

[lampajr]

what about Authentication Token or (Horreum) Access Token ?? ... I don't think Developer Token is not the most appropriate name either.

yeah, I don't have strong opinion on the name I would just use a name users are already used to

it was not clear, but I meant the former. similar to what currently exists for the machine accounts where the password is displayed only once, on creation.

Awesome, we are on the same page thx!