Handle API keys

[spwoodcock]

• OAM has the requirement for API key / token based auth.
• It makes sense to have the tokens be per app, stored in the app database (a user record linked to the HOT Login unique global user ID).
• My hunch is that to facilitate API token login, we handle this on the backend of the app, as an either/or @login_required decorator or @api_token decorator.
• The router will take the request and check if the authentication is valid for either HOT login, or via the API token validation flow. If either succeeds, the user is authenticated, if not block access.
• I just wanted to run this by @hg1g and @emi420 who have been leading the implementation of this, to ensure it's a sane approach / fits in with what is done so far 🙏

[emi420]

It make sense to manage API keys also inside login, we could have read-only or create permissions.

We'll come back to this issue in the future.

[spwoodcock]

Copying thread from slack for context on what we will do:

---

Hernán[12:38 PM]
hey everyone! since we moved to Hanko we only have session cookies, which don't work for cURL/scripts.

here's what I'd propose:

Handle API tokens in one place, the login profile page, instead of each project rolling its own.

  - Login backend stores one non-expiring token per user, with endpoints to generate/regenerate it behind the Hanko session.
  - auth-libs accepts both Authorization: Bearer and the Hanko cookie, so every project gets API auth just by bumping the lib.
  - Profile page gets a new "API Access Token" section: generate, regenerate, copy. Shown once on creation. Account deletion already lives there.
  - fAIr/drone-tm/etc drop their local token screen and point to login.hotosm.org/profile?return_to=.

that way we manage the token in one place, regenerating kills it everywhere at once, and we don't duplicate auth code across apps.

let me know what you think!

---

Emi  [12:41 PM]
It would be better to have a single token for accessing everything or to select which apps are accessible with the token? it would be a single token or the user would be able to generate more than one? (we can add permissions in the future, like read, write)

---

Kshitij  [1:10 PM]
yes token and the application role would be ideal !

---

Kshitij  [1:10 PM]
I had it implemented before on fAIr now with the hanko this part is broken !

---

Kshitij  [1:11 PM]
you’re doing that in fAIr currently or how are you managing account deletion?I setup an email to admins so we would delete it manually once we receive the request of deletion , it is mainly to follow the GDPR !  this part is broken too , i guess its the same for all across the tool we have we need to figure out account deletion and access token !

---

Emi  [1:16 PM]
I think we can add both things to the login app directly, so we have them available for all tools. We are going to discuss this on our weekly meeting today, to see if it’s possible to have it ready for this week. (edited) 

---

Kshitij  [1:18 PM]
thanks Emi

---

Hernán Gigena  [1:24 PM]
you mean App scope ("works in fAIr, not drone-tm"), don't you?

---

Emi  [1:26 PM]
yes

---

Sam[1:55 PM]
My immediate though was 'one non-expiring token valid for all of our apps - crazy!', but on reflection of what our threat model is in reality, I think it could be acceptable.

The main risks of a token leaking are:

Deletion of data that the user owns (especially if this is made convenient via portal)
Impersonation of a user for uploads / edits - not a big incentive for this tbh.

We don't have as much risk with the centralised auth cookie, as it's browser scoped and expires.

This all said, do we really gain much by having a single token with the potential to scope for everything vs having one token per app, all managed via Portal?

---

Sam[1:56 PM]
If we had a decent UI for managing tokens (and revoking / expiring them), could we just generate one per app? I doubt a user is going to automate an entire e2e via command line
Sam Woodcock  [1:57 PM]
is it ok with everyone if I copy this thread to github too?

---

Emi  [1:59 PM]
Yep! that would be the solution, one token per app, currently we need it for fAIr so we can go to production preserving existing functionality but then it will be useful for other apps too. The plan is to add permissions in the future, so the token can be read-only for example.

---

Kshitij  [2:01 PM]
yes i think 3 of our apps use token atm , fAIr , tasking manager and OAM

---

Hernán [2:19 PM]
API tokens in the login app — summary

Model: one non-expiring token per (user, app). A user can have one token for fAIr, one for drone-tm, one for OAM, etc. If a token leaks, only that single app is exposed. Leaves the door
  open to add per-token permissions (read-only, etc.) later without breaking anything.

Login portal:
  - Stores the tokens and exposes endpoints to list, generate/regenerate and revoke them, all behind the existing Hanko session.
  - New "API Access Tokens" section on the profile page, one row per app with Generate / Regenerate / Revoke buttons. The plaintext token is shown only once, right after creation.
  - Account deletion already lives on the same page and cleans up every token automatically.

Shared auth library:
  - Extended to accept these tokens in the Authorization: Bearer header, in addition to the current Hanko session cookie.
  - Each project declares which app it is, so a token bound to fAIr only works against fAIr.
  - Projects get token support for free just by bumping the library.

Consumer apps (fAIr, drone-tm, OAM):
  - Day 1: bump the library. That's it, their APIs immediately accept the new tokens.
  - Replace each app's local token UI with a button that redirects users to the login portal to manage their tokens.

Verification:
  - generate a fAIr token, call fAIr with it (works), call drone-tm with it (rejected), generate a drone-tm token, both work independently, revoke one, the other keeps working,
  - delete the account and both disappear.

