Add Hanko SSO Authentication by hg1g · Pull Request #492 · hotosm/fAIr

hg1g · 2026-03-12T23:14:23Z

Add Hanko SSO Authentication

Summary

Integrates Hanko SSO authentication 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 to switch between legacy (current) and hanko modes
Hanko auth uses JWT cookies instead of access-token headers
User onboarding flow to link existing accounts or create new ones
Shared auth-libs web component for login UI

This PR is functionality only. Deploy configuration (Dockerfiles, workflows, nginx) comes in a separate PR.

For Deployment: Required Secrets & Variables

Backend Environment Variables

When deploying with AUTH_PROVIDER=hanko:

Variable	Required	Example	Description
`AUTH_PROVIDER`	Yes	`hanko`	Set to `hanko` to enable SSO
`HANKO_API_URL`	Yes	`https://login.hotosm.org`	Hanko service URL
`COOKIE_SECRET`	Yes	`<shared-secret>`	Must match login service - for cookie encryption
`COOKIE_DOMAIN`	Yes	`.hotosm.org`	Domain for auth cookies
`LOGIN_URL`	No	`https://login.hotosm.org`	Login service URL for redirects
`FRONTEND_URL`	Yes	`https://fair.hotosm.org`	Frontend URL for redirects

Frontend Environment Variables

Variable	Required	Example	Description
`VITE_AUTH_PROVIDER`	Yes	`hanko`	Must match backend
`VITE_HANKO_URL`	Yes	`https://login.hotosm.org`	Hanko service URL

Important Notes

COOKIE_SECRET must be shared with the login service (login.hotosm.org) - coordinate with login team
COOKIE_DOMAIN should be .hotosm.org for production so cookies work across subdomains
Default is legacy mode - existing deployments continue working without changes
Run migrations after setting env vars - the hotosm_auth_django app (with migrations) only loads when AUTH_PROVIDER=hanko

New Dependencies

Package	Location	Notes
`hotosm-auth[django]==0.2.10`	Backend (PyPI)	Hanko auth middleware & helpers
`@hotosm/hanko-auth`	Frontend (npm)	Login web component

New API Endpoints

Endpoint	Method	Description
`/api/v1/auth/onboarding/`	GET	Callback from login service after onboarding
`/api/v1/auth/status/`	GET	Check authentication status

How it Works

Legacy Mode (default)

AUTH_PROVIDER=legacy

No changes - continues using OSM OAuth with access-token header.

Hanko Mode

AUTH_PROVIDER=hanko

User clicks login → redirected to login.hotosm.org
Hanko sets JWT cookie after authentication
Backend middleware validates JWT cookie
If user mapping exists → authenticated
If no mapping → user goes through onboarding

Onboarding Flow

New Hanko users choose:

"I had an account" → Connect OSM to recover existing fAIr data
"I'm new" → Create fresh account with synthetic ID

Test Plan

Legacy auth continues working (AUTH_PROVIDER=legacy)
Hanko login/logout flow works
New user onboarding creates account
Existing user onboarding recovers data
Navbar shows correct user state
Protected routes redirect to login correctly
?mine=true filter works for both auth types

Backward Compatibility

Default is legacy - no action needed for existing deployments
Existing users continue working with OSM OAuth
Can switch to hanko when ready by setting environment variables

Auth functionality only, deploy config in separate PR.

omranlm

@jeafreezy can you pelase review all frontend changes and make sure all clear .. feel free to add comments on specific code lines and tag the submitters for clarification. @emi420 is also HOT team member and has been coordinating those efforts

@kshitijrajsharma and the back end review for you please

jeafreezy · 2026-03-27T15:28:03Z

@jeafreezy can you pelase review all frontend changes and make sure all clear .. feel free to add comments on specific code lines and tag the submitters for clarification. @emi420 is also HOT team member and has been coordinating those efforts

@kshitijrajsharma and the back end review for you please

Got it.

I actually had a first review last week and It looks very great to me. I’d give it a second look over the weekend.

kshitijrajsharma · 2026-03-27T16:42:30Z

