Feature: integrate Hanko auth login by andrea-chirillano · Pull Request #538 · hotosm/osm-export-tool

andrea-chirillano · 2026-03-26T23:46:45Z

This pull request requires in-depth review before merging.

This PR includes changes to the backend (Django), frontend (React/JS), infrastructure (Docker, nginx), and tests. Review carefully before approving.

Add Hanko SSO Authentication

Integrates Hanko SSO as an alternative to legacy OSM OAuth, enabling single sign-on across the HOT ecosystem via login.hotosm.org.

Key changes

New AUTH_PROVIDER setting (legacy | hanko) — default is legacy, existing deployments are unaffected
HankoAuthentication DRF backend added to DEFAULT_AUTHENTICATION_CLASSES (takes priority, falls back to token/OAuth2)
Onboarding flow to link existing OSM accounts or create new ones for first-time Hanko users
hotosm-auth web component (<hotosm-auth>) rendered in NavBar via HankoAuthButton.js
<hotosm/tool-menu> web component added to the layout (loaded from jsDelivr, fixed version)
Django upgraded from 3.2 → 4.2 LTS (required by hotosm-auth[django])
print() calls replaced with logging throughout api/views.py
Responsive navbar collapse added (mobile support)
Admin authorization now supports both modes: is_superuser (legacy) and ADMIN_EMAILS env var (Hanko)

New API Endpoints

Endpoint	Method	Description
`/api/auth/me/`	GET	Current user info
`/api/v1/auth/status/`	GET	Auth status + onboarding flag
`/api/v1/auth/onboarding/`	GET	Callback from login service after OSM link
`/api/admin/`	—	Hanko→Django user mapping (admin panel)
`/api/v1/`	—	Hanko OSM OAuth routes (from `hotosm_auth_django`)

Legacy OAuth routes (/osm/, /o/, /authorized) are only registered when AUTH_PROVIDER=legacy.

New Dependencies

Package	Location	Notes
`hotosm-auth[django]==0.2.12`	Backend (PyPI)	Hanko middleware, helpers, OSM views
`tzdata`	Backend (PyPI)	Required on minimal images (Python 3.9+)
`@hotosm/hanko-auth@0.5.2`	Frontend (jsDelivr CDN)	Login web component
`@hotosm/tool-menu@0.2.6`	Frontend (jsDelivr CDN)	HOT ecosystem nav menu

Required Environment Variables

Backend — required (Hanko mode)

Variable	Required	Example	Description
`AUTH_PROVIDER`	Yes	`hanko`	Set to `hanko` to enable SSO. Default: `legacy`
`HANKO_API_URL`	Yes (Hanko)	`https://login.hotosm.org`	Hanko service URL (server-to-server)
`COOKIE_SECRET`	Yes (Hanko)	`<shared-secret>`	32+ bytes. Must match the login service and other apps — coordinate with login team

Backend — recommended

Variable	Default	Description
`HANKO_PUBLIC_URL`	same as `HANKO_API_URL`	Public URL the browser sees / used for the login-service redirect
`COOKIE_DOMAIN`	inferred	Cookie domain — use `.hotosm.org` for cross-subdomain SSO
`COOKIE_SECURE`	`not DEBUG`	`true` in production
`ADMIN_EMAILS`	`""`	Comma-separated list; grants `is_superuser` in Hanko mode
`RAW_DATA_API_PUBLIC_URL`	falls back to `RAW_DATA_API_URL`	Public Raw Data API URL for frontend

Backend — optional (OSM connection & JWT)

These are read directly from the environment by the hotosm-auth library.