---

Sam [2:43 PM]
This sounds perfect - one small thing I just thought of though:

We are going to great efforts to make our apps compatible with both (1) HOT unified login (2) standalone login (with bundled hanko instance).
If we centralise the API key logic to the login service, then to implement API keys on a standalone tool (without HOT login) this would become more difficult.
We would have the implement the API key logic manually in each app that requires it.

Honestly, for the improvement in UX we get from a unified portal management, I think it's still a positive.
We could just have users of standalone instances deal with the fact they can't use API keys - is that an ok tradeoff? (edited)

---

Emi  [2:47 PM]
HOT Login is also free and open source software, so standalone instances could also implement it right?

---

Sam[2:47 PM]
True true

---

Kshitij  [2:47 PM]
I am more leaning towards a siimple implementation having a single api key with scope defined !

---

Kshitij  [2:48 PM]
here scope would mean applications

---

Kshitij  [2:48 PM]
so same key would work for multiple apps if preferred and configured in the profile

---

Kshitij  [2:48 PM]
that would reduce so much complexity

---

Sam [2:49 PM]
For someone to only run say DroneTM, it's a bit more complex to run the login service too - not ideal. But it's currently only fAIr, TM, OAM with API keys, so we can live with this I guess.

Complexity for the dev or for the user @Kshitij?

---

Sam [2:49 PM]
I think it makes it slightly simpler for the user, at the expense of additional risk (leaking a token that is scoped for all apps)

---

Kshitij  [2:49 PM]
for the user ! I mean

---

Kshitij  [2:50 PM]
yes i was thining like how pypi handles it

---

Sam Woodcock  [2:50 PM]
I don't think you can scope for multiple packages though right?

---

Emi  [2:50 PM]
we could have both, each token could be associated to one or more apps, so we keep it simple but enable more complex scenarios

---

Sam [2:50 PM]
We can have API key generation generic, but then add scopes for which app it links to - only one app per token? (the pypi approach, unless I'm mistaken) (edited) 

---

Sam [2:51 PM]
If I were a user I would be temped to just have one main api key for all apps, if that were possible

---

Kshitij  [2:52 PM]
mee too , pypi gives both the option , one token for all
token per app

---

Sam Woodcock  [2:52 PM]
Oh yes I guess it does!

---

Kshitij  [2:52 PM]
I use one token for all one !

---

Emi  [2:53 PM]
ok so in login UI the user will be able to create different tokens and assign one or more apps to each of them

---

Emi  [2:53 PM]
currently this is for user, in the future it could be for organizations

---

Kshitij  [2:54 PM]
something like this
image.png

---

Sam [2:54 PM]
If we allow a token scoped to all apps, should we just make our lives simpler and only allow that?
The simplest UX would be: "generate API token for HOT apps"

---

Sam [2:54 PM]
One token to manage per user

---

Emi  [2:54 PM]
ok so there will be 2 options 1) single app 2) all apps

---

Sam [2:54 PM]
(I'm not thrilled with that approach for the security, but mentioned above our threat level is low). It's the simplest for the users

---

Emi  [2:55 PM]
for for security reasons it will be good to have the possibility of enabling access to a single app and not the others

---

Emi  [2:56 PM]
I’m not sure if the threat level is that low, there are situations where risk is high and data must be protected, with the user deciding when to share what (edited) 

---

Sam [2:56 PM]
But that's exactly my point for why we shouldn't allow tokens scoped to all apps. pypi is a single platform. We are managing 6+ platforms via a single API key

---

Sam [2:56 PM]
I don't know another service on the internet that allows that

If we are favouring security: one per app.
If we prefer UX to rule out: one for all apps.

I don't think it's worth adding logic to handle a hybrid approach, when I'm sure if a single api key is an option, people will just choose that

(just my opinion!)

If you both think a having a hybrid is the best, let's go for that 👍 See what Hernan thinks too

---

Kshitij  [2:59 PM]
yeah security wise shared login system gonna be threat for sure , if there is a security vulnerabilities in the shared auth all of the system would be affected ! hybrid sounds good enough for me one can only set keys per app if they are concerned

---

Emi  [2:59 PM]
Generating and using a token is not for the common user but for someone with basic tech knowledge who for some reason needs the token (ex: uploading imagery to Open Aerial Map from OpenDroneMap). I would go for one token per app, it would be more secure and it will preserve current functionality

---

Emi  [3:00 PM]
and it will be technically possibly to enable access to all apps anyway, by generating one token per app

---

Kshitij  [3:01 PM]
aah thats right the token is for techie kind of user base (edited) 

---

Emi  [3:01 PM]
then we can add permissions per app, like read/write

---

Kshitij  [3:01 PM]
1 app 1 token seems good then !

---

Hernán Gigena  [3:02 PM]
the read/write feat could be implemented in a second version

---

Emi  [3:02 PM]
yep

---

Sam Woodcock  [3:02 PM]
Yes I agree 😃

---

Hernán Gigena  [3:02 PM]
ok, so 1 app, 1 token