mirror/trailbase
1
0
Fork 0
mirror of https://github.com/trailbaseio/trailbase.git synced 2026-04-28 20:49:41 -05:00
Code Issues Packages Projects Releases Wiki Activity

Docs: clear up blurp about authentication code flow + PKCE. #86

Browse Source
This commit is contained in:
Sebastian Jeltsch
2025-07-27 14:10:54 +02:00
parent be13dbeab2
commit aa9f477972
1 changed files with 30 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/content/docs/documentation/auth.mdx
+30 -17
View File
@@ -67,34 +67,43 @@ When building your own UIs, login is handled by:
for OAuth. It constructs a redirect for the external provider including the
callback address back to your TrailBase instance (`<YOUR_SITE>/api/auth/v1/oauth/<PROVIDER_NAME>/callback`).
### PKCE and Client-Side Apps
### Authentication Code Flow & PKCE
Whenever a client-side application (mobile, desktop, ...), defers to a Web
UI[^4] for users to sign in, it is *recommended* to use
Proof-Key-for-Code-Exchange (PKCE) to protect against man-in-the-middle attacks
by other applications on the user's device such as infected or malicious browsers.
Whenever a native client-side application (mobile, desktop, ...) or
different-origin web app defers to a web UI[^4] for their users to sign in, a
protocol for exchanging the tokens is needed.
The basic idea is to turn the normal sign-in flow (`login(creds) -> tokens`)
from a single into a two-step process:
The *authentication code flow* defines such a protocol. Upon successful
off-site login, users are redirected to a `<callback>?auth_code=<code>`
address provided by your application.
Subsequently, your app can exchange the auth code[^5], typically together with another
secret, for tokens via TrailBase's
[`/api/auth/v1/token`](/api/operations/auth_code_to_token_handler/)
endpoint to sign the user in.
Proof-Key-for-Code-Exchange (PKCE) provides an elegant way to establish the
secondary secret and also protects against man-in-the-middle attacks by
infected or malicious browsers/WebViews.
*Authentication code flow* with PKCE results in a two-step login procedure:
1. `login(creds, pkce_code_challenge) -> auth_code`
2. `upgrade(auth_code, pkce_code_verifier) -> tokens`
with the `pkce_code_verifier` being randomly generated by the client and
`pkce_code_challenge` simply being a hash thereof.
Since only step (1) is mediated by an external application, they cannot
intercept the tokens in step (2).
where `pkce_code_verifier` is simply a client-generated random secret and
`pkce_code_challenge` is a hash thereof.
Since only the first step is mediated by an external application (browser or
WebView), the subsequent token exchange cannot be intercepted.
You can use PKCE with TrailBase by additionally passing:
To initiate the authentication code flow with PKCE you have to additionally
pass:
- `response_type=code`,
- `pkce_code_challenge=<CHALLENGE>`,
- `pkce_code_challenge=<urlSafeBase64(sha256(pkce_code_verifier)))>`,
- `redirect_to=<TARGET>`, e.g. `custom-app-schema://callback`,
as input to `/api/auth/v1/login` and `/api/auth/v1/oauth/<PROVIDER_NAME>/login`.
With an `auth_code` in hand, the client can call
[`/api/auth/v1/token`](/api/operations/auth_code_to_token_handler/)
to upgrade `auth_code` + `pkce_code_verifier` to a new user session and tokens.
as inputs to `/api/auth/v1/login` or `/api/auth/v1/oauth/<PROVIDER_NAME>/login`.
Note that native applications will need to register the callback scheme first
to receive the evnetual callback.
## Design
@@ -214,3 +223,7 @@ have persisted should be dropped.
[^4]:
Both for TrailBase's built-in auth UIs and custom UIs.
[^5]:
An intermediary code is used since tokens can get reasonably large and
in-lining them would be brittle as well as interceptable.