Variable	Default	Description
`OSM_CLIENT_ID` / `OSM_CLIENT_SECRET`	unset	Enable starting the OSM OAuth flow from the export-tool itself (`/api/v1/auth/osm/login/`). If unset, onboarding redirects users to the login service to connect OSM
`OSM_REDIRECT_URI`	unset	OSM OAuth callback URL when OSM is enabled locally
`JWT_AUDIENCE`	`None`	Optional validation of the JWT `aud` claim
`JWT_ISSUER`	inferred from `HANKO_API_URL`	JWT issuer; set explicitly if Hanko runs behind a proxy
`COOKIE_SAMESITE`	`lax`	SameSite policy for the auth cookie

Frontend (injected via Django template into `window.*`)

Variable	Required	Description
`AUTH_PROVIDER`	Yes	Must match backend
`HANKO_URL`	Yes (Hanko)	Hanko public URL — passed as `hanko-url` to `<hotosm-auth>`

Database Migrations

When AUTH_PROVIDER=hanko, the hotosm_auth_django app is added to INSTALLED_APPS and contributes one migration (0001_initial):

Creates the hanko_user_mappings table (maps Hanko user IDs ↔ Django user IDs, scoped by app_name)
Uses CREATE TABLE IF NOT EXISTS — idempotent, safe to re-run
Run with: python manage.py migrate (or python manage.py migrate hotosm_auth_django)

No migrations are added to the export-tool's own apps (api, jobs, tasks, ui). Rolling back to AUTH_PROVIDER=legacy needs no reverse migration — the table is harmless if left in place. Explicit rollback: python manage.py migrate hotosm_auth_django zero.

How It Works

Legacy mode (default)

AUTH_PROVIDER=legacy — no changes, continues using OSM OAuth with access-token header.

Hanko mode

User clicks login → redirected to login.hotosm.org
Hanko sets a JWT cookie after authentication
HankoAuthentication DRF backend validates the JWT cookie via hotosm_auth_django
If a Django↔Hanko mapping exists → user is authenticated
If no mapping → GET /api/v1/auth/status/ returns needs_onboarding: true → onboarding flow starts
Onboarding: user chooses to link an existing OSM account (recovers data) or create a new one

Onboarding account matching

For "I already have an account", existing users are matched by priority:

OSM ID — via social_auth_usersocialauth (find_legacy_user_by_osm_id)
Email — Hanko email vs auth_user.email (find_legacy_user_by_email, lowest id wins)

If neither matches, the user is redirected back to the login service with an error and no DB rows are created.

Test Plan

Backward Compatibility

Default is legacy — no action required for existing deployments
Existing OSM OAuth users continue working unchanged
Switch to hanko when ready by setting the environment variables above

Deployment

The deploy is done manually via SSH. There is no automated pipeline — after the PR is merged, someone with server access must connect and deploy by hand.

Dependency & Django Version Update

Django has been upgraded from 3.2 → 4.2 LTS and several dependencies have been
updated to their latest compatible versions. These changes are required for two reasons:

Unit tests: the updated test suite relies on APIs and behaviors introduced in
Django 4.2. Running tests against Django 3.2 will result in failures.
Security: Django 3.2 no longer receives security
patches. Upgrading to the 4.2 LTS branch ensures continued security support.

Collateral Fixes (not Hanko, but required)

A few changes in this PR are not part of the SSO feature itself, but were necessary to make the branch run, build under Docker, or pass tests. Listed here so reviewers aren't surprised by non-Hanko diffs:

Change	File(s)	Why it was needed
Removed `userinfo=` from `Galaxy(...)` calls	`tasks/task_runners.py`	The pinned `osm-export-tool-python==2.0.10` does not accept a `userinfo` argument — `main` raises `TypeError` on every export run
`or` → `and` in the `last_run_status` guard	`tasks/task_runners.py`	The original `!= "SUBMITTED" or != "RUNNING"` is always `True`, so a new run was created even when one was already `SUBMITTED`/`RUNNING`, allowing duplicate parallel runs. The matching `else` branch was unreachable dead code
Redis host/port read from env vars	`tasks/task_runners.py`, `core/settings/project.py`	Redis was hardcoded to `localhost`; in a containerized setup it runs in a separate container. Defaults to `localhost`, so non-Docker setups are unaffected
`FeatureSelection.example()` → `SIMPLE_FEATURE_SELECTION` constant	`conftest.py` (new) + `api/tests/test_views.py`, `jobs/tests/test_models.py`, `tasks/tests/test_models.py`	The import `from feature_selection.feature_selection import FeatureSelection` raises `ModuleNotFoundError` — the affected test files in `main` cannot even be collected
Added `[tool:pytest]` config	`setup.cfg`	Sets `DJANGO_SETTINGS_MODULE` so the test suite can be run with `pytest`