backend/fairproject/settings.py

+# Authentication: "legacy" (OSM OAuth) or "hanko" (Hanko SSO)
+AUTH_PROVIDER = env("AUTH_PROVIDER", default="legacy")
+
+if AUTH_PROVIDER == "hanko":


better to use type safety and the options specially when its string ! or make accepted values constant

good point, I'll add AuthProvider constants in settings.py

kshitijrajsharma · 2026-03-27T16:44:52Z

backend/fairproject/urls.py

 )

+admin_mapping_patterns = []
+if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':


Auth provider should be compulsory ! It should be provided legacy by default yes but assume value needs to be there so getattr is not needed

makes sense, I'll simplify to settings.AUTH_PROVIDER without getattr

kshitijrajsharma · 2026-03-27T16:45:36Z

backend/fairproject/urls.py

+            user_name_column="username",
+            user_email_column="email",
+        )
+    except ImportError:


if the authprovider is hanko it should not pass when package not found ! hotosmauth_django needs to be installed !

good catch, removed the try/except so it fails if package is missing

kshitijrajsharma · 2026-03-27T16:46:10Z

backend/fairproject/urls.py

    path("api/v1/auth/", include("login.urls")),
    path("api/v1/", include("core.urls")),
-    path("api/admin/", admin.site.urls),
+    path("api/admin/", include(admin_mapping_patterns)),


why ? what is api admin mapping patterns ?

these are admin endpoints from hotosm-auth for managing hanko-to-OSM user mappings. The login repo has an admin dashboard that communicates with these endpoints in all apps (fAIr, portal, drone-tm, etc.) to view/delete mappings. The mappings live in each app's DB, not in login.

kshitijrajsharma · 2026-03-27T16:47:06Z

backend/login/authentication.py

                raise exceptions.AuthenticationFailed(
                    "OSM authentication failed: Invalid or expired access token"
                )
-        return (user, None)  # authentication successful return id,user_name,img


no need to remove the inline comments ?

kshitijrajsharma · 2026-03-27T16:47:53Z

backend/login/authentication.py

+        from hotosm_auth_django import get_mapped_user_id
+
+        if not hasattr(request, 'hotosm'):
+            logger.debug("No hotosm attribute on request - HankoAuthMiddleware not active")


is it possible for this class to be instantiated when hanko is not enabled ? if no then this check should be explicit !

you're right, HankoAuthentication only runs when Hanko is enabled so the middleware must be there. Changed to raise an explicit error!

kshitijrajsharma · 2026-03-27T16:48:39Z

backend/login/authentication.py

+
+
+# Select authentication class based on AUTH_PROVIDER
+if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':


same typed constant here as well that will be easy on the checks astoo to know which auth backend is active rather than string comparison

already done in the AuthProvider constants fix

backend/login/hanko_helpers.py

kshitijrajsharma · 2026-03-27T16:51:13Z

backend/login/hanko_helpers.py

+        existing = OsmUser.objects.get(osm_id=osm_id)
+        logger.info(f"Found existing OsmUser: osm_id={osm_id}")
+        return existing
+    except OsmUser.DoesNotExist:


if else should suffice but this is okay too

true, both work fine

kshitijrajsharma · 2026-03-27T16:51:39Z

backend/login/hanko_helpers.py

+    def get_queryset(self):
+        queryset = super().get_queryset()
+
+        mine_param = self.request.query_params.get('mine', '').lower()


I don't understand this what's mine param ?

this "mine" param is a workaround we added because there was a bug that didn't allow filtering datasets/models by user directly

How the auth flow works:

Portal sends request with Hanko cookie to fAIr

HankoAuthMiddleware extracts the Hanko user from JWT

HankoAuthentication looks up the user mapping (Hanko ID → OSM ID) in the DB

Sets request.user to the mapped OsmUser

The problem: ViewSets don't auto-filter by request.user. Your filterset_fields = ["user"] fix allows ?user=<osm_id>, but Portal only has the Hanko token, it doesn't know the osm_id.

