OAuth/OIDC Setup

GeoLens supports SSO via OAuth 2.0 / OpenID Connect with four provider types: Google, GitHub, Microsoft Entra ID, and generic OIDC (Auth0, Okta, Keycloak, Authentik, and any other OIDC-compliant IdP). GitHub is a plain OAuth 2.0 provider rather than OIDC, so it does not use a discovery document. All flows use PKCE (Proof Key for Code Exchange, S256) automatically. Client secrets are encrypted at rest (see PKCE & client-secret encryption).

Replace https://geolens.example.com with your GeoLens instance’s URL in every example below.

Set your public URLs first

Set PUBLIC_APP_URL and PUBLIC_API_URL to your instance’s externally reachable origin before you register anything at an IdP. GeoLens builds the redirect_uri it hands the provider from the resolved public API URL — PUBLIC_API_URL when set, otherwise PUBLIC_APP_URL with /api appended — and the IdP will only accept a callback it already has on file. Both Compose files default these to the loopback origin the installer prints, so an instance nobody has configured asks the provider to redirect back to that loopback address rather than to your hostname, and the first login fails with redirect_uri_mismatch. If neither value is set, GeoLens refuses to infer an origin from request headers and the login and callback endpoints return 500. Set both in .env, or under Admin -> Settings -> General (the saved value overrides .env) — see Configuration.

How OAuth works in GeoLens

The diagram shows the bundled setup, where the web app and the API share an origin. The callback hands the browser a one-time code that expires after two minutes and works only in the browser that started the sign-in, and the exchange sets the refresh token as an httpOnly cookie. When the web app and the API are on different origins, the cookie can’t be used, so the callback redirects to /oauth/callback#token=...&refresh_token=... with both tokens in the URL fragment instead.

End users do not call these endpoints directly. They sign in through the GeoLens web UI, which performs the authorization-code flow on their behalf. Once the UI has a JWT, machine clients reuse it like any other Bearer token (see API authentication).

PKCE & client-secret encryption

PKCE (Proof Key for Code Exchange) is enforced for every OAuth flow regardless of provider type: GeoLens generates a random code_verifier, sends the SHA-256 code_challenge on the authorize redirect, and verifies the verifier on the token exchange. This protects against authorization-code interception even on browsers without HTTPS-only contexts.

Client secrets stored in the database are encrypted at rest with Fernet (AES-128-CBC + HMAC-SHA256). The key is SECRET_ENCRYPTION_KEY when it is set, with SECRET_ENCRYPTION_KEY_PREVIOUS still accepted for reads during a key rotation. When it isn’t set, the key is derived from JWT_SECRET_KEY, and rotating the JWT secret then makes every stored client secret unreadable until you re-enter it in the admin UI. Set SECRET_ENCRYPTION_KEY so the JWT secret can rotate without touching SSO. After adding it to an existing install, re-encrypt the stored secrets with backend/scripts/rotate_secrets.py; RUNBOOK.md section 11 has the steps for adopting and rotating the key.

Configure providers via the admin UI

The simplest way to configure OAuth is through the admin settings panel:

1. Navigate to Admin -> Settings -> Auth.
2. Scroll to the OAuth Providers section.
3. Click Add Provider.
4. Select the provider type, fill in the required fields, and click Create Provider.

Providers can be enabled, disabled, edited, or deleted from the same panel. The login screen reflects changes immediately. No restart required.

Providers are records in the database, not settings, so they stay manageable here and through the provider API when ENV_ONLY_CONFIG=true. That mode locks the settings on the Auth tab to their environment values but does not lock providers. There is no environment variable or file format for declaring providers, so an env-only deployment still creates them in the admin UI or API. Before 1.24.0 the tab disabled Add, Edit and Delete in env-only mode even though the API accepted them.

Provider configuration reference

Whether you use the admin UI or the API, every provider has the same configurable fields:

Field	Required	Description
slug	Yes	URL-safe identifier used in callback URLs (e.g. google, azure-ad)
display_name	Yes	Label shown on the login page button
provider_type	Yes	One of: google, github, microsoft, oidc
client_id	Yes	OAuth client ID from the IdP
client_secret	Yes	OAuth client secret
discovery_url	No	OIDC discovery URL (.well-known/openid-configuration). Auto-populates for Google and Microsoft. Rejected for github (GitHub is not OIDC)
authorize_url	No	Authorization endpoint (only needed if discovery_url is not set; auto-filled for github)
token_url	No	Token endpoint (only needed if discovery_url is not set; auto-filled for github)
userinfo_url	No	Userinfo endpoint (only needed if discovery_url is not set; auto-filled for github)
scopes	No	Space-separated scopes. Default: openid profile email (for github, read:user user:email)
default_role	No	Role assigned to new users: viewer, editor, or admin. Default: viewer
enabled	No	Whether the provider appears on the login page. Default: true