…xport-tool into feature/login-hanko

emi420

Hi @andrea-chirillano ! I did my review before moving the PR to "Ready to review" so it's easier for other people to review it.

Thanks!

emi420 · 2026-03-31T07:14:09Z

Hi @andrea-chirillano ! please remove this file, the branch feature/login_hanko will be deleted once merged so this file will not be used after that.

Hi, the branch is necessary because that branch depends on the staging environment https://export.testlogin.hotosm.org/v3/

emi420 · 2026-03-31T12:28:43Z


        if not all:
            queryset = queryset.filter(Q(user_id=user.id))
-


Why this change? it adds additional filters, could we revert it?

I also realized they were unnecessary, and I've already reverted those changes.

emi420 · 2026-03-31T14:18:03Z

Please remove this file, it's only for testing on export.testlogin.hotosm.org and will not be used after the PR

I added it to gitignore

emi420 · 2026-03-31T14:18:48Z

This file is for development right? if that's the case, please add a comment about it and move it to a docker folder

I added it to gitignore and move that Dockerfile into a docker folder.

…xport-tool into feature/login-hanko

…login_hanko

spwoodcock · 2026-04-10T20:25:59Z

Thanks - I just saw this PR from the message on slack!

I have no idea how Export Tool is deployed in production, nor how we can test this PR for now, but once it's marked as ready for review, I can look into those things with dk 😄

kshitijrajsharma · 2026-04-10T20:32:32Z

Thanks - I just saw this PR from the message on slack!

I have no idea how Export Tool is deployed in production, nor how we can test this PR for now, but once it's marked as ready for review, I can look into those things with dk 😄

its in a single ec2 instance in our aws ! Ideally we can swamp a quick stage server for export tool in a tiny instance ! I am happy to review once PR is ready !

spwoodcock · 2026-04-10T21:14:00Z

Is it a systemd service or something, running the Python / Django server? I can't see any containerisation in the repo

spwoodcock · 2026-04-10T21:15:04Z

Ah I literally just saw this dir!

https://github.com/hotosm/osm-export-tool/tree/main/ops/systemd

Assuming a few services all run in parallel, managed by systemd

emi420 · 2026-04-10T21:22:52Z

We have a testing deployment:

https://export.testlogin.hotosm.org/

kshitijrajsharma · 2026-04-10T21:31:13Z

Yes systemd services, export tool isn't containerized yet ! Yarn builds the frontend !

andrea-chirillano and others added 9 commits January 27, 2026 02:17

Add: dockerfile

29f7e4f

Add: Login flow with Hanko

2635e8f

Merge branch 'main' into feature/login-hanko

c72ead9

Restore logs and comments

3d64cac

Merge branch 'feature/login-hanko' of https://github.com/hotosm/osm-e…

f34ebba

…xport-tool into feature/login-hanko

Restore files that are not related to hanko

e24e6b4

Fix: badly parsed code

3b5097d

Add: middleware for decorators

76978dd

keep INSTALLED_APPS as a tuple

974f72e

emi420 marked this pull request as draft March 27, 2026 17:02

andrea-chirillano temporarily deployed to testlogin March 27, 2026 17:28 — with GitHub Actions Inactive

andrea-chirillano added 3 commits March 27, 2026 18:13

Add: variable SELECTION_FEATURE_SIMPLE

