@lowdefy/docs-content 6.1.0 → 7.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +7 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +43 -7
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +154 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +8 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +136 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +2 -0
- package/content/connections/smtp.md +3 -1
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +24 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +1 -0
- package/content/controls/try.md +4 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +10 -7
- package/content/deployment/docker.md +22 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +17 -6
- package/content/display-blocks/aggrid.md +36 -19
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +24 -1
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +44 -0
- package/index.json +3691 -14
- package/package.json +11 -1
- package/scripts/collectImportedFiles.js +80 -0
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +100 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
# Auth Configuration
|
|
2
|
+
|
|
3
|
+
The `auth` section configures user authentication. Lowdefy's auth is built on [BetterAuth](https://www.better-auth.com/): sessions are database-backed, the app owns its auth UI, and roles live on organization memberships. If you are moving from the previous NextAuth-shaped config, start with the [Auth Upgrade guide](/auth-upgrade) — several keys were renamed or removed.
|
|
4
|
+
|
|
5
|
+
The `_secret` operator is evaluated over the entire `auth` section, so any value can be a secret reference.
|
|
6
|
+
|
|
7
|
+
For a login method to work you must configure **at least one mechanism** (`emailAndPassword`, `magicLink`, `emailOTP`, `phoneNumber`, an OAuth `providers` entry, or an API `strategies` entry), a `secret`, and a `database`. An `auth` block with none of these fails the build.
|
|
8
|
+
|
|
9
|
+
## Secret
|
|
10
|
+
|
|
11
|
+
A required signing secret, given as a `_secret` reference:
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
lowdefy: 7.0.0
|
|
15
|
+
auth:
|
|
16
|
+
secret:
|
|
17
|
+
_secret: BETTER_AUTH_SECRET
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Also pin the app's canonical origin — the `url` of the current environment in [`config.environments`](/lowdefy-schema), or the `BETTER_AUTH_URL` environment variable, which wins — auth builds password-reset, magic-link and verification links, and its CSRF origin allowlist, from it. With `auth.email` configured, a production server refuses to start without it. See the [migration guide](/auth-upgrade#3-pin-the-canonical-url-with-better-auth-url).
|
|
21
|
+
|
|
22
|
+
## Database
|
|
23
|
+
|
|
24
|
+
Sessions, users, accounts and organizations are stored through an adapter:
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
lowdefy: 7.0.0
|
|
28
|
+
auth:
|
|
29
|
+
database:
|
|
30
|
+
id: auth_db
|
|
31
|
+
type: MongoDBAuthAdapter
|
|
32
|
+
properties:
|
|
33
|
+
uri:
|
|
34
|
+
_secret: AUTH_DATABASE_URI
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names follow the `user-*` convention and are fixed by the adapter.
|
|
38
|
+
|
|
39
|
+
## Login mechanisms
|
|
40
|
+
|
|
41
|
+
- **Email & password** — `auth.emailAndPassword` (`enabled`, `requireEmailVerification`, `minPasswordLength` (default 8), `disableSignUp`).
|
|
42
|
+
- **Magic link** — `auth.magicLink` (`enabled`, `expiresIn` seconds (default 300), `disableSignUp`), which needs `auth.email` (below).
|
|
43
|
+
- **Email one-time code** — `auth.emailOTP` (`enabled`, `otpLength` (default 6), `expiresIn` seconds (default 300), `allowedAttempts` (default 3), `disableSignUp` (default `false`)), which needs `auth.email` (below). The person is emailed a code and types it into the tab they started from, so the sign-in survives mail security that pre-fetches links, and works when the email is opened on another device.
|
|
44
|
+
- **OAuth providers** — `auth.providers`; see [Providers](/auth-providers).
|
|
45
|
+
- **Phone number** — `auth.phoneNumber` (OTP sign-in); needs a `phone.otp.send` hook to deliver the SMS.
|
|
46
|
+
- **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
|
|
47
|
+
|
|
48
|
+
```yaml
|
|
49
|
+
lowdefy: 7.0.0
|
|
50
|
+
auth:
|
|
51
|
+
emailAndPassword:
|
|
52
|
+
enabled: true
|
|
53
|
+
requireEmailVerification: true
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Auth email
|
|
57
|
+
|
|
58
|
+
`auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
|
|
59
|
+
|
|
60
|
+
```yaml
|
|
61
|
+
lowdefy: 7.0.0
|
|
62
|
+
auth:
|
|
63
|
+
email:
|
|
64
|
+
connectionId: email # an SMTP connection in connections[]
|
|
65
|
+
templates: # all optional; unset → branded stock template
|
|
66
|
+
verifyEmail: verify-email-notification
|
|
67
|
+
resetPassword: reset-password-notification
|
|
68
|
+
magicLink: magic-link-notification
|
|
69
|
+
invitation: invite-notification
|
|
70
|
+
emailOTP: email-otp-notification
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Link and code in one email
|
|
74
|
+
|
|
75
|
+
With both `magicLink` and `emailOTP` enabled, the magic-link email also carries the one-time code, so a single email serves both paths: the person clicks the button, or types the code into the tab they asked for the link from. Nothing extra is sent — the `emailOTP` template is only used for a code-only send.
|
|
76
|
+
|
|
77
|
+
The `magicLink` template then has two more variables available: `otp` (the code) and `expiresIn` (the code's lifetime in seconds, from `auth.emailOTP.expiresIn`). The stock template renders them below the sign-in button; a template of your own can place them wherever it likes. With `emailOTP` off both are absent and the link email is unchanged.
|
|
78
|
+
|
|
79
|
+
## Auth pages
|
|
80
|
+
|
|
81
|
+
BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` points at them. All are Lowdefy page paths:
|
|
82
|
+
|
|
83
|
+
| Key | Default | When required |
|
|
84
|
+
| --- | ------- | ------------- |
|
|
85
|
+
| `signIn` | `/login` | |
|
|
86
|
+
| `signUp` | `/signup` | |
|
|
87
|
+
| `error` | `/auth/error` | receives `?error=` code |
|
|
88
|
+
| `forgotPassword` | `/forgot-password` | |
|
|
89
|
+
| `resetPassword` | `/reset-password` | where the emailed reset link lands, with `?token=` (or `?error=INVALID_TOKEN`); the default `redirectTo` of `RequestPasswordReset` |
|
|
90
|
+
| `verifyEmail` | `/verify-email` | where the emailed verification link lands; receives `?error=` code when the link is invalid or expired |
|
|
91
|
+
| `twoFactor` | — | **required** when `twoFactor.enabled` |
|
|
92
|
+
| `twoFactorEnrol` | — | **required** when `twoFactor.required` |
|
|
93
|
+
| `acceptInvitation` | — | consumes an `?invitationId=` link |
|
|
94
|
+
| `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
|
|
95
|
+
|
|
96
|
+
```yaml
|
|
97
|
+
lowdefy: 7.0.0
|
|
98
|
+
auth:
|
|
99
|
+
authPages:
|
|
100
|
+
signIn: /login
|
|
101
|
+
signUp: /signup
|
|
102
|
+
error: /auth-error
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### The email verification page
|
|
106
|
+
|
|
107
|
+
A verification email links to Better Auth's verify endpoint, which confirms the address and then redirects to `authPages.verifyEmail`. When the link is invalid or has expired, it redirects there with `?error=` set (`INVALID_TOKEN`, `TOKEN_EXPIRED`), so the page can offer to resend with the `SendVerificationEmail` action. A `callbackUrl` on the `SignUp` or `SendVerificationEmail` action sends that link somewhere else instead.
|
|
108
|
+
|
|
109
|
+
### The magic link landing page
|
|
110
|
+
|
|
111
|
+
`authPages.magicLink` is opt-in, and it exists for one reason: Better Auth's magic-link verify endpoint consumes the single-use token on the **first** `GET` of the URL. Corporate mail security — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetches every link in a message at delivery time, so that first `GET` is a scanner and the person clicking arrives to `INVALID_TOKEN`.
|
|
112
|
+
|
|
113
|
+
Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
lowdefy: 7.0.0
|
|
117
|
+
auth:
|
|
118
|
+
magicLink:
|
|
119
|
+
enabled: true
|
|
120
|
+
authPages:
|
|
121
|
+
magicLink: /magic-link
|
|
122
|
+
pages:
|
|
123
|
+
public:
|
|
124
|
+
- magic-link
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
```yaml
|
|
128
|
+
id: magic-link
|
|
129
|
+
type: PageHeaderMenu
|
|
130
|
+
blocks:
|
|
131
|
+
- id: content
|
|
132
|
+
type: Box
|
|
133
|
+
blocks:
|
|
134
|
+
- id: title
|
|
135
|
+
type: Title
|
|
136
|
+
properties:
|
|
137
|
+
content: Sign in
|
|
138
|
+
level: 3
|
|
139
|
+
- id: description
|
|
140
|
+
type: Paragraph
|
|
141
|
+
properties:
|
|
142
|
+
content: Click the button below to finish signing in.
|
|
143
|
+
- id: verify_button
|
|
144
|
+
type: Button
|
|
145
|
+
properties:
|
|
146
|
+
title: Sign in
|
|
147
|
+
events:
|
|
148
|
+
onClick:
|
|
149
|
+
- id: verify
|
|
150
|
+
type: MagicLinkVerify
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The page must **not** call `MagicLinkVerify` in `onMount`, and must not auto-redirect to the verify endpoint. Scanning sandboxes that render the page and execute its JavaScript would consume the token anyway, which puts you back where you started. The protection is the click, not the page.
|
|
154
|
+
|
|
155
|
+
Leave the key unset and magic-link sign-in keeps working exactly as before, linking straight at the verify endpoint.
|
|
156
|
+
|
|
157
|
+
See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [MCP Server & OAuth](/mcp-oauth) page for `oauthProvider.consentPage` and `postLoginPage`.
|
|
158
|
+
|
|
159
|
+
## Session
|
|
160
|
+
|
|
161
|
+
Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
|
|
162
|
+
|
|
163
|
+
```yaml
|
|
164
|
+
lowdefy: 7.0.0
|
|
165
|
+
auth:
|
|
166
|
+
session:
|
|
167
|
+
expiresIn: 43200 # 12 hours in seconds
|
|
168
|
+
updateAge: 3600
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`session.cookieCache` (off by default) trades a short window of stale session reads for fewer database lookups — leave it off unless you understand the [revocation-latency trade](/two-factor#recovering-a-user-who-has-lost-their-factor).
|
|
172
|
+
|
|
173
|
+
## Roles, organizations, and API strategies
|
|
174
|
+
|
|
175
|
+
- **Roles** — declare app role names in `auth.roles` and gate pages/endpoints with `auth.pages.roles` / `auth.api.roles`. See [Roles](/roles).
|
|
176
|
+
- **Organizations** — `auth.organizations.policy` (`pinned` or `tenant`) decides the whole multi-tenancy model. See [Organizations & Multi-Tenancy](/organizations).
|
|
177
|
+
- **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
|
|
178
|
+
|
|
179
|
+
```yaml
|
|
180
|
+
lowdefy: 7.0.0
|
|
181
|
+
auth:
|
|
182
|
+
strategies:
|
|
183
|
+
- id: service-key
|
|
184
|
+
type: apiKey
|
|
185
|
+
roles:
|
|
186
|
+
- integrations
|
|
187
|
+
properties:
|
|
188
|
+
keys:
|
|
189
|
+
- value:
|
|
190
|
+
_secret: SERVICE_API_KEY
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
A strategy caller carries the configured `roles` and `attributes` and its `auth_method` is the strategy type. A `jwt` strategy needs exactly one of `properties.secret` or `properties.jwksUri`, and a non-empty `algorithms` allowlist (which blocks `alg: none` downgrades). Its `properties.claimMapping` copies token claims onto the caller: `id` (default `sub`), `roles`, `attributes.<name>` into `_user.attributes`, and any other name onto `_user` itself. `system` is reserved, since `_user.system` marks the stand-in caller a [`CallApi` `caller`](/lowdefy-api#running-in-one-organization) names, and the build refuses a mapping for it.
|
|
194
|
+
|
|
195
|
+
## Captcha
|
|
196
|
+
|
|
197
|
+
`auth.captcha` protects auth endpoints with Cloudflare Turnstile. The `siteKey` is public (a plain string, never a `_secret`); the `secretKey` is a `_secret` reference. See the [Captcha block](/Captcha) for the client side.
|
|
198
|
+
|
|
199
|
+
## Rate limiting and account linking
|
|
200
|
+
|
|
201
|
+
- `auth.rateLimit` — brute-force protection, on by default (`enabled`, `window` seconds, `max`). Sign-in and sign-up allow 3 attempts per 10 seconds, and password-reset and verification emails 3 per minute. Limits count per client address: the connection's address on a self-hosted server, or the address a trusted proxy forwarded when the app lists its proxies in [`config.trustedProxies`](/docker#behind-a-reverse-proxy). `X-Forwarded-For` from anyone else is ignored.
|
|
202
|
+
- `auth.account.accountLinking` — link a new OAuth sign-in to an existing account by verified email. `trustedProviders` lists providers whose email claim you trust for linking. **This is unrelated to `provider.twoFactorTrusted`** — see [Two-Factor Authentication](/two-factor#trusting-an-oauth-provider).
|
|
203
|
+
|
|
204
|
+
## Mock User for Testing (Dev Server Only)
|
|
205
|
+
|
|
206
|
+
When developing and testing Lowdefy apps, you can bypass the login flow by configuring a mock user. This is useful for testing authenticated flows without going through OAuth login.
|
|
207
|
+
|
|
208
|
+
The mock user can be configured in three ways:
|
|
209
|
+
|
|
210
|
+
### CLI Flag
|
|
211
|
+
|
|
212
|
+
Pass `--mock-user` to `lowdefy dev` to start the server as a mock user for that run. Supply a JSON user object to set the identity and roles, or use the bare flag for a default user with no roles:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
lowdefy dev --mock-user '{"id":"test-user","email":"test@example.com","roles":["admin"]}'
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The flag sets `LOWDEFY_DEV_USER` for the dev server process, so it takes precedence over `auth.dev.mockUser` in the config file.
|
|
219
|
+
|
|
220
|
+
### Environment Variable
|
|
221
|
+
|
|
222
|
+
Set the `LOWDEFY_DEV_USER` environment variable to a JSON string containing the mock user object:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
LOWDEFY_DEV_USER='{"id":"test-user","email":"test@example.com","roles":["admin"]}'
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Config File
|
|
229
|
+
|
|
230
|
+
Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
|
|
231
|
+
|
|
232
|
+
###### Configure a mock user for development
|
|
233
|
+
```yaml
|
|
234
|
+
lowdefy: 7.0.0
|
|
235
|
+
|
|
236
|
+
auth:
|
|
237
|
+
providers:
|
|
238
|
+
- id: google
|
|
239
|
+
type: Google
|
|
240
|
+
properties:
|
|
241
|
+
clientId:
|
|
242
|
+
_secret: GOOGLE_CLIENT_ID
|
|
243
|
+
clientSecret:
|
|
244
|
+
_secret: GOOGLE_CLIENT_SECRET
|
|
245
|
+
dev:
|
|
246
|
+
mockUser:
|
|
247
|
+
id: test-user
|
|
248
|
+
email: test@example.com
|
|
249
|
+
name: Test User
|
|
250
|
+
roles:
|
|
251
|
+
- admin
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
When a mock user is configured:
|
|
255
|
+
- The environment variable takes precedence over the config file if both are set
|
|
256
|
+
- A warning is logged at dev server startup: "Mock user active - login bypassed"
|
|
257
|
+
- The mock user is injected as a pre-resolved caller — its `roles` are authoritative
|
|
258
|
+
- It can not carry `system`, which is reserved for the stand-in caller a bound `CallApi` names; the dev server refuses a mock user that sets it
|
|
259
|
+
- The `_user` operator returns values from the mock user, on the server and in the browser client — the dev server serves the mock session to both
|
|
260
|
+
- Protected pages are accessible based on the mock user's roles
|
|
261
|
+
- The dev server's headless renderer (used by the AI-agent screenshot and state-inspection tools) renders as the mock user, so it can capture pages with roles the default user lacks
|
|
262
|
+
|
|
263
|
+
> **Note:** Mock users only work with the development server (`lowdefy dev`). The production server ignores mock user configuration for security.
|
|
264
|
+
|
|
265
|
+
> **Note:** `dev.mockUser` bypasses the auth engine rather than exercising it, so [auth steps](/auth-steps) (which need the running auth engine) are unavailable under a mock user.
|
|
266
|
+
|
|
267
|
+
`auth.dev` needs no auth stack behind it. An `auth` block whose only key is `dev` is not an auth configuration: it demands no login method, no `secret` and no `database`, the app builds and runs signed out in production, and in the dev server the browser is the `dev.mockUser` caller. Adding any other `auth` key declares a real auth stack, and the build then requires a mechanism, a secret and (for a login method) a database as usual.
|
|
@@ -6,6 +6,30 @@ Providers are used to configure the identity providers that will be used to auth
|
|
|
6
6
|
|
|
7
7
|
Auth.js supports a large number of OAuth identity providers. During the OAuth flow, a user is redirected to a webpage hosted by the provider, where they usually authenticate using their credentials if not already signed in. They are then redirected back to the Lowdefy application, and the Lowdefy application interacts with the providers's API to verify the login and get the user details like name and email address.
|
|
8
8
|
|
|
9
|
+
### Trusting a GenericOAuth provider's email
|
|
10
|
+
|
|
11
|
+
A `GenericOAuth` provider marks a user's email as verified only when the issuer sends the `email_verified` claim as `true`. Some issuers never send the claim, so every user they sign in stays unverified and cannot accept an organization invitation. Set `trustEmail: true` on the provider to mark every user it signs in as verified, whatever the issuer sends (also when it sends `email_verified: false`). Users it signed in before are marked verified on their next sign-in:
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
auth:
|
|
15
|
+
providers:
|
|
16
|
+
- id: company-sso
|
|
17
|
+
type: GenericOAuth
|
|
18
|
+
properties:
|
|
19
|
+
discoveryUrl:
|
|
20
|
+
_secret: SSO_DISCOVERY_URL
|
|
21
|
+
clientId:
|
|
22
|
+
_secret: SSO_CLIENT_ID
|
|
23
|
+
clientSecret:
|
|
24
|
+
_secret: SSO_CLIENT_SECRET
|
|
25
|
+
scopes: [openid, profile, email]
|
|
26
|
+
trustEmail: true
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Only set `trustEmail` for an issuer that controls the emails it hands out. A verified email lets a sign-in through the provider link to an existing user with the same verified email, as it would for a provider listed in `auth.account.accountLinking.trustedProviders`. That is safe when the issuer controls its emails, since the issuer's user then owns the address. To stop all linking, set `auth.account.accountLinking.enabled: false`. That applies to every provider: a user who already has an account with the same email, through another provider or email and password, can then no longer sign in through this one.
|
|
30
|
+
|
|
31
|
+
With `session.cookieCache.enabled: true`, the session from the sign-in that marks an existing user verified still reads unverified until the cache expires (`session.cookieCache.maxAge`), so accepting an invitation straight after that sign-in can still be refused.
|
|
32
|
+
|
|
9
33
|
## Email Provider
|
|
10
34
|
|
|
11
35
|
Auth.js supports email login, where a link with a token is sent to the user's email address and the user can click on the link to log in (often called "magic links"). To use email authentication an Adapter must be configured, since the verification tokens need to be stored in a database.
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Auth Steps
|
|
2
|
+
|
|
3
|
+
Auth steps are routine steps that administer users, organizations and memberships — inviting a member, updating an app role, banning a user, creating an organization. They run **inside an `Api` or `InternalApi` endpoint routine**, not as client actions, because administering *other* people's memberships is a server operation that must be authorized against the caller, name its target organization explicitly, and be visible in a diff.
|
|
4
|
+
|
|
5
|
+
> A **client action** mutates the caller's *own* session and nothing else — `SetActiveOrganization`, `AcceptInvitation`, `LeaveOrganization`. Anything that reaches another person's membership is an auth **step** in a routine, which is what earns it the per-step authority floor below. See the [Auth Upgrade guide](/auth-upgrade#retired-client-actions) for the actions that became steps.
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
id: invite-member
|
|
9
|
+
type: Api
|
|
10
|
+
routine:
|
|
11
|
+
- id: invite
|
|
12
|
+
type: InviteMember
|
|
13
|
+
properties:
|
|
14
|
+
organizationId:
|
|
15
|
+
_user: organization_id
|
|
16
|
+
email:
|
|
17
|
+
_payload: email
|
|
18
|
+
appRoles:
|
|
19
|
+
_payload: roles
|
|
20
|
+
- ':return':
|
|
21
|
+
_step: invite
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## The authority model
|
|
25
|
+
|
|
26
|
+
Every auth step declares, in its own code, the authority it requires — and the engine's **authority floor** enforces that declaration mechanically before the step runs. This is not optional decoration: a step with no declared authority is a build/runtime error, so an app can never expose a member mutation by forgetting a check. The reason the floor exists in one place is that most steps go adapter-direct or through BetterAuth's admin plugin, whose check reads a single deployment-wide `user.role` field and **cannot** answer "is the caller an administrator of *this* organization". For those steps, the floor is the only authorization that can express per-organization authority.
|
|
27
|
+
|
|
28
|
+
A step declares one of three **scopes**.
|
|
29
|
+
|
|
30
|
+
### `org` — authorized against the caller's membership in the target organization
|
|
31
|
+
|
|
32
|
+
The common case. The floor:
|
|
33
|
+
|
|
34
|
+
1. **Resolves the target organization** (see below).
|
|
35
|
+
2. **Finds the caller's `member` row** in that organization and checks its role against the step's required **permissions**. The caller's authority is their membership in the *target* organization — an administrator of the team organization holds nothing in the customer organization.
|
|
36
|
+
3. For steps that write the deployment-wide `user` row, additionally requires the **target user** to be a member of that organization (`targetUser`), so org authority alone can never reach a user who is not the caller's business.
|
|
37
|
+
|
|
38
|
+
Permissions map to the organization tier via BetterAuth's organization access control: `owner` and `admin` are granted the member-management permissions out of the box; `member` holds none of them. A refused caller gets a `ConfigError` naming exactly what was required.
|
|
39
|
+
|
|
40
|
+
### `system` — caller-less, trusted runs only
|
|
41
|
+
|
|
42
|
+
A `system`-scoped step (`CreateOrganization`, `ListUsers`) has no organization to be authorized in, so a caller can never satisfy it. It runs **only** where the run itself is trusted — a caller-less system routine. Mark the step `system: true`, or run it from a system context (cron, a verified webhook, an auth hook):
|
|
43
|
+
|
|
44
|
+
```yaml
|
|
45
|
+
- id: create_org
|
|
46
|
+
type: CreateOrganization
|
|
47
|
+
system: true
|
|
48
|
+
properties:
|
|
49
|
+
name:
|
|
50
|
+
_payload: name
|
|
51
|
+
slug:
|
|
52
|
+
_payload: slug
|
|
53
|
+
userId:
|
|
54
|
+
_payload: ownerUserId
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### `caller` — acts on the caller's own records
|
|
58
|
+
|
|
59
|
+
A `caller`-scoped step (`RevokeMcpGrant`, `CreateMcpToken`, `RevokeMcpToken`, `LeaveOrganization`) acts only on rows the caller owns, so it needs no organization authority — but it is meaningless without a caller, and the system has no rows of its own. It requires a real caller and refuses `system: true`.
|
|
60
|
+
|
|
61
|
+
### Leaving an organization from a routine
|
|
62
|
+
|
|
63
|
+
`LeaveOrganization` ends the caller's own membership of the organization named by `organizationId`. The property is required: the step has no org scope, so nothing defaults it. The organization plugin's own checks run, so a caller who is not a member there, or who is its only owner, is refused. The refusal throws with the plugin's message, which the routine catches with `:try` to branch on:
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
id: leave
|
|
67
|
+
type: Api
|
|
68
|
+
routine:
|
|
69
|
+
- :try:
|
|
70
|
+
- id: leave
|
|
71
|
+
type: LeaveOrganization
|
|
72
|
+
properties:
|
|
73
|
+
organizationId:
|
|
74
|
+
_payload: organization_id
|
|
75
|
+
:catch:
|
|
76
|
+
- :return:
|
|
77
|
+
refused:
|
|
78
|
+
message:
|
|
79
|
+
_error: message
|
|
80
|
+
# Runs only when the leave went through.
|
|
81
|
+
- :return:
|
|
82
|
+
success: true
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
On success the step returns the member row it removed. The caller's session still names the organization they left as active, so their next request resolves unauthenticated: follow the call on the page with `SetActiveOrganization` for another organization, or with `Logout`. The `LeaveOrganization` client action leaves the session's active organization from the browser and clears it; use it when nothing else has to happen in the same request as the leave. Step and action types resolve from separate maps, so the shared name is never ambiguous.
|
|
86
|
+
|
|
87
|
+
## `system: true` — the two doors to a caller-less run
|
|
88
|
+
|
|
89
|
+
The floor's caller requirement passes on either of two independent doors:
|
|
90
|
+
|
|
91
|
+
- a **run-level** system context (`context.system === true`) — a trusted, caller-less run such as a cron endpoint, an auth hook, or a verified webhook; or
|
|
92
|
+
- a **per-step** `system: true` on a single step in an otherwise user-driven run — a waiver visible in the diff, for the one privileged operation in a member-facing routine.
|
|
93
|
+
|
|
94
|
+
Either door makes the step act caller-less **as the system**, bypassing the org/permission checks. That is an explicit trust decision, not attribution — use it deliberately.
|
|
95
|
+
|
|
96
|
+
## How the target organization is resolved
|
|
97
|
+
|
|
98
|
+
For every `org`-scoped step the floor resolves the target organization once, and the step writes into the *same* one it authorized — they cannot drift. The rule:
|
|
99
|
+
|
|
100
|
+
1. An explicit **`organizationId`** property always wins. This is what a multi-organization admin routine passes, and it is what lets a session pinned to the team organization administer the customer organization.
|
|
101
|
+
2. `ListMembers` also accepts an **`organizationSlug`**, resolved to an id here.
|
|
102
|
+
3. Otherwise the **pinned** organization is the default — **but under `policy: tenant` there is no pinned organization**, so an omitted `organizationId` is a runtime error naming the fix. Under `tenant`, always pass `organizationId` explicitly.
|
|
103
|
+
|
|
104
|
+
## `targetUser` and `selfTargetExempt`
|
|
105
|
+
|
|
106
|
+
Two refinements the floor reads from a step's declaration:
|
|
107
|
+
|
|
108
|
+
- **`targetUser`** names the property holding the id of the user being acted on. Steps that write the shared `user` row declare it, so the floor can require that user to be a member of the target organization. An absent target-user property is the step's own required-property error, not the floor's.
|
|
109
|
+
- **`selfTargetExempt`** lets a caller act on **their own** row without holding org authority — this is what makes `UpdateUserProfile` a self-service "save my profile" step as well as an admin one. When the named property equals the caller's own id, the org authority check is skipped.
|
|
110
|
+
|
|
111
|
+
## Step reference
|
|
112
|
+
|
|
113
|
+
Scope, required permission, and target for every auth step. Permissions are checked against the caller's `member.role` in the target organization; `owner`/`admin` hold them by default.
|
|
114
|
+
|
|
115
|
+
| Step | Scope | Permission | Target | What it does |
|
|
116
|
+
| ---- | ----- | ---------- | ------ | ------------ |
|
|
117
|
+
| `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. |
|
|
118
|
+
| `CancelInvitation` | org | `invitation: [cancel]` | — | Cancel a pending invitation. |
|
|
119
|
+
| `ListMembers` | org | `member: [list]` | — | List members of the organization (accepts `organizationSlug`). |
|
|
120
|
+
| `RemoveMember` | org | `member: [delete]` | — | Remove a member from the organization. |
|
|
121
|
+
| `UpdateMemberRoles` | org | `member: [update]` | — | Set the membership's **app roles** (`appRoles` array; empty clears). |
|
|
122
|
+
| `UpdateMemberOrgRole` | org | `member: [update]` | — | Set the **org tier** (`owner`/`admin`/`member`). |
|
|
123
|
+
| `UpdateMemberAttributes` | org | `member: [update]` | — | Set the membership's per-organization attributes. |
|
|
124
|
+
| `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
|
|
125
|
+
| `RevokeOrgMcpToken` | org | `member: [update]` | — | Switch off any [member token](/mcp-oauth#tokens-for-scripts) in the organization (`id`). |
|
|
126
|
+
| `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy). Self-service save is exempt. |
|
|
127
|
+
| `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
|
|
128
|
+
| `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
|
|
129
|
+
| `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
|
|
130
|
+
| `DeleteUser` | org | `user: [delete]` | `userId` | Delete a user. |
|
|
131
|
+
| `RevokeUserSessions` | org | `session: [revoke]` | `userId` | Sign a user out of all sessions. |
|
|
132
|
+
| `ResetUserTwoFactor` | org | `user: [reset-two-factor]` | `userId` | Clear a user's two-factor enrolment and trust-device records. |
|
|
133
|
+
| `RevokeUserPasskeys` | org | `user: [revoke-passkeys]` | `userId` | Remove a user's passkeys (`passkeyId` to target one). |
|
|
134
|
+
| `CreateOrganization` | system | — | — | Create an organization (tenant provisioning). Needs `userId`, or `name`+`slug` for creator-less provisioning. |
|
|
135
|
+
| `ListUsers` | system | — | — | List every user in the deployment. |
|
|
136
|
+
| `LeaveOrganization` | caller | — | — | End the caller's own membership of the named organization (`organizationId`, required). [Leaving from a routine](#leaving-an-organization-from-a-routine). |
|
|
137
|
+
| `RevokeMcpGrant` | caller | — | — | Revoke the calling assistant's own [MCP grant](/mcp-oauth#switching-organization-from-the-assistant). |
|
|
138
|
+
| `CreateMcpToken` | caller | — | — | Create a [member token](/mcp-oauth#tokens-for-scripts) for the caller in their active organization (`name`, `expiresInDays` or `null`). Session callers only. |
|
|
139
|
+
| `RevokeMcpToken` | caller | — | — | Switch off one of the caller's own [member tokens](/mcp-oauth#tokens-for-scripts) (`id`). |
|
|
140
|
+
|
|
141
|
+
The two role tiers a member carries — the `owner`/`admin`/`member` org tier and the app's own role strings — are explained in [Organizations & Multi-Tenancy](/organizations#the-owner-admin-member-tier-vs-app-roles). Recovering a user who lost their second factor is a worked routine on the [Two-Factor Authentication](/two-factor#recovering-a-user-who-has-lost-their-factor) page.
|
|
@@ -8,16 +8,21 @@ The `Login` action is used to start the user login flow. If only one OAuth provi
|
|
|
8
8
|
|
|
9
9
|
The authorization url usually hosts a page where the user can input their credentials. After the user has logged in successfully, the user is redirected to the `/api/auth/callback/<provider_id>` route in the Lowdefy app, where the rest of the authorization code flow is completed. This URL usually needs to be configured in the identity provider's settings.
|
|
10
10
|
|
|
11
|
-
The `callbackUrl`
|
|
11
|
+
The `callbackUrl` parameter of the Login action specifies where the user lands after login is complete. Three sources are consulted, in order: the `callbackUrl` param, then the `?callbackUrl=` query parameter Lowdefy sets when it redirects an unauthenticated user to the sign-in page, then the app's home page. If none resolves the action throws, rather than staying silently on the sign-in page.
|
|
12
|
+
|
|
13
|
+
In a protected app a signed-out visitor is sent to the sign-in page for every URL, present or absent, so a `404` means you are signed in — see [Page and API existence](/auth-upgrade#page-and-api-existence-is-no-longer-observable-before-you-sign-in).
|
|
14
|
+
|
|
15
|
+
To sign in without navigating at all - a login form in a modal, or an embedded panel - set `callbackUrl: false`. This is not valid for magic-link or social/OAuth sign-in, which redirect through a hop Lowdefy does not control.
|
|
12
16
|
|
|
13
17
|
The parameters are:
|
|
14
18
|
- `authUrl: object`:
|
|
15
19
|
- `urlQuery: object`: Query parameters to set for the authorization URL.
|
|
16
|
-
- `callbackUrl: object`:
|
|
20
|
+
- `callbackUrl: object | false`: Set to `false` to sign in without navigating. As an object:
|
|
17
21
|
- `home: boolean`: Redirect to the home page after the login flow is complete.
|
|
18
22
|
- `pageId: string`: The pageId of the page to redirect to after the login flow is complete.
|
|
19
|
-
- `url: string`: The URL to redirect to after the login flow is complete.
|
|
23
|
+
- `url: string`: The URL to redirect to after the login flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
|
|
20
24
|
- `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
|
|
25
|
+
- `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
|
|
21
26
|
- `providerId: string`: The ID of the provider that should be used for login. If not set and only one provider is configured the configured provider will be used. Else the user will be redirected to a sign in page where they can choose a provider.
|
|
22
27
|
|
|
23
28
|
## Examples
|
|
@@ -91,18 +96,165 @@ events:
|
|
|
91
96
|
screen_hint: signup
|
|
92
97
|
```
|
|
93
98
|
|
|
99
|
+
## Magic link sign-in
|
|
100
|
+
|
|
101
|
+
`Login` with `magicLink: true` emails the user a sign-in link. By default that link points straight at Better Auth's verify endpoint, which consumes the single-use token on the first `GET` of the URL.
|
|
102
|
+
|
|
103
|
+
That is a problem in corporate inboxes. Mail security products — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetch every link in a message as it is delivered, so the scanner spends the token minutes before the person clicks, and the person lands on the error page with `INVALID_TOKEN`.
|
|
104
|
+
|
|
105
|
+
Set [`auth.authPages.magicLink`](/auth-configuration#auth-pages) to a page in your app to close that gap. The email then links to your page, carrying the token and the callback destinations on its URL query, and a [`MagicLinkVerify`](/MagicLinkVerify) action on a **button click** walks to the verify endpoint. Fetching the landing page does nothing, so a scanner cannot consume the token.
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
lowdefy: {{ version }}
|
|
109
|
+
auth:
|
|
110
|
+
magicLink:
|
|
111
|
+
enabled: true
|
|
112
|
+
authPages:
|
|
113
|
+
magicLink: /magic-link
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```yaml
|
|
117
|
+
id: magic-link
|
|
118
|
+
type: PageHeaderMenu
|
|
119
|
+
blocks:
|
|
120
|
+
- id: content
|
|
121
|
+
type: Box
|
|
122
|
+
blocks:
|
|
123
|
+
- id: title
|
|
124
|
+
type: Title
|
|
125
|
+
properties:
|
|
126
|
+
content: Sign in
|
|
127
|
+
level: 3
|
|
128
|
+
- id: description
|
|
129
|
+
type: Paragraph
|
|
130
|
+
properties:
|
|
131
|
+
content: Click the button below to finish signing in.
|
|
132
|
+
- id: verify_button
|
|
133
|
+
type: Button
|
|
134
|
+
properties:
|
|
135
|
+
title: Sign in
|
|
136
|
+
events:
|
|
137
|
+
onClick:
|
|
138
|
+
- id: verify
|
|
139
|
+
type: MagicLinkVerify
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The landing page must be reachable while signed out, so add it to `auth.pages.public`.
|
|
143
|
+
|
|
144
|
+
Do **not** run `MagicLinkVerify` in the page's `onMount`, and do not auto-redirect to the verify endpoint. Some scanning sandboxes render the page and execute its JavaScript, so an automatic verify hands the token back to the scanner and you are no better off than linking at the endpoint directly. The whole protection is that a human has to click.
|
|
145
|
+
|
|
146
|
+
The action needs no parameters: the token and the `callbackURL`, `newUserCallbackURL` and `errorCallbackURL` values are read from the landing page's own URL query, which the email put there. Pass parameters only to override them.
|
|
147
|
+
|
|
148
|
+
## Email code sign-in
|
|
149
|
+
|
|
150
|
+
With `auth.emailOTP` enabled the app can sign a person in with a code emailed to them. Unlike a magic link, the code is typed into the tab they started from — so it survives corporate mail security that pre-fetches links (and consumes the single-use link token), and it works when the email is read on another device.
|
|
151
|
+
|
|
152
|
+
Two actions drive it:
|
|
153
|
+
|
|
154
|
+
- [`EmailOtpSend`](/EmailOtpSend) sends the code to an email address.
|
|
155
|
+
- [`EmailOtpVerify`](/EmailOtpVerify) signs the person in with the code they typed.
|
|
156
|
+
|
|
157
|
+
`EmailOtpVerify` lands the user through the same three sources as `Login`: the `callbackUrl` param, then the `?callbackUrl=` query, then the app's home page. `callbackUrl: false` verifies without navigating — it is a plain JSON sign-in with no redirect hop, so staying put is valid here.
|
|
158
|
+
|
|
159
|
+
### With magic link, one email carries both
|
|
160
|
+
|
|
161
|
+
When `auth.magicLink` is enabled alongside `auth.emailOTP`, the magic-link email also carries the code, so one email serves both paths. Keep using `Login` with `magicLink: true` to send it — no change is needed — and offer `EmailOtpVerify` on the same page for people whose link does not work. `EmailOtpSend` is then only needed for a code-only page, where no link is offered at all.
|
|
162
|
+
|
|
163
|
+
###### A sign-in page offering a code:
|
|
164
|
+
```yaml
|
|
165
|
+
id: email-code-login
|
|
166
|
+
type: Box
|
|
167
|
+
blocks:
|
|
168
|
+
- id: email
|
|
169
|
+
type: TextInput
|
|
170
|
+
required: true
|
|
171
|
+
properties:
|
|
172
|
+
title: Email
|
|
173
|
+
- id: send_code
|
|
174
|
+
type: Button
|
|
175
|
+
properties:
|
|
176
|
+
title: Send code
|
|
177
|
+
events:
|
|
178
|
+
onClick:
|
|
179
|
+
- id: validate
|
|
180
|
+
type: Validate
|
|
181
|
+
params:
|
|
182
|
+
regex: ^email$
|
|
183
|
+
- id: send
|
|
184
|
+
type: EmailOtpSend
|
|
185
|
+
params:
|
|
186
|
+
email:
|
|
187
|
+
_state: email
|
|
188
|
+
- id: sent
|
|
189
|
+
type: DisplayMessage
|
|
190
|
+
params:
|
|
191
|
+
content: Check your email for the sign-in code.
|
|
192
|
+
- id: otp
|
|
193
|
+
type: TextInput
|
|
194
|
+
properties:
|
|
195
|
+
title: Sign-in code
|
|
196
|
+
- id: sign_in
|
|
197
|
+
type: Button
|
|
198
|
+
properties:
|
|
199
|
+
title: Sign in
|
|
200
|
+
events:
|
|
201
|
+
onClick:
|
|
202
|
+
- id: verify
|
|
203
|
+
type: EmailOtpVerify
|
|
204
|
+
params:
|
|
205
|
+
email:
|
|
206
|
+
_state: email
|
|
207
|
+
otp:
|
|
208
|
+
_state: otp
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
An expired, mistyped or already-used code is the auth server rejecting the attempt, not an app fault: the action throws a `UserError`, so `onClick` `catch` actions run and the message displays, but nothing is reported to the server.
|
|
212
|
+
|
|
213
|
+
## SMS sign-in
|
|
214
|
+
|
|
215
|
+
`PhoneNumberVerify` completes a sign-in with an SMS code, and lands the user through the same three sources as `Login`: the `callbackUrl` param, then the `?callbackUrl=` query, then the app's home page. `callbackUrl: false` verifies without navigating.
|
|
216
|
+
|
|
217
|
+
Two modes are exempt, because neither ends with the user arriving somewhere new:
|
|
218
|
+
|
|
219
|
+
- `disableSession: true` creates no session to arrive with.
|
|
220
|
+
- `updatePhoneNumber: true` is a signed-in user confirming a new number. They already had a session, and the confirmation usually runs in a modal a navigation would yank them out of.
|
|
221
|
+
|
|
222
|
+
### Carrying the destination to a separate SMS form
|
|
223
|
+
|
|
224
|
+
The `?callbackUrl=` query is read from the page the action runs on, and the unauthenticated bounce puts it on `authPages.signIn`. If your SMS form lives on its own page, the link that gets the user there has to carry the parameter, or the destination falls back to the home page:
|
|
225
|
+
|
|
226
|
+
```yaml
|
|
227
|
+
- id: to_phone_login
|
|
228
|
+
type: Link
|
|
229
|
+
params:
|
|
230
|
+
pageId: phone-login
|
|
231
|
+
urlQuery:
|
|
232
|
+
_if:
|
|
233
|
+
test:
|
|
234
|
+
_eq:
|
|
235
|
+
- _url_query: callbackUrl
|
|
236
|
+
- null
|
|
237
|
+
then: null
|
|
238
|
+
else:
|
|
239
|
+
callbackUrl:
|
|
240
|
+
_url_query: callbackUrl
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
The `_if` is what keeps a user who reached the sign-in page directly from being sent to `/phone-login?callbackUrl=null` — `urlQuery` serialises a null value rather than dropping the key.
|
|
244
|
+
|
|
94
245
|
## Logout
|
|
95
246
|
|
|
96
247
|
When the `Logout` action is called, the user data and authorization cookies are cleared by the app.
|
|
97
248
|
|
|
98
|
-
The `callbackUrl`
|
|
249
|
+
The `callbackUrl` parameter of the Logout action specifies where the user lands after logout is complete. Unlike the `Login` action it has no default and does not read the `?callbackUrl=` query: with no `callbackUrl` the page is reloaded and the server re-applies the page's auth rules, which sends a signed-out user off a protected page to the sign-in page.
|
|
99
250
|
|
|
100
251
|
The parameters are:
|
|
101
252
|
- `callbackUrl: object`:
|
|
102
|
-
- `home: boolean`: Redirect to the home page after the
|
|
103
|
-
- `pageId: string`: The pageId of the page to redirect to after the
|
|
104
|
-
- `url: string`: The URL to redirect to after the
|
|
105
|
-
- `urlQuery: object`: The urlQuery to set for the page the user is redirected to after
|
|
253
|
+
- `home: boolean`: Redirect to the home page after the logout flow is complete.
|
|
254
|
+
- `pageId: string`: The pageId of the page to redirect to after the logout flow is complete.
|
|
255
|
+
- `url: string`: The URL to redirect to after the logout flow is complete. An absolute URL is not `basePath`-prefixed, so it can be an external logout landing page.
|
|
256
|
+
- `urlQuery: object`: The urlQuery to set for the page the user is redirected to after logout.
|
|
257
|
+
- `pathParams: object`: Values for the placeholders in the destination page's [`path`](/page-paths), by placeholder name.
|
|
106
258
|
- `redirect: boolean`: If set to `false` the user session will be cleared, but the page will not be reloaded.
|
|
107
259
|
|
|
108
260
|
|