The proper fix would be auto-filtering in get_queryset() when user is authenticated. For now mine=true triggers this filter using the resolved request.user. Let me know if you want us to implement the ViewSet fix instead.

kshitijrajsharma · 2026-03-27T16:52:01Z

backend/login/urls.py

        name="request-email-verification",
    ),
    path("me/verify-email/", views.VerifyEmail.as_view(), name="verify-email"),
+    # Hanko onboarding endpoint (only used when AUTH_PROVIDER=hanko)


then path should only be added when authprovider backend is hanko !

yes! moved the onboarding path inside an if settings.AUTH_PROVIDER == AuthProvider.HANKO block

kshitijrajsharma · 2026-03-27T16:54:02Z

backend/login/views.py

+                app_name="fair",
+            )
+
+            frontend_url = getattr(settings, 'FRONTEND_URL', '/')


settings.frontend_url , it has default value so it would be available in django settings

fAIr/backend/fairproject/settings.py

Line 35 in 8cc9a35

FRONTEND_URL = env("FRONTEND_URL", default="https://fair-dev.hotosm.org")

right, simplified to settings.FRONTEND_URL

kshitijrajsharma · 2026-03-27T16:55:18Z

backend/login/views.py

+
+            if not existing_user:
+                from urllib.parse import urlencode
+                login_url = getattr(settings, 'LOGIN_URL', 'https://login.hotosm.org')


same , lets make it explicit defautl value in settings !

done, simplified to settings.LOGIN_URL

kshitijrajsharma · 2026-03-27T16:56:50Z

backend/login/views.py

+        from hotosm_auth_django import get_mapped_user_id
+
+        if getattr(settings, 'AUTH_PROVIDER', 'legacy') != 'hanko':
+            return Response({


Use exceptions https://github.com/hotosm/fAIr/blob/develop/backend/core/exceptions.py You can have a class for login !

perfect! Added LoginException in core/exceptions.py and using it in OnboardingCallback for the Hanko-specific errors. The responses in AuthStatus are status info (not errors), so they stay as regular responses, returning authenticated: False is expected behavior, not an error

kshitijrajsharma · 2026-03-27T16:58:09Z

backend/pyproject.toml

 description = "AI Assisted Mapping"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"


hotosm-auth[django] requires python 3.10 I assume ?

yes, we bumped from 3.9 to 3.10 because hotosm-auth requires it. If needed we could update the lib to support 3.9, but if it's not a problem we'd prefer to keep 3.10

kshitijrajsharma · 2026-03-27T17:00:49Z

PR_DRAFT.md

Kindly remove this from the PR , rather its okay to include it in the description , if you are comfortable with .md you can put this in gist and share the link !

jeafreezy · 2026-03-27T16:59:30Z

frontend/src/assets/svgs/hamburger-icon.svg

Can we rename this to hamburger-icon so it's consistent with existing naming convention ?

jeafreezy · 2026-03-27T19:38:24Z

frontend/src/components/layouts/navbar/navbar.tsx

              {SHARED_CONTENT.navbar.loginButton}
            </Button>
          )}
+          <hotosm-tool-menu></hotosm-tool-menu>


Must this always exist even in legacy mode ? It doesn't style well in legacy mode.

But when i switch to Hanko, it does style well.

Also, is it possible to detect the current application and disable it from the menu ? It can be also be an argument here https://github.com/hotosm/portal/tree/main/frontend/web-components/tool-menu to make it flexible e.g disable-active-app, that way the users won't need to see fAIr again on the tools since they're already on fAIr. This just an idea.

Finally, redirection doesn't work in development environment when i switch to hankomode. It just takes me to my profile page. See attached video for reference.

Screen.Recording.2026-03-27.at.20.35.42.mov

thanks for the detailed feedback!

Tool menu in legacy mode. For now I'm hiding it in legacy mode. The issue is that hanko-auth injects HOT design system CSS globally, which tool-menu depends on. In legacy mode that CSS never loads so the component doesn't render correctly. @warmijusti can you take a look? Not sure if the fix should be in tool-menu (inject CSS globally like hanko-auth does) or if we should load it in fAIr.