2b344c6

Remove: tabs in files

4833270

Change staging environment path

a68c070

andrea-chirillano temporarily deployed to testlogin March 30, 2026 14:07 — with GitHub Actions Inactive

hg1g temporarily deployed to testlogin March 30, 2026 16:53 — with GitHub Actions Inactive

emi420 requested changes Mar 31, 2026

View reviewed changes

andrea-chirillano added 3 commits March 31, 2026 22:14

Fix: unit test with legacy account

7456a53

Fix: clean up auth imports, decorators, and dev files per PR review

4cd21ab

Deploy

c3b9db8

andrea-chirillano had a problem deploying to testlogin March 31, 2026 23:38 — with GitHub Actions Failure

Add: nginx into the docker folder

5901810

andrea-chirillano temporarily deployed to testlogin April 1, 2026 13:27 — with GitHub Actions Inactive

hg1g and others added 7 commits April 1, 2026 17:47

Fix URLs: remove https:// prefix from hostnames

6391625

Add traefik.docker.network label to fix routing

62a2936

Fix: files to delete and functions to modify

f8b02f8

Fix: variables removed

e28375f

Delete core/settings/docker.py

564c637

remove unnecessary lines of code

8730994

Merge branch 'feature/login-hanko' of https://github.com/hotosm/osm-e…

e1b7c4f

…xport-tool into feature/login-hanko

andrea-chirillano added 2 commits April 6, 2026 16:01

Deploy

ac0eb99

Deploy

bbcbf0a

emi420 mentioned this pull request Apr 6, 2026

Shared authentication with hotosm/hanko-auth #539

Open

hg1g and others added 5 commits April 6, 2026 15:44

Merge branch 'login_hanko' of github.com:hotosm/osm-export-tool into …

62f5b5b

…login_hanko

Fix: export button

ffe260d

Replace auth decorators with hotosm_auth_django.login_required

c75bed3

Remove: redudant conditionally for css rule

356e788

Merge branch 'login_hanko' of github.com:hotosm/osm-export-tool into …

e4d32d1

…login_hanko

spwoodcock self-requested a review April 10, 2026 20:24

hg1g added 2 commits May 15, 2026 12:18

Bump auth-libs and clean up Hanko code

d57799a

Restore non-Hanko changes in views.py and Summary.js

08d676e

hg1g marked this pull request as ready for review May 15, 2026 18:08

Uh oh!

Conversation

andrea-chirillano commented Mar 26, 2026 • edited by hg1g Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This pull request requires in-depth review before merging.

Add Hanko SSO Authentication

Key changes

New API Endpoints

New Dependencies

Required Environment Variables

Backend — required (Hanko mode)

Backend — recommended

Backend — optional (OSM connection & JWT)

Frontend (injected via Django template into window.*)

Database Migrations

How It Works

Legacy mode (default)

Hanko mode

Onboarding account matching

Test Plan

Backward Compatibility

Deployment

Dependency & Django Version Update

Collateral Fixes (not Hanko, but required)

Uh oh!

emi420 left a comment

Choose a reason for hiding this comment

Uh oh!

emi420 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

andrea-chirillano Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

emi420 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

andrea-chirillano Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

emi420 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

andrea-chirillano Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

emi420 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

andrea-chirillano Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

spwoodcock commented Apr 10, 2026

Uh oh!

kshitijrajsharma commented Apr 10, 2026

Uh oh!

spwoodcock commented Apr 10, 2026

Uh oh!

spwoodcock commented Apr 10, 2026

Uh oh!

emi420 commented Apr 10, 2026

Uh oh!

kshitijrajsharma commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

andrea-chirillano commented Mar 26, 2026 •

edited by hg1g

Loading

Frontend (injected via Django template into `window.*`)

andrea-chirillano Mar 31, 2026 •

edited

Loading

kshitijrajsharma commented Apr 10, 2026 •

edited

Loading