Skip to main content

OAuth login

identity-service owns the whole OAuth flow. Provider apps call back to one fixed URL on identity-service, which exchanges the code server-side, applies the company rules, and returns tokens to the shell. This page covers that flow, the confirmation page, token delivery, and the redirect allowlist. For passwordless email sign-in, see Magic link. A company can enable both. A desktop app returns through a custom-scheme link instead of an http(s) shell. See Desktop apps. Web and desktop session codes both use S256 PKCE.

How the flow works​

The shell (or shellui login in the CLI) only talks to identity-service. The shell destination, redirect_to, travels in a signed OAuth state value, never in the provider callback URL:

  1. The shell opens GET /api/v1/authorize with company_id, redirect_to, code_challenge, code_challenge_method=S256, and optionally provider.
  2. Without provider, identity-service shows a sign-in method picker, even when the company has a single method.
  3. identity-service redirects to the provider with redirect_uri set to its own /api/v1/oauth/callback and a signed state.
  4. The provider returns to /api/v1/oauth/callback. identity-service exchanges the code server-side.
  5. identity-service shows an account confirmation page. The user can continue, switch provider, or switch account. Some providers skip this step, see Skip the confirmation page.
  6. identity-service redirects to redirect_to?shellui_auth_code=…. That response sets the identity browser session cookie when the account is active and can access the company. The shell page does not read that cookie. The shell host exchanges the one-time code. See Shell host session.

GET /api/v1/settings includes logout_url, the identity origin plus /oauth/logout. To sign the browser out of identity, send it to logout_url?company_id=<id>&return_to=<url> with GET or POST. return_to uses the same allowlist as redirect_to on /api/v1/authorize. A missing or rejected return_to shows "You are signed out" and does not redirect. This route calls Django logout only. It does not revoke access or refresh tokens. That stays on POST /api/v1/logout with the Bearer token. GET /api/v1/sessions lists those refresh sessions, not the browser cookie.

Company join rules (public, domain, invite) apply after the provider sign-in succeeds. See Company access.

Register the callback URL​

Register one callback URL on each provider app, pointing at identity-service, with no query string:

EnvironmentCallback URL
Localhttp://localhost:8000/api/v1/oauth/callback
Productionhttps://auth.example.com/api/v1/oauth/callback

The provider homepage or application URL can still be your shell, for example https://app.example.com. Do not register the shell /login/callback URL at the provider: only identity-service redirects there. Supported providers and their settings are listed in OAuth providers.

Skip the confirmation page​

After the callback, identity-service shows a confirmation page so the user can check which account they used. Google skips it by default, because Google already shows its own consent screen and account picker. OAUTH_SKIP_CONFIRM_PROVIDERS controls the list:

ValueBehavior
Unsetgoogle skips the confirmation page
google,microsoftEach listed provider skips it. Use catalog IDs from OAuth providers
Empty (OAUTH_SKIP_CONFIRM_PROVIDERS=)Every provider shows it

An unknown ID in the list is ignored. When the profile is not good enough to finish on its own, identity-service shows the confirmation page anyway. That happens when the email is missing, is a {id}@{provider}.local placeholder, or comes with email_verified: false.

Token delivery​

By default, identity-service sends the shell a one-time code, not the tokens. The code is valid for OAUTH_SESSION_CODE_TTL_SECONDS (120 seconds by default) and works once:

ModeHow the shell receives tokensStatus
code (default)redirect_to?shellui_auth_code=…, then POST /api/v1/oauth/sessionRecommended
fragmentIgnored since 0.9.0, falls back to codeDeprecated, will be removed

Since 0.9.0 tokens are never sent in the URL fragment. token_delivery=fragment and OAUTH_TOKEN_DELIVERY=fragment fall back to the one-time code, which requires PKCE. POST /api/v1/oauth/exchange still serves older shells that receive the provider ?code= themselves.

Custom-scheme redirects work the same way. See Desktop apps.