Provider step-by-steps

Google

1. Go to the Google Cloud Console.
2. Create a new OAuth 2.0 Client ID (application type: Web application).
3. Add the authorized redirect URI:

   https://geolens.example.com/api/auth/oauth/google/callback

4. Copy the Client ID and Client Secret.
5. In GeoLens, create the provider via the admin UI (Admin -> Settings -> Auth -> Add Provider -> Google), or via the API:

curl -X POST https://geolens.example.com/api/settings/oauth-providers/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "google",
    "display_name": "Google",
    "provider_type": "google",
    "client_id": "123456789.apps.googleusercontent.com",
    "client_secret": "GOCSPX-xxxxxxxxxxxx",
    "discovery_url": "https://accounts.google.com/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "default_role": "viewer",
    "enabled": true
  }'

The “Sign in with Google” button appears on the login page immediately after creation.

Microsoft Entra ID

1. In the Azure Portal, navigate to Microsoft Entra ID -> App registrations -> New registration.
2. Set the redirect URI to:

   https://geolens.example.com/api/auth/oauth/microsoft/callback

3. Under Certificates & secrets, create a new client secret. Save the secret value (not the secret ID) immediately. Azure shows it only once.
4. Note your Application (client) ID, Directory (tenant) ID, and the secret value.
5. Create the provider in GeoLens:

curl -X POST https://geolens.example.com/api/settings/oauth-providers/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "microsoft",
    "display_name": "Microsoft",
    "provider_type": "microsoft",
    "client_id": "YOUR_APPLICATION_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET_VALUE",
    "discovery_url": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "default_role": "viewer",
    "enabled": true
  }'

The tenant-specific discovery URL embeds your Directory (tenant) ID. Use this form for a dedicated Microsoft Entra tenant; use common only when your identity team has approved broader Microsoft consent settings.

GitHub

GitHub is a plain OAuth 2.0 provider (not OIDC). Its authorize, token, and userinfo endpoints are fixed, so you supply only the client credentials — do not set discovery_url (GitHub providers reject it).

1. In GitHub, go to Settings -> Developer settings -> OAuth Apps -> New OAuth App (a personal or organization OAuth app).
2. Set the Authorization callback URL to:

   https://geolens.example.com/api/auth/oauth/github/callback

3. Copy the Client ID and generate a Client Secret.
4. Create the provider in GeoLens:

curl -X POST https://geolens.example.com/api/settings/oauth-providers/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "github",
    "display_name": "GitHub",
    "provider_type": "github",
    "client_id": "Iv1.xxxxxxxxxxxx",
    "client_secret": "your-github-client-secret",
    "scopes": "read:user user:email",
    "default_role": "viewer",
    "enabled": true
  }'

The default scope is read:user user:email; user:email is required so GeoLens can read the account’s verified email to match or create the user. Leave authorize_url, token_url, and userinfo_url unset — GeoLens fills in GitHub’s fixed endpoints (github.com/login/oauth/authorize, github.com/login/oauth/access_token, and api.github.com/user) automatically.

Generic OIDC

For any OIDC-compliant provider (Auth0, Okta, Keycloak, Authentik, etc.):

1. Register a new application in your IdP. Application type: Web application with authorization-code flow.
2. Set the redirect URI to:

   https://geolens.example.com/api/auth/oauth/{slug}/callback

   Replace {slug} with whatever slug you plan to use (e.g. keycloak, okta, auth0).
3. If the IdP publishes a discovery document, use discovery_url. Otherwise, provide authorize_url, token_url, and userinfo_url explicitly.

curl -X POST https://geolens.example.com/api/settings/oauth-providers/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "keycloak",
    "display_name": "Keycloak",
    "provider_type": "oidc",
    "client_id": "geolens",
    "client_secret": "your-keycloak-secret",
    "discovery_url": "https://keycloak.example.com/realms/main/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "default_role": "editor",
    "enabled": true
  }'

For providers that don’t publish discovery (rare in 2026), supply the three endpoints manually:

{
  "authorize_url": "https://idp.example.com/oauth2/authorize",
  "token_url": "https://idp.example.com/oauth2/token",
  "userinfo_url": "https://idp.example.com/oauth2/userinfo"
}

Configure programmatically

Providers can be managed entirely via the API. All endpoints require the manage_settings capability (admin role). Obtain a JWT token first. The admin password is generated at install time and stored in your .env as GEOLENS_ADMIN_PASSWORD — the installer never prints the value itself, so read it back from that file (or substitute your own admin account):

export GEOLENS_ADMIN_USERNAME="$(grep '^GEOLENS_ADMIN_USERNAME=' .env | cut -d= -f2-)"
export GEOLENS_ADMIN_PASSWORD="$(grep '^GEOLENS_ADMIN_PASSWORD=' .env | cut -d= -f2-)"

TOKEN=$(curl -s -X POST https://geolens.example.com/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=$GEOLENS_ADMIN_USERNAME" \
  --data-urlencode "password=$GEOLENS_ADMIN_PASSWORD" | jq -r '.access_token')

List providers

curl https://geolens.example.com/api/settings/oauth-providers/ \
  -H "Authorization: Bearer $TOKEN"

The response never includes the client_secret. Secrets are write-only.

Update a provider

curl -X PUT https://geolens.example.com/api/settings/oauth-providers/{provider_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Only include client_secret in the update payload if you need to rotate it. Omitting the field preserves the existing encrypted secret.

Delete a provider

curl -X DELETE https://geolens.example.com/api/settings/oauth-providers/{provider_id} \
  -H "Authorization: Bearer $TOKEN"

Deleting a provider also removes all linked OAuth accounts for that provider. Affected users fall back to local-password login (if they have a password set) or lose access entirely.

One case is refused: if password login is disabled and this is the last enabled SSO provider, the delete returns 422 rather than locking everyone out. The same guard fires on an update that sets enabled: false. Re-enable password login, or enable another provider, first.

Account linking

If Allowed Email Domains is set on the Auth tab, it is checked before any of the linking rules below. For a first-time SSO identity a non-empty allowlist makes a verified email mandatory: an identity with no email claim, an unverified one, or one outside an allowed domain is refused rather than provisioned. Returning users are checked too — against the IdP’s verified claim when present, otherwise their stored address — with one exemption: a returning user who holds manage_settings is let through, mirroring the break-glass on password login. The list is empty by default, which allows any domain.

When a user signs in via OAuth, GeoLens applies these rules in order:

1. Existing OAuth link. If the user has previously signed in with the same provider and subject ID, they are logged in to the existing account.
2. Email match — verified addresses only. If no prior OAuth link exists, the OAuth identity is linked to a local user with the same email address (case-insensitive) only when the IdP asserted email_verified: true. The local password remains valid; the user can use either authentication method. If the claim is missing or false and a local account already holds that address, the login is refused — sign in with the local account and link OAuth from your profile, or have the IdP verify the address. If the claim is missing or false and no local account holds that address, the email is discarded and the account created in step 3 has none.
3. New account. Otherwise, and only while self-registration (REGISTRATION_ENABLED) is on, a new active user account is created with a username derived from the email prefix or display name. The role assigned is the provider’s default_role. With self-registration off the sign-in is refused; an admin creates the account first, and the next SSO sign-in links to it through step 2. With it on, set Allowed Email Domains or use a single-tenant identity provider, because a Google, GitHub or multi-tenant Microsoft provider otherwise lets anyone with such an account create an active account here.

This means existing local users can start using OAuth without losing their data, as long as the email addresses match. For organizations migrating from local-only auth, the recommended sequence is: enable the OAuth provider with default_role: viewer, instruct users to sign in via OAuth once (which auto-links by email — this requires an IdP that emits email_verified; Google, Microsoft, Okta, and Auth0 all do, and the GitHub provider satisfies it by construction, since GeoLens accepts only a GitHub account’s primary and verified address), then optionally disable local-password login for OAuth-managed accounts.

Note

Email-based linking is case-insensitive but exact otherwise. alice@example.com and Alice@Example.com link to the same user, but alice@example.com and alice.smith@example.com do not, even if both belong to the same person at the IdP. Coordinate email canonicalization with your identity provider before enabling OAuth on a populated instance.

See also

• User management & RBAC: for default-role assignment and the role/permission matrix
• Settings reference: system-wide auth settings beyond per-provider config
• API authentication: the JWT format the OAuth flow ultimately issues