disable-active-app attribute: good idea! @warmijusti thoughts?

Redirection not working: I saw you tested locally (127.0.0.1) against dev.login. That won't work because Hanko auth shares cookies by subdomain, so dev.login.hotosm.org can't set cookies for localhost. For local dev it's easier to use legacy mode. To test Hanko properly we'd need to deploy to fair-dev where the subdomains align and env vars will be configured correctly.

Hi everyone, for point number 2, I think it's better to not disable or hide the tool.

It's good for the user to see in which category the tool is located (imagery, mapping, field, data)

It will help to locate the app in the list the next time

Disabling the link is not adding anything to the UI/UX and it prevents users to click it. Some people could use this link

hi! regarding point number 1: thanks for the catch! version 0.2.7 of the tool menu should solve this issue.

This reverts commit ec3cf59.

hg1g added 2 commits March 12, 2026 19:04

Add Hanko SSO authentication

540c48b

Auth functionality only, deploy config in separate PR.

Restore docstrings and comments

acd00d0

hg1g mentioned this pull request Mar 12, 2026

Add testlogin deployment workflow #493

Draft

Remove unused auth-libs local folder

8e07af0

emi420 marked this pull request as ready for review March 13, 2026 03:04

emi420 marked this pull request as draft March 13, 2026 03:05

Fix missing email mock in onboarding test

da3cb38

hg1g marked this pull request as ready for review March 13, 2026 14:36

kshitijrajsharma requested review from jeafreezy and kshitijrajsharma and removed request for jeafreezy March 19, 2026 09:34

omranlm requested a review from jeafreezy March 27, 2026 15:22

omranlm added enhancement New feature or request component : frontend labels Mar 27, 2026

omranlm reviewed Mar 27, 2026

View reviewed changes

kshitijrajsharma reviewed Mar 27, 2026

View reviewed changes

backend/login/hanko_helpers.py Show resolved Hide resolved

kshitijrajsharma reviewed Mar 27, 2026

View reviewed changes

kshitijrajsharma requested changes Mar 27, 2026

View reviewed changes

kshitijrajsharma added component : backend status : testing labels Mar 27, 2026

jeafreezy reviewed Mar 27, 2026

View reviewed changes

hg1g added a commit that referenced this pull request Mar 27, 2026

Address PR #492 review comments

2722370

hg1g added 5 commits March 27, 2026 17:14

Address PR #492 review comments

e462ee7

Hide tool-menu in legacy auth mode

ec3cf59

Revert "Hide tool-menu in legacy auth mode"

3021668

This reverts commit ec3cf59.

Show tool-menu only in hanko mode (temporary fix)

ab126b1

Fix tests to expect exceptions instead of Response

afc6976

kshitijrajsharma requested a review from jeafreezy April 1, 2026 12:22

emi420 mentioned this pull request Apr 2, 2026

Add Hanko SSO Authentication #497

Open

Solve hor variables import bug

b0d2500

jeafreezy approved these changes Apr 6, 2026

View reviewed changes

kshitijrajsharma merged commit 057e231 into develop Apr 7, 2026
7 checks passed

kshitijrajsharma deleted the feature/hanko-auth branch April 7, 2026 12:58



		# Select authentication class based on AUTH_PROVIDER
		if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':

Uh oh!

Conversation

hg1g commented Mar 12, 2026 • edited by kshitijrajsharma Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add Hanko SSO Authentication

Summary

For Deployment: Required Secrets & Variables

Backend Environment Variables

Frontend Environment Variables

Important Notes

New Dependencies

New API Endpoints

How it Works

Legacy Mode (default)

Hanko Mode

Onboarding Flow

Test Plan

Backward Compatibility

Uh oh!

omranlm left a comment

Choose a reason for hiding this comment

Uh oh!

jeafreezy commented Mar 27, 2026

Uh oh!

kshitijrajsharma Mar 27, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

hg1g commented Mar 12, 2026 •

edited by kshitijrajsharma

Loading

kshitijrajsharma Mar 27, 2026 •

edited

Loading