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.10`	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

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
`HANKO_PUBLIC_URL`	No	same as above	Public URL (defaults to `HANKO_API_URL`)
`COOKIE_SECRET`	Yes (Hanko)	`<shared-secret>`	Must match the login service — coordinate with login team
`COOKIE_DOMAIN`	Yes (Hanko)	`.hotosm.org`	Cookie domain — use `.hotosm.org` for cross-subdomain SSO
`COOKIE_SECURE`	No	`true`	Defaults to `not DEBUG`
`ADMIN_EMAILS`	No	`admin@hotosm.org`	Comma-separated list; replaces `is_superuser` in Hanko mode
`RAW_DATA_API_PUBLIC_URL`	No	`https://api.rawdata.hotosm.org`	Public URL for frontend (falls back to `RAW_DATA_API_URL`)

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>`

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

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 has no longer receives security
patches. Upgrading to the 4.2 LTS branch ensures continued security support
through April 2026.

…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

.github/workflows/deploy-login-hanko.yml

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/

api/tests/test_hanko_auth.py

api/views.py

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

api/views.py


        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.

api/views.py

ui/views.py

Makefile

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

nginx.conf

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

docker/Dockerfile.dev

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

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

andrea-chirillano and others added 7 commits April 6, 2026 13:17

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

Deploy

ac0eb99

Deploy

bbcbf0a

emi420 mentioned this pull request Apr 6, 2026

Shared authentication with hotosm/hanko-auth #539

Open

andrea-chirillano added 3 commits April 6, 2026 20:50

Fix: export button

ffe260d

Replace auth decorators with hotosm_auth_django.login_required

c75bed3

Remove: redudant conditionally for css rule

356e788

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

Conversation

andrea-chirillano commented Mar 26, 2026 • edited 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

Frontend (injected via Django template into window.*)

How It Works

Legacy mode (default)

Hanko mode

Test Plan

Backward Compatibility

Deployment

Dependency & Django Version Update

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

Loading

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

andrea-chirillano Mar 31, 2026 •

edited

Loading

kshitijrajsharma commented Apr 10, 2026 •

edited

Loading