PKCE for every session code​

S256 PKCE is required for web redirects and for custom-scheme redirects. identity-service stores the challenge on the one-time code. It does not store the verifier. A copied shellui_auth_code cannot be redeemed without the verifier the shell kept.

Send the challenge when sign-in starts:

StartParameters
GET /api/v1/authorizequery code_challenge, code_challenge_method=S256
POST /api/v1/magic-link/requestthe same two fields in the JSON body
GET /api/v1/saml/<organization_slug>/login/the same query parameters

The method picker and the SAML handoff keep those parameters on the next URL. plain is refused. The challenge is 43 to 128 base64url characters (RFC 7636). The verifier is 43 to 128 unreserved characters. code_challenge is BASE64URL(SHA256(verifier)) with the = padding removed.

Exchange:

{
"auth_code": "<shellui_auth_code>",
"redirect_to": "<the callback URL with shellui_auth_code removed>",
"code_verifier": "<verifier>"
}

redirect_to is the same URL sent at the start, including other query parameters, without shellui_auth_code. For an http(s) redirect, Origin is required and must equal the origin of redirect_to (scheme, host, and port, no path). The shell host sets that header to the shell page origin. A missing Origin is 400 with {"error":"Origin is required for this redirect."}. A different origin is 400 with {"error":"Origin does not match redirect_to."}. Those two responses have no error_code. PKCE failures are 400 with error and error_code (pkce_required, invalid_code_challenge, invalid_code_challenge_method, invalid_code_verifier, pkce_verification_failed). A failed check does not use up the code.

A custom-scheme redirect still skips the Origin check, and only after the verifier matches. See Desktop apps.

token_delivery=fragment no longer bypasses this: it falls back to the one-time code.

POST /api/v1/oauth/exchange and POST /api/v1/providers/<provider>/login/ are the older JSON endpoints. They require S256 PKCE only for a custom-scheme redirect_uri. New shells use /api/v1/authorize and /api/v1/oauth/session.

Web sign-in and the CLI​

Web sign-in sends S256 PKCE. Create a verifier and its challenge before GET /api/v1/authorize, and send code_verifier with the one-time code. shellui login does not redeem a code on a loopback page. It uses device login. See CLI device login.

Desktop and Tauri apps send the challenge and the verifier too. A custom scheme does not need a matching Origin.

Shell host session​

The shell and identity are different sites. Keep the access token and the refresh token on the shell host.

Run the host with shellui start or serve:dist, or put your own proxy on the shell origin. The browser arrives with shellui_auth_code in the query. The host then calls identity. No identity cookie is required:

  1. POST /api/v1/oauth/session with auth_code, redirect_to, and code_verifier
  2. POST /api/v1/token?grant_type=refresh_token with refresh_token in the JSON body when you need a new access token
  3. POST /api/v1/logout with Authorization: Bearer and refresh_token in the JSON body, then clear the refresh token on the host

Page JavaScript does not call these endpoints and does not see the tokens.

Set Origin on the exchange to the shell page origin (scheme, host, and port). It must match the origin of redirect_to. Identity accepted that redirect_to only when the origin was an active CompanyOAuthRedirect for the company, or a loopback origin when loopback redirects are allowed.

A second allowlisted origin does not match this code. These calls are server to server, so CORS does not apply.

Store the refresh token in a first-party cookie on the shell host. Replace that cookie when refresh returns a new refresh token. Clear it after logout.

PKCE, single use, and the 120s code lifetime are unchanged. A failed PKCE or Origin check does not use up the code.

Identity records the refresh session while the browser is on identity, when it issues the code. It does not take a client IP from the shell host. X-Forwarded-For is used only when the direct peer is listed in TRUSTED_PROXY_IPS. That setting is for a reverse proxy in front of identity, not for the shell host.

Redirect allowlist​

identity-service only sends codes or tokens to origins the company approved. This stops a crafted redirect_to from sending a session to another site:

TargetRule
Loopback (127.0.0.1, localhost, ::1)Allowed when DEBUG=true or OAUTH_ALLOW_LOOPBACK_REDIRECTS=true, for local shells
Other http(s) originsMust match an active CompanyOAuthRedirect row for the company
Desktop app URIScheme must be in the company desktop_redirect_schemes list. An empty list turns desktop sign-in off. With DEBUG=true, or with allow_desktop_dev_scheme, a listed scheme also allows its -dev variant. See Desktop apps
Hosting previews ({slug}.{HOSTING_APP_DOMAIN})Added and removed by hosting-service (source=hosting) when a site is created or deleted
Empty allowlistEvery non-loopback http(s) redirect_to is denied. A custom-scheme redirect_to is denied unless that scheme is in desktop_redirect_schemes

Store web origins as scheme, host, and optional port, for example http://localhost:4000 or https://app.example.com. A path or query on a web allowlist entry is ignored. A desktop redirect is not an allowlist row: add the scheme to the company, then send shellui-playground://callback.

Manage the allowlist​

Staff and company owners can edit the allowlist in three places:

  • Shellui admin: OAuth setup, with manual origins and a separate list of hosting previews
  • Django admin: Company OAuth redirects
  • REST API: GET, POST, PATCH, and DELETE on /api/v1/oauth-redirects?company_id=…

This request adds a production shell origin for company 1:

curl -s -X POST "https://auth.example.com/api/v1/oauth-redirects?company_id=1" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"base_url":"https://app.example.com","label":"Production shell"}'

hosting-service keeps preview origins in sync with PUT and DELETE on /api/v1/hosting-oauth-redirects, using the deployer's identity JWT (staff or company owner). The company comes from the token.

CORS is a separate control​

CORS decides which browser origins may call the API. The redirect allowlist decides where sessions go after sign-in. Only the allowlist needs to be strict:

ConcernMechanismStrict
Token delivery after OAuthCompanyOAuthRedirect allowlist and one-time code exchangeYes. Keep the list short and prefer code delivery
Browser API calls with a Bearer JWTCORS_ALLOW_ALL_ORIGINS=true by default, with CORS_ALLOW_CREDENTIALS=falseNo. JWT verification and company scoping protect the API

Do not add hosting preview origins to CORS_ALLOWED_ORIGINS. Set CORS_ALLOW_ALL_ORIGINS=false only on installs that restrict API origins on purpose, see Security hardening.

Account linking and login CSRF​

identity-service first matches a sign-in to an existing user by provider account ID. When there is no match, it links by email only when the provider proves the user owns that email, for example a verified primary email on GitHub or email_verified in a Google ID token. Otherwise it returns an error rather than attach the sign-in to another user's account. The rule for each provider is in How email linking works.

To block login CSRF, /api/v1/authorize stores a random nonce in the shellui_oauth_state_nonce cookie (HttpOnly, SameSite=Lax). The callback checks that nonce against the signed state, and rejects a state that was already used.

Endpoints​

EndpointRole
GET /api/v1/authorizeStart sign-in, with an optional method picker
GET /api/v1/oauth/callbackProvider callback and confirmation page
POST /api/v1/oauth/confirmFinish sign-in after confirmation
GET /api/v1/oauth/confirm?action=switch&confirm_token=…Restart OAuth with the account picker (Google, Microsoft)
POST /api/v1/oauth/sessionExchange shellui_auth_code for tokens
POST /api/v1/oauth/exchangeDeprecated code exchange for older shells
GET, POST, PATCH, DELETE /api/v1/oauth-redirectsManage the redirect allowlist
PUT, DELETE /api/v1/hosting-oauth-redirectshosting-service sync (source=hosting)
GET /api/v1/oauth-provider-catalogProvider catalog for Shellui admin
GET, POST /api/v1/oauth-social-appsCompany provider apps (client ID, secret, settings)