@lumoauth/react 1.0.0 → 1.2.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 +421 -569
- package/dist/index.d.mts +25 -17
- package/dist/index.d.ts +25 -17
- package/dist/index.js +44 -17
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +44 -17
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,791 +1,643 @@
|
|
|
1
1
|
# @lumoauth/react
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@lumoauth/react)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
|
|
6
|
+
`@lumoauth/react` adds LumoAuth sign-in, user menus and access checks to a React app. You wrap
|
|
7
|
+
the app in `<LumoAuthProvider>`, then use ready-made components such as `<SignIn>`,
|
|
8
|
+
`<UserButton>` and `<Protect>`, or hooks such as `useAuth()` and `usePermission()`. Users sign
|
|
9
|
+
in with OAuth 2.0 and PKCE by default.
|
|
10
|
+
|
|
11
|
+
It is part of the [LumoAuth JavaScript SDK](../../README.md), and it is built on
|
|
12
|
+
[`@lumoauth/client`](../client/README.md).
|
|
13
|
+
|
|
14
|
+
## Contents
|
|
15
|
+
|
|
16
|
+
- [Is this the right package?](#is-this-the-right-package)
|
|
17
|
+
- [Requirements](#requirements)
|
|
18
|
+
- [Install](#install)
|
|
19
|
+
- [Quick start](#quick-start)
|
|
20
|
+
- [Core concepts](#core-concepts)
|
|
21
|
+
- [Configuration](#configuration)
|
|
22
|
+
- [Components](#components)
|
|
23
|
+
- [Sign-in and sign-up](#sign-in-and-sign-up)
|
|
24
|
+
- [User](#user)
|
|
25
|
+
- [Access checks](#access-checks)
|
|
26
|
+
- [Show content by sign-in state](#show-content-by-sign-in-state)
|
|
27
|
+
- [Unstyled buttons](#unstyled-buttons)
|
|
28
|
+
- [Hooks](#hooks)
|
|
29
|
+
- [Common patterns](#common-patterns)
|
|
30
|
+
- [Appearance](#appearance)
|
|
31
|
+
- [Sign-in strategies](#sign-in-strategies)
|
|
32
|
+
- [Errors](#errors)
|
|
33
|
+
- [API reference](#api-reference)
|
|
34
|
+
- [Troubleshooting](#troubleshooting)
|
|
35
|
+
- [Versioning and compatibility](#versioning-and-compatibility)
|
|
36
|
+
- [Related packages](#related-packages)
|
|
37
|
+
- [Licence](#licence)
|
|
38
|
+
|
|
39
|
+
## Is this the right package?
|
|
40
|
+
|
|
41
|
+
| You are building… | Use |
|
|
42
|
+
|---|---|
|
|
43
|
+
| A React 18+ single-page app (Vite, Remix, React Router and similar) | **This package** |
|
|
44
|
+
| A Next.js App Router app | [`@lumoauth/nextjs`](../nextjs/README.md). It re-exports everything here and adds server-side sessions. |
|
|
45
|
+
| An app in Vue, Svelte, Angular or plain JavaScript | [`@lumoauth/client`](../client/README.md) |
|
|
46
|
+
| Server code | [`@lumoauth/backend`](../backend/README.md) or [`@lumoauth/express`](../express/README.md) |
|
|
47
|
+
|
|
48
|
+
## Requirements
|
|
49
|
+
|
|
50
|
+
- React and React DOM 18 or newer (peer dependencies)
|
|
51
|
+
- Node 18 or newer for your build
|
|
52
|
+
- A LumoAuth organization and a **public** OAuth client with PKCE. Register your callback URL as a
|
|
53
|
+
redirect URI, and add your app's origin to the client's allowed origins.
|
|
54
|
+
|
|
55
|
+
## Install
|
|
20
56
|
|
|
21
57
|
```bash
|
|
22
|
-
npm install @lumoauth/react
|
|
58
|
+
npm install @lumoauth/react
|
|
23
59
|
```
|
|
24
60
|
|
|
25
|
-
|
|
61
|
+
`@lumoauth/client` is installed with it and re-exported as `LumoAuth`, so one install is enough.
|
|
62
|
+
|
|
63
|
+
## Quick start
|
|
26
64
|
|
|
27
|
-
|
|
65
|
+
**1. Wrap the app in the provider.**
|
|
28
66
|
|
|
29
67
|
```tsx
|
|
30
68
|
import { LumoAuthProvider } from '@lumoauth/react';
|
|
31
69
|
|
|
32
|
-
function App() {
|
|
70
|
+
export function App() {
|
|
33
71
|
return (
|
|
34
72
|
<LumoAuthProvider
|
|
35
|
-
domain="https://
|
|
73
|
+
domain="https://app.lumoauth.dev" // EU region: https://eu.app.lumoauth.dev
|
|
36
74
|
orgId="acme-corp"
|
|
37
75
|
clientId="your-client-id"
|
|
38
76
|
afterSignInUrl="/dashboard"
|
|
39
|
-
afterSignOutUrl="/"
|
|
40
77
|
>
|
|
41
|
-
<
|
|
78
|
+
<Routes />
|
|
42
79
|
</LumoAuthProvider>
|
|
43
80
|
);
|
|
44
81
|
}
|
|
45
82
|
```
|
|
46
83
|
|
|
47
|
-
|
|
84
|
+
**2. Add a callback page.** By default the provider sends users back to
|
|
85
|
+
`<your origin>/auth/callback`. Mount `<AuthCallback>` on that route:
|
|
48
86
|
|
|
49
87
|
```tsx
|
|
50
88
|
import { AuthCallback } from '@lumoauth/react';
|
|
51
89
|
|
|
52
|
-
|
|
53
|
-
function CallbackPage() {
|
|
90
|
+
export function CallbackPage() {
|
|
54
91
|
return <AuthCallback afterSignInUrl="/dashboard" />;
|
|
55
92
|
}
|
|
56
93
|
```
|
|
57
94
|
|
|
58
|
-
|
|
95
|
+
**3. Show a sign-in button or the user menu.**
|
|
59
96
|
|
|
60
97
|
```tsx
|
|
61
|
-
import { SignedIn, SignedOut,
|
|
98
|
+
import { SignedIn, SignedOut, SignInButton, UserButton } from '@lumoauth/react';
|
|
62
99
|
|
|
63
|
-
function Header() {
|
|
100
|
+
export function Header() {
|
|
64
101
|
return (
|
|
65
102
|
<nav>
|
|
66
|
-
<SignedOut>
|
|
67
|
-
|
|
68
|
-
</SignedOut>
|
|
69
|
-
<SignedIn>
|
|
70
|
-
<UserButton showName />
|
|
71
|
-
</SignedIn>
|
|
103
|
+
<SignedOut><SignInButton>Sign in</SignInButton></SignedOut>
|
|
104
|
+
<SignedIn><UserButton showName /></SignedIn>
|
|
72
105
|
</nav>
|
|
73
106
|
);
|
|
74
107
|
}
|
|
75
108
|
```
|
|
76
109
|
|
|
77
|
-
|
|
110
|
+
**4. Show content only to users who hold a permission.**
|
|
78
111
|
|
|
79
|
-
|
|
112
|
+
```tsx
|
|
113
|
+
import { Protect } from '@lumoauth/react';
|
|
80
114
|
|
|
81
|
-
|
|
115
|
+
<Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
|
|
116
|
+
<AdminPanel />
|
|
117
|
+
</Protect>
|
|
118
|
+
```
|
|
82
119
|
|
|
83
|
-
|
|
120
|
+
## Core concepts
|
|
84
121
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
| `orgId` | `string` | **required** | Your organization ID |
|
|
89
|
-
| `clientId` | `string` | **required** | OAuth client ID |
|
|
90
|
-
| `authStrategy` | `'pkce' \| 'password'` | `'pkce'` | Authentication method |
|
|
91
|
-
| `redirectUri` | `string` | `origin + '/auth/callback'` | OAuth callback URL |
|
|
92
|
-
| `afterSignInUrl` | `string` | `'/'` | Redirect after sign-in |
|
|
93
|
-
| `afterSignUpUrl` | `string` | — | Redirect after sign-up |
|
|
94
|
-
| `afterSignOutUrl` | `string` | `'/'` | Redirect after sign-out |
|
|
122
|
+
**The provider holds the session.** `<LumoAuthProvider>` signs the user in, stores the tokens,
|
|
123
|
+
refreshes the access token before it expires, and shares the session across tabs. Every component
|
|
124
|
+
and hook reads from it, so the provider must wrap them.
|
|
95
125
|
|
|
96
|
-
|
|
126
|
+
**Checks run as the signed-in user.** `usePermission`, `useZanzibar`, `useAbac` and `<Protect>`
|
|
127
|
+
call LumoAuth with the user's access token. They hide content in the browser, but they do not
|
|
128
|
+
protect data. Your API must check access again on the server.
|
|
97
129
|
|
|
98
|
-
|
|
130
|
+
**Scopes.** The provider requests `openid profile email` at sign-in unless you pass a `scope`
|
|
131
|
+
prop. Permission and relationship checks need nothing more. ABAC checks need `abac:read`, and
|
|
132
|
+
listing the user's permissions needs `authz:read`. Add them to `scope`, and allow them on the
|
|
133
|
+
OAuth client:
|
|
99
134
|
|
|
100
|
-
|
|
135
|
+
```tsx
|
|
136
|
+
<LumoAuthProvider
|
|
137
|
+
domain="https://app.lumoauth.dev"
|
|
138
|
+
orgId="acme-corp"
|
|
139
|
+
clientId="client_…"
|
|
140
|
+
scope="openid profile email abac:read authz:read"
|
|
141
|
+
>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The full scope table is in the [client README](../client/README.md#scopes).
|
|
101
145
|
|
|
102
|
-
|
|
146
|
+
## Configuration
|
|
147
|
+
|
|
148
|
+
`<LumoAuthProvider>` props:
|
|
149
|
+
|
|
150
|
+
| Prop | Type | Default | Description |
|
|
151
|
+
|---|---|---|---|
|
|
152
|
+
| `domain` | `string` | required | Root URL of LumoAuth |
|
|
153
|
+
| `orgId` | `string` | required | Organization slug |
|
|
154
|
+
| `clientId` | `string` | required | OAuth client ID |
|
|
155
|
+
| `redirectUri` | `string` | `<origin>/auth/callback` | Callback URL. It must be registered on the OAuth client. |
|
|
156
|
+
| `scope` | `string` | `'openid profile email'` | Space-separated scopes for sign-in and sign-up. Add `abac:read` for `useAbac` and `<Protect abac>`, and `authz:read` for `listSlugs()`. The OAuth client must allow each scope. |
|
|
157
|
+
| `afterSignInUrl` | `string` | `'/'` | Where `<AuthCallback>` sends the user after sign-in |
|
|
158
|
+
| `afterSignUpUrl` | `string` | none | Where to go after sign-up |
|
|
159
|
+
| `afterSignOutUrl` | `string` | `'/'` | Where to go after sign-out. Register it as a post-logout redirect URI on the client. |
|
|
160
|
+
| `authStrategy` | `'pkce' \| 'password'` | `'pkce'` | See [Sign-in strategies](#sign-in-strategies) |
|
|
161
|
+
| `storage` | `TokenStorage` | `sessionStorage` in a browser, memory on a server | Where tokens are stored. Import an adapter from `@lumoauth/client`. |
|
|
162
|
+
| `crossTab` | `boolean` | `true` | Share the session across tabs. One tab does each refresh, and the others receive the result. |
|
|
163
|
+
| `children` | `ReactNode` | required | Your app |
|
|
164
|
+
|
|
165
|
+
**Where tokens are stored.** The default, `sessionStorage`, keeps one session per tab and clears
|
|
166
|
+
it when the tab closes. `localStorageAdapter()` shares the session across tabs and browser
|
|
167
|
+
restarts. `cookieStorageAdapter()` keeps tokens in an httpOnly cookie that scripts cannot read,
|
|
168
|
+
which is the only option that protects them from cross-site scripting. It needs a same-origin
|
|
169
|
+
server that serves a session endpoint, such as the one in `@lumoauth/nextjs`. The
|
|
170
|
+
[client README](../client/README.md#choose-where-tokens-are-stored) compares the adapters.
|
|
103
171
|
|
|
104
172
|
```tsx
|
|
105
|
-
import {
|
|
173
|
+
import { localStorageAdapter } from '@lumoauth/client';
|
|
106
174
|
|
|
107
|
-
<
|
|
108
|
-
afterSignInUrl="/dashboard"
|
|
109
|
-
signUpUrl="/sign-up"
|
|
110
|
-
appearance={{ theme: 'dark' }}
|
|
111
|
-
/>
|
|
175
|
+
<LumoAuthProvider domain={domain} orgId={orgId} clientId={clientId} storage={localStorageAdapter()}>
|
|
112
176
|
```
|
|
113
177
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
| `afterSignInUrl` | `string` | Redirect after sign-in |
|
|
117
|
-
| `signUpUrl` | `string` | Link to sign-up page |
|
|
118
|
-
| `appearance` | `AppearanceProps` | Theme/style overrides |
|
|
178
|
+
Create the adapter once, outside the component, or with `useMemo`. A new adapter on each render
|
|
179
|
+
rebuilds the session.
|
|
119
180
|
|
|
120
|
-
|
|
181
|
+
## Components
|
|
121
182
|
|
|
122
|
-
|
|
183
|
+
### Sign-in and sign-up
|
|
123
184
|
|
|
124
|
-
|
|
125
|
-
|
|
185
|
+
**`<SignIn>`** renders a sign-in card. In PKCE mode it shows social buttons, if you list any, and
|
|
186
|
+
a button that redirects to the LumoAuth sign-in page. In password mode it shows an email and
|
|
187
|
+
password form.
|
|
126
188
|
|
|
127
|
-
|
|
189
|
+
```tsx
|
|
190
|
+
<SignIn afterSignInUrl="/dashboard" signUpUrl="/sign-up" socialProviders={['google', 'github']} />
|
|
128
191
|
```
|
|
129
192
|
|
|
130
|
-
|
|
193
|
+
| Prop | Type | Description |
|
|
194
|
+
|---|---|---|
|
|
195
|
+
| `afterSignInUrl` | `string` | Where to go after sign-in |
|
|
196
|
+
| `signUpUrl` | `string` | Link to your sign-up page |
|
|
197
|
+
| `socialProviders` | `string[]` | Providers to show. The default is `[]`. Each button sends the user straight to that provider. If the organization has not set the provider up, the user sees the LumoAuth sign-in page instead. Icons are included for `google`, `github`, `microsoft` and `apple`. |
|
|
198
|
+
| `appearance` | `AppearanceProps` | See [Appearance](#appearance) |
|
|
199
|
+
|
|
200
|
+
The SDK has no default list of providers. An unauthenticated page cannot read which providers
|
|
201
|
+
the organization has turned on, so you list them yourself.
|
|
131
202
|
|
|
132
|
-
|
|
203
|
+
**`<SignUp>`** renders a sign-up card. In PKCE mode it sends the user to the LumoAuth registration
|
|
204
|
+
page. Password mode has no inline registration, because LumoAuth has no JSON registration
|
|
205
|
+
endpoint.
|
|
133
206
|
|
|
134
207
|
```tsx
|
|
135
|
-
|
|
208
|
+
<SignUp afterSignUpUrl="/onboarding" signInUrl="/sign-in" />
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**`<AuthCallback>`** finishes sign-in on your callback route. It checks the `state`, exchanges the
|
|
212
|
+
code for tokens, loads the user and redirects.
|
|
136
213
|
|
|
137
|
-
|
|
214
|
+
```tsx
|
|
138
215
|
<AuthCallback
|
|
139
216
|
afterSignInUrl="/dashboard"
|
|
140
|
-
loading={<
|
|
141
|
-
error={(
|
|
217
|
+
loading={<Spinner />}
|
|
218
|
+
error={(message) => <ErrorCard message={message} />}
|
|
142
219
|
/>
|
|
143
220
|
```
|
|
144
221
|
|
|
145
222
|
| Prop | Type | Description |
|
|
146
|
-
|
|
147
|
-
| `afterSignInUrl` | `string` |
|
|
148
|
-
| `loading` | `ReactNode` |
|
|
149
|
-
| `error` | `ReactNode \| (
|
|
150
|
-
|
|
151
|
-
---
|
|
223
|
+
|---|---|---|
|
|
224
|
+
| `afterSignInUrl` | `string` | Where to go on success. Falls back to the provider's `afterSignInUrl`, then `/`. |
|
|
225
|
+
| `loading` | `ReactNode` | Shown during the exchange |
|
|
226
|
+
| `error` | `ReactNode \| (message: string) => ReactNode` | Shown when sign-in fails |
|
|
152
227
|
|
|
153
|
-
|
|
228
|
+
### User
|
|
154
229
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
Avatar button with a dropdown menu for account management and sign-out. Only visible when signed in.
|
|
230
|
+
**`<UserButton>`** shows the user's avatar with a menu for the account and sign-out. It renders
|
|
231
|
+
nothing when nobody is signed in.
|
|
158
232
|
|
|
159
233
|
```tsx
|
|
160
|
-
import { UserButton } from '@lumoauth/react';
|
|
161
|
-
|
|
162
234
|
<UserButton showName afterSignOutUrl="/" />
|
|
163
235
|
```
|
|
164
236
|
|
|
165
237
|
| Prop | Type | Default | Description |
|
|
166
|
-
|
|
167
|
-
| `showName` | `boolean` | `false` | Show display name next to avatar |
|
|
168
|
-
| `afterSignOutUrl` | `string` | `'/'` |
|
|
169
|
-
| `appearance` | `AppearanceProps` |
|
|
238
|
+
|---|---|---|---|
|
|
239
|
+
| `showName` | `boolean` | `false` | Show the display name next to the avatar |
|
|
240
|
+
| `afterSignOutUrl` | `string` | provider value, then `'/'` | Where to go after sign-out |
|
|
241
|
+
| `appearance` | `AppearanceProps` | none | Style overrides |
|
|
170
242
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
Renders the user's profile image or initials. Shows a placeholder icon when not signed in.
|
|
243
|
+
**`<UserAvatar>`** shows the user's picture or initials. It shows a placeholder icon when nobody
|
|
244
|
+
is signed in.
|
|
174
245
|
|
|
175
246
|
```tsx
|
|
176
|
-
import { UserAvatar } from '@lumoauth/react';
|
|
177
|
-
|
|
178
|
-
// Default circle avatar
|
|
179
247
|
<UserAvatar />
|
|
180
|
-
|
|
181
|
-
// Large square avatar
|
|
182
248
|
<UserAvatar size={48} shape="square" />
|
|
183
249
|
```
|
|
184
250
|
|
|
185
|
-
| Prop | Type | Default |
|
|
186
|
-
|
|
187
|
-
| `size` | `number` | `32` |
|
|
188
|
-
| `shape` | `'circle' \| 'square'` | `'circle'` |
|
|
189
|
-
| `appearance` | `AppearanceProps` |
|
|
190
|
-
|
|
191
|
-
### `<UserProfile>`
|
|
251
|
+
| Prop | Type | Default |
|
|
252
|
+
|---|---|---|
|
|
253
|
+
| `size` | `number` (pixels) | `32` |
|
|
254
|
+
| `shape` | `'circle' \| 'square'` | `'circle'` |
|
|
255
|
+
| `appearance` | `AppearanceProps` | none |
|
|
192
256
|
|
|
193
|
-
|
|
257
|
+
**`<UserProfile>`** shows a profile card with account details, security status, roles, groups and
|
|
258
|
+
a sign-out button.
|
|
194
259
|
|
|
195
260
|
```tsx
|
|
196
|
-
import { UserProfile } from '@lumoauth/react';
|
|
197
|
-
|
|
198
|
-
// Full profile card
|
|
199
261
|
<UserProfile afterSignOutUrl="/" />
|
|
200
|
-
|
|
201
|
-
// Compact mode (hides security and roles sections)
|
|
202
|
-
<UserProfile mode="compact" />
|
|
262
|
+
<UserProfile mode="compact" /> {/* account details only */}
|
|
203
263
|
```
|
|
204
264
|
|
|
205
265
|
| Prop | Type | Default | Description |
|
|
206
|
-
|
|
207
|
-
| `mode` | `'full' \| 'compact'` | `'full'` |
|
|
208
|
-
| `afterSignOutUrl` | `string` |
|
|
209
|
-
| `appearance` | `AppearanceProps` |
|
|
210
|
-
|
|
211
|
-
---
|
|
212
|
-
|
|
213
|
-
## Control Components
|
|
266
|
+
|---|---|---|---|
|
|
267
|
+
| `mode` | `'full' \| 'compact'` | `'full'` | `'compact'` hides the security and roles sections |
|
|
268
|
+
| `afterSignOutUrl` | `string` | none | Where to go after sign-out |
|
|
269
|
+
| `appearance` | `AppearanceProps` | none | Style overrides |
|
|
214
270
|
|
|
215
|
-
###
|
|
271
|
+
### Access checks
|
|
216
272
|
|
|
217
|
-
|
|
273
|
+
**`<Protect>`** renders its children only when a check allows it. Pass exactly one of
|
|
274
|
+
`permission`, `zanzibar` or `abac`. While the check runs, and when it is denied, `<Protect>`
|
|
275
|
+
renders `fallback`.
|
|
218
276
|
|
|
219
277
|
```tsx
|
|
220
|
-
|
|
278
|
+
// A permission (RBAC)
|
|
279
|
+
<Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
|
|
280
|
+
<AdminPanel />
|
|
281
|
+
</Protect>
|
|
221
282
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
<p>Welcome back! You are signed in.</p>
|
|
227
|
-
<UserProfile />
|
|
228
|
-
</SignedIn>
|
|
283
|
+
// A relationship (Zanzibar). Without subject, the check is about the signed-in user.
|
|
284
|
+
<Protect zanzibar={{ object: 'document:readme', relation: 'editor' }}>
|
|
285
|
+
<EditButton />
|
|
286
|
+
</Protect>
|
|
229
287
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
</>
|
|
235
|
-
);
|
|
236
|
-
}
|
|
288
|
+
// An attribute policy (ABAC). Needs abac:read on the token.
|
|
289
|
+
<Protect abac={{ resourceType: 'document', action: 'delete', resourceId: 'doc-123' }}>
|
|
290
|
+
<DeleteButton />
|
|
291
|
+
</Protect>
|
|
237
292
|
```
|
|
238
293
|
|
|
239
|
-
|
|
294
|
+
| Prop | Type | Description |
|
|
295
|
+
|---|---|---|
|
|
296
|
+
| `permission` | `string` | Permission slug |
|
|
297
|
+
| `zanzibar` | `{ object, relation, subject? }` | Relationship check. Without `subject`, the SDK asks about `user:<sub>`, where `<sub>` is the signed-in user's subject. When nobody is signed in, `<Protect>` renders `fallback` and sends no request. |
|
|
298
|
+
| `abac` | `{ resourceType, action, resourceId? }` | ABAC check |
|
|
299
|
+
| `fallback` | `ReactNode` | Shown while checking and when denied. Default: nothing. |
|
|
300
|
+
| `children` | `ReactNode` | Shown when allowed |
|
|
240
301
|
|
|
241
|
-
|
|
302
|
+
Any error during the check, such as a missing scope, counts as denied.
|
|
242
303
|
|
|
243
|
-
|
|
244
|
-
import { SignedOut, RedirectToSignIn } from '@lumoauth/react';
|
|
304
|
+
### Show content by sign-in state
|
|
245
305
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
<SignedOut>
|
|
250
|
-
<RedirectToSignIn />
|
|
251
|
-
</SignedOut>
|
|
252
|
-
<SignedIn>
|
|
253
|
-
<Dashboard />
|
|
254
|
-
</SignedIn>
|
|
255
|
-
</>
|
|
256
|
-
);
|
|
257
|
-
}
|
|
306
|
+
```tsx
|
|
307
|
+
<SignedIn><p>Welcome back.</p></SignedIn>
|
|
308
|
+
<SignedOut><SignIn /></SignedOut>
|
|
258
309
|
```
|
|
259
310
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
## Unstyled Components
|
|
263
|
-
|
|
264
|
-
Headless components without built-in UI — bring your own markup.
|
|
311
|
+
`<SignedIn>` renders its children only when a user is signed in. `<SignedOut>` renders them only
|
|
312
|
+
when nobody is. Neither renders anything while the session is loading.
|
|
265
313
|
|
|
266
|
-
|
|
314
|
+
**`<RedirectToSignIn>`** starts sign-in as soon as it renders. In PKCE mode it sends the user to
|
|
315
|
+
LumoAuth. In password mode it sends the user to `signInUrl`, when you pass one.
|
|
267
316
|
|
|
268
317
|
```tsx
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
// Default
|
|
272
|
-
<SignInButton />
|
|
273
|
-
|
|
274
|
-
// Custom children
|
|
275
|
-
<SignInButton>
|
|
276
|
-
<button className="my-btn">Log in</button>
|
|
277
|
-
</SignInButton>
|
|
318
|
+
<SignedOut><RedirectToSignIn /></SignedOut>
|
|
319
|
+
<SignedIn><Dashboard /></SignedIn>
|
|
278
320
|
```
|
|
279
321
|
|
|
280
|
-
###
|
|
322
|
+
### Unstyled buttons
|
|
281
323
|
|
|
282
|
-
|
|
283
|
-
import { SignUpButton } from '@lumoauth/react';
|
|
284
|
-
<SignUpButton signUpUrl="/register" />
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
### `<SignOutButton>`
|
|
324
|
+
These buttons have no styling of their own. Put your own markup inside them.
|
|
288
325
|
|
|
289
326
|
```tsx
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
<SignOutButton afterSignOutUrl="/">
|
|
293
|
-
<button className="my-btn">Log out</button>
|
|
294
|
-
</SignOutButton>
|
|
327
|
+
<SignInButton><button className="btn">Log in</button></SignInButton>
|
|
328
|
+
<SignUpButton signUpUrl="/register" />
|
|
329
|
+
<SignOutButton afterSignOutUrl="/"><button className="btn">Log out</button></SignOutButton>
|
|
295
330
|
```
|
|
296
331
|
|
|
297
|
-
|
|
332
|
+
| Component | Props | What a click does |
|
|
333
|
+
|---|---|---|
|
|
334
|
+
| `<SignInButton>` | `children?`, `signInUrl?`, `className?` | PKCE mode: starts sign-in. Password mode: goes to `signInUrl`. |
|
|
335
|
+
| `<SignUpButton>` | `children?`, `signUpUrl?`, `className?` | Goes to `signUpUrl` |
|
|
336
|
+
| `<SignOutButton>` | `children?`, `afterSignOutUrl?`, `className?` | Signs the user out, then redirects |
|
|
298
337
|
|
|
299
338
|
## Hooks
|
|
300
339
|
|
|
301
|
-
|
|
340
|
+
Every hook must be called inside `<LumoAuthProvider>`.
|
|
302
341
|
|
|
303
|
-
|
|
342
|
+
**`useAuth()`** returns the full auth context.
|
|
304
343
|
|
|
305
344
|
```tsx
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
function MyComponent() {
|
|
309
|
-
const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
|
|
345
|
+
const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
|
|
310
346
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
return (
|
|
315
|
-
<div>
|
|
316
|
-
<p>Hello, {user.displayName}!</p>
|
|
317
|
-
<button onClick={() => signOut()}>Sign out</button>
|
|
318
|
-
</div>
|
|
319
|
-
);
|
|
320
|
-
}
|
|
347
|
+
if (!isLoaded) return <p>Loading…</p>;
|
|
348
|
+
if (!isSignedIn) return <button onClick={() => signIn()}>Sign in</button>;
|
|
349
|
+
return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
|
|
321
350
|
```
|
|
322
351
|
|
|
323
|
-
#### Return value
|
|
324
|
-
|
|
325
352
|
| Property | Type | Description |
|
|
326
|
-
|
|
327
|
-
| `user` | `LumoAuthUser \| null` |
|
|
328
|
-
| `
|
|
329
|
-
| `isLoaded` | `boolean` |
|
|
330
|
-
| `
|
|
331
|
-
| `signIn
|
|
332
|
-
| `signInWithRedirect` |
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `
|
|
336
|
-
| `
|
|
337
|
-
| `
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
import { useUser } from '@lumoauth/react';
|
|
345
|
-
|
|
346
|
-
const user = useUser();
|
|
347
|
-
console.log(user?.email, user?.roles);
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
#### `LumoAuthUser` object
|
|
353
|
+
|---|---|---|
|
|
354
|
+
| `user` | `LumoAuthUser \| null` | The signed-in user |
|
|
355
|
+
| `status` | `'loading' \| 'authenticated' \| 'unauthenticated'` | Session status |
|
|
356
|
+
| `isLoaded` | `boolean` | The first session check has finished |
|
|
357
|
+
| `isSignedIn` | `boolean` | A user is signed in |
|
|
358
|
+
| `signIn(email?, password?)` | function | PKCE mode: call with no arguments to redirect to LumoAuth. Password mode: pass the email and password. |
|
|
359
|
+
| `signInWithRedirect()` | function | Starts the PKCE redirect in either mode |
|
|
360
|
+
| `signInWithSocial(provider)` | function | Starts the PKCE redirect straight to a social provider, such as `'google'` |
|
|
361
|
+
| `signUp(params)` | function | PKCE mode: sends the user to the registration page. Password mode: throws, because inline registration is not available. |
|
|
362
|
+
| `signOut({ afterSignOutUrl? })` | function | Revokes the access token, clears local tokens, and ends the LumoAuth session through the logout endpoint |
|
|
363
|
+
| `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
|
|
364
|
+
| `handleCallback()` | function | Exchanges the code on the callback page. `<AuthCallback>` calls it for you. |
|
|
365
|
+
| `sendMagicLink(email, redirectUri?)` | function | Emails a sign-in link |
|
|
366
|
+
| `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
|
|
367
|
+
| `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
|
|
368
|
+
| `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
|
|
369
|
+
|
|
370
|
+
**`useUser()`** returns the signed-in `LumoAuthUser`, or `null`.
|
|
351
371
|
|
|
352
372
|
| Field | Type | Description |
|
|
353
|
-
|
|
354
|
-
| `id` | `string \| number` | User ID |
|
|
355
|
-
| `email` | `string` | Primary email |
|
|
356
|
-
| `firstName` | `string
|
|
357
|
-
| `
|
|
358
|
-
| `
|
|
359
|
-
| `
|
|
360
|
-
| `
|
|
361
|
-
| `
|
|
362
|
-
| `
|
|
363
|
-
| `
|
|
364
|
-
| `sub` | `string?` | OIDC subject ID |
|
|
365
|
-
| `claims` | `Record<string, unknown>` | Additional claims |
|
|
366
|
-
|
|
367
|
-
### `useSignIn()`
|
|
373
|
+
|---|---|---|
|
|
374
|
+
| `id` | `string \| number` | User ID (the OIDC `sub`) |
|
|
375
|
+
| `email` | `string` | Primary email address |
|
|
376
|
+
| `firstName`, `lastName` | `string \| undefined` | Name parts |
|
|
377
|
+
| `displayName` | `string` | The name, or the email when there is no name |
|
|
378
|
+
| `avatarUrl` | `string \| undefined` | Profile picture |
|
|
379
|
+
| `emailVerified` | `boolean` | Whether the email address is verified |
|
|
380
|
+
| `mfaEnabled` | `boolean` | From the `mfa_enabled` claim; `false` when absent |
|
|
381
|
+
| `roles`, `groups` | `string[]` | From the `roles` and `groups` claims; empty when absent |
|
|
382
|
+
| `sub` | `string \| undefined` | OIDC subject |
|
|
383
|
+
| `claims` | `Record<string, unknown>` | Every claim from the UserInfo response |
|
|
368
384
|
|
|
369
|
-
|
|
370
|
-
|
|
385
|
+
The user comes from the OIDC UserInfo endpoint. A field is empty when the response does not
|
|
386
|
+
contain it.
|
|
371
387
|
|
|
372
|
-
|
|
373
|
-
```
|
|
388
|
+
**`useSignIn()`** returns `{ signIn, signInWithRedirect, isLoading }`.
|
|
374
389
|
|
|
375
|
-
|
|
390
|
+
**`useSession()`** returns `{ isActive, isLoaded, getToken, status }`. Use `getToken()` to call
|
|
391
|
+
your own API:
|
|
376
392
|
|
|
377
393
|
```tsx
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
const { isActive, isLoaded, getToken, status } = useSession();
|
|
381
|
-
|
|
382
|
-
// Fetch API data with the access token
|
|
383
|
-
async function fetchData() {
|
|
384
|
-
const token = await getToken();
|
|
385
|
-
const res = await fetch('/api/data', {
|
|
386
|
-
headers: { Authorization: `Bearer ${token}` },
|
|
387
|
-
});
|
|
388
|
-
return res.json();
|
|
389
|
-
}
|
|
394
|
+
const { getToken } = useSession();
|
|
395
|
+
const res = await fetch('/api/data', { headers: { Authorization: `Bearer ${await getToken()}` } });
|
|
390
396
|
```
|
|
391
397
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
Returns a configured `LumoAuth` SDK client for authorization checks. Token is auto-managed.
|
|
398
|
+
**`useLumoAuth()`** returns a `LumoAuth` client from `@lumoauth/client`. Its token comes from the
|
|
399
|
+
session. Use it for any call that the hooks do not cover.
|
|
395
400
|
|
|
396
401
|
```tsx
|
|
397
|
-
import { useLumoAuth } from '@lumoauth/react';
|
|
398
|
-
|
|
399
402
|
const client = useLumoAuth();
|
|
400
|
-
const canEdit = await client.permissions.check('
|
|
403
|
+
const canEdit = await client.permissions.check('document.edit');
|
|
401
404
|
```
|
|
402
405
|
|
|
403
|
-
|
|
406
|
+
**`usePermission(slug)`**, **`useZanzibar(request)`** and **`useAbac(request)`** each return
|
|
407
|
+
`{ allowed, isLoading }`. Each one runs again when its input changes. An error counts as denied.
|
|
404
408
|
|
|
405
409
|
```tsx
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
const {
|
|
410
|
+
const { allowed, isLoading } = usePermission('document.edit');
|
|
411
|
+
const editor = useZanzibar({ object: 'document:readme', relation: 'editor', subject: 'user:alice' });
|
|
412
|
+
const canRead = useAbac({ resourceType: 'document', action: 'read', resourceId: 'doc-123' });
|
|
409
413
|
```
|
|
410
414
|
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
```tsx
|
|
414
|
-
import { useZanzibar } from '@lumoauth/react';
|
|
415
|
-
|
|
416
|
-
const { allowed, isLoading } = useZanzibar({
|
|
417
|
-
object: 'document:readme',
|
|
418
|
-
relation: 'editor',
|
|
419
|
-
subject: 'user:alice',
|
|
420
|
-
});
|
|
421
|
-
```
|
|
415
|
+
A Zanzibar check about a user other than the signed-in user needs the `authz:check` scope or
|
|
416
|
+
permission. `useAbac` needs `abac:read`; see [Core concepts](#core-concepts).
|
|
422
417
|
|
|
423
|
-
|
|
418
|
+
**`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
|
|
424
419
|
|
|
425
420
|
```tsx
|
|
426
|
-
import { useAbac } from '@lumoauth/react';
|
|
427
|
-
|
|
428
|
-
const { allowed, isLoading } = useAbac({
|
|
429
|
-
resourceType: 'document',
|
|
430
|
-
action: 'read',
|
|
431
|
-
resourceId: 'doc-123',
|
|
432
|
-
});
|
|
433
|
-
```
|
|
434
|
-
|
|
435
|
-
### `useMagicLink()`
|
|
436
|
-
|
|
437
|
-
Manages the full state machine for sending a passwordless magic-link email. Handles in-flight loading, success, and error states so you can build a controlled form without any extra local state.
|
|
438
|
-
|
|
439
|
-
```tsx
|
|
440
|
-
import { useMagicLink } from '@lumoauth/react';
|
|
441
|
-
|
|
442
421
|
function PasswordlessForm() {
|
|
443
422
|
const [email, setEmail] = useState('');
|
|
444
423
|
const { sendMagicLink, isLoading, isSent, error, reset } = useMagicLink();
|
|
445
424
|
|
|
446
425
|
if (isSent) {
|
|
447
426
|
return (
|
|
448
|
-
<
|
|
449
|
-
|
|
427
|
+
<p>
|
|
428
|
+
We sent a sign-in link to <strong>{email}</strong>.{' '}
|
|
450
429
|
<button onClick={reset}>Use a different email</button>
|
|
451
|
-
</
|
|
430
|
+
</p>
|
|
452
431
|
);
|
|
453
432
|
}
|
|
454
433
|
|
|
455
434
|
return (
|
|
456
435
|
<form onSubmit={(e) => { e.preventDefault(); sendMagicLink(email); }}>
|
|
457
|
-
<input
|
|
458
|
-
|
|
459
|
-
value={email}
|
|
460
|
-
onChange={(e) => setEmail(e.target.value)}
|
|
461
|
-
placeholder="you@example.com"
|
|
462
|
-
/>
|
|
463
|
-
<button type="submit" disabled={isLoading}>
|
|
464
|
-
{isLoading ? 'Sending…' : 'Send sign-in link'}
|
|
465
|
-
</button>
|
|
436
|
+
<input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
|
|
437
|
+
<button type="submit" disabled={isLoading}>{isLoading ? 'Sending…' : 'Send sign-in link'}</button>
|
|
466
438
|
{error && <p className="error">{error}</p>}
|
|
467
439
|
</form>
|
|
468
440
|
);
|
|
469
441
|
}
|
|
470
442
|
```
|
|
471
443
|
|
|
472
|
-
|
|
444
|
+
`isSent` becomes `true` whether or not the account exists. The server never reveals that.
|
|
473
445
|
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
| `error` | `string \| null` | Error message if the request failed |
|
|
480
|
-
| `reset` | `() => void` | Reset back to idle state |
|
|
481
|
-
|
|
482
|
-
### `useEmailFirst()`
|
|
483
|
-
|
|
484
|
-
Checks whether an account exists for a given email before revealing the next step (password field, magic-link option, or sign-up prompt). Useful for building a single email-input screen that adapts to whether the user already has an account.
|
|
446
|
+
**`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
|
|
447
|
+
a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
|
|
448
|
+
`EmailCheckResult`. It reports whether the account exists and which methods it can use:
|
|
449
|
+
`passwordEnabled`, `passkeyEnabled`, `magicLinkEnabled`, `hasPasskey`, `hasPushDevice` and
|
|
450
|
+
`maskedEmail`. `exists` is `null` until the first check.
|
|
485
451
|
|
|
486
452
|
```tsx
|
|
487
|
-
|
|
453
|
+
const { checkEmail, isLoading } = useEmailFirst();
|
|
488
454
|
|
|
489
|
-
function
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
async function handleSubmit(e: React.FormEvent) {
|
|
497
|
-
e.preventDefault();
|
|
498
|
-
const found = await checkEmail(email);
|
|
499
|
-
if (found) {
|
|
500
|
-
onKnownUser(); // show password / magic-link step
|
|
501
|
-
} else {
|
|
502
|
-
onNewUser(); // show sign-up prompt
|
|
503
|
-
}
|
|
504
|
-
}
|
|
505
|
-
|
|
506
|
-
return (
|
|
507
|
-
<form onSubmit={handleSubmit}>
|
|
508
|
-
<input
|
|
509
|
-
type="email"
|
|
510
|
-
value={email}
|
|
511
|
-
onChange={(e) => setEmail(e.target.value)}
|
|
512
|
-
placeholder="you@example.com"
|
|
513
|
-
/>
|
|
514
|
-
<button type="submit" disabled={isLoading}>
|
|
515
|
-
{isLoading ? 'Checking…' : 'Continue'}
|
|
516
|
-
</button>
|
|
517
|
-
</form>
|
|
518
|
-
);
|
|
455
|
+
async function onSubmit(e: React.FormEvent) {
|
|
456
|
+
e.preventDefault();
|
|
457
|
+
const found = await checkEmail(email);
|
|
458
|
+
if (!found.exists) return showSignUp();
|
|
459
|
+
if (found.magicLinkEnabled) return showMagicLinkOption();
|
|
460
|
+
signIn(); // fall back to the LumoAuth sign-in page
|
|
519
461
|
}
|
|
520
462
|
```
|
|
521
463
|
|
|
522
|
-
|
|
464
|
+
## Common patterns
|
|
523
465
|
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
| `checkEmail` | `(email) => Promise<boolean>` | Returns `true` if account exists |
|
|
527
|
-
| `isLoading` | `boolean` | True while the check is in-flight |
|
|
528
|
-
| `exists` | `boolean \| null` | Result of last check (`null` = not yet checked) |
|
|
529
|
-
| `reset` | `() => void` | Reset state back to idle |
|
|
530
|
-
|
|
531
|
-
---
|
|
532
|
-
|
|
533
|
-
## Authorization
|
|
534
|
-
|
|
535
|
-
### `<Protect>`
|
|
536
|
-
|
|
537
|
-
Conditional rendering based on permissions, Zanzibar (ReBAC), or ABAC.
|
|
538
|
-
|
|
539
|
-
```tsx
|
|
540
|
-
import { Protect } from '@lumoauth/react';
|
|
541
|
-
|
|
542
|
-
// RBAC
|
|
543
|
-
<Protect permission="admin.dashboard" fallback={<p>Access denied</p>}>
|
|
544
|
-
<AdminPanel />
|
|
545
|
-
</Protect>
|
|
546
|
-
|
|
547
|
-
// Zanzibar (ReBAC)
|
|
548
|
-
<Protect zanzibar={{ object: 'doc:readme', relation: 'editor' }}>
|
|
549
|
-
<EditButton />
|
|
550
|
-
</Protect>
|
|
551
|
-
|
|
552
|
-
// ABAC
|
|
553
|
-
<Protect abac={{ resourceType: 'document', action: 'delete', resourceId: 'doc-123' }}>
|
|
554
|
-
<DeleteButton />
|
|
555
|
-
</Protect>
|
|
556
|
-
```
|
|
557
|
-
|
|
558
|
-
---
|
|
559
|
-
|
|
560
|
-
## Common Patterns
|
|
561
|
-
|
|
562
|
-
### Navbar with login detection
|
|
563
|
-
|
|
564
|
-
Swap sign-in/sign-up links for user avatar and sign-out when authenticated:
|
|
466
|
+
<details>
|
|
467
|
+
<summary><strong>A navigation bar that swaps sign-in links for the user menu</strong></summary>
|
|
565
468
|
|
|
566
469
|
```tsx
|
|
567
|
-
import {
|
|
568
|
-
SignedIn, SignedOut,
|
|
569
|
-
UserButton, SignInButton, SignUpButton,
|
|
570
|
-
} from '@lumoauth/react';
|
|
470
|
+
import { SignedIn, SignedOut, UserButton, SignInButton, SignUpButton } from '@lumoauth/react';
|
|
571
471
|
|
|
572
|
-
function Navbar() {
|
|
472
|
+
export function Navbar() {
|
|
573
473
|
return (
|
|
574
474
|
<nav className="navbar">
|
|
575
475
|
<a href="/">My App</a>
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
<
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
<SignedIn>
|
|
584
|
-
<UserButton showName />
|
|
585
|
-
</SignedIn>
|
|
586
|
-
</div>
|
|
476
|
+
<SignedOut>
|
|
477
|
+
<SignInButton className="btn">Sign in</SignInButton>
|
|
478
|
+
<SignUpButton className="btn btn-primary">Sign up</SignUpButton>
|
|
479
|
+
</SignedOut>
|
|
480
|
+
<SignedIn>
|
|
481
|
+
<UserButton showName />
|
|
482
|
+
</SignedIn>
|
|
587
483
|
</nav>
|
|
588
484
|
);
|
|
589
485
|
}
|
|
590
486
|
```
|
|
591
487
|
|
|
592
|
-
|
|
488
|
+
</details>
|
|
593
489
|
|
|
594
|
-
|
|
490
|
+
<details>
|
|
491
|
+
<summary><strong>A route that needs a signed-in user</strong></summary>
|
|
595
492
|
|
|
596
493
|
```tsx
|
|
597
494
|
import { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';
|
|
598
495
|
|
|
599
|
-
function ProtectedRoute({ children }: { children: React.ReactNode }) {
|
|
496
|
+
export function ProtectedRoute({ children }: { children: React.ReactNode }) {
|
|
600
497
|
return (
|
|
601
498
|
<>
|
|
602
|
-
<SignedOut>
|
|
603
|
-
|
|
604
|
-
</SignedOut>
|
|
605
|
-
<SignedIn>
|
|
606
|
-
{children}
|
|
607
|
-
</SignedIn>
|
|
499
|
+
<SignedOut><RedirectToSignIn /></SignedOut>
|
|
500
|
+
<SignedIn>{children}</SignedIn>
|
|
608
501
|
</>
|
|
609
502
|
);
|
|
610
503
|
}
|
|
611
|
-
|
|
612
|
-
// Usage
|
|
613
|
-
<ProtectedRoute>
|
|
614
|
-
<Dashboard />
|
|
615
|
-
</ProtectedRoute>
|
|
616
504
|
```
|
|
617
505
|
|
|
618
|
-
|
|
506
|
+
</details>
|
|
507
|
+
|
|
508
|
+
<details>
|
|
509
|
+
<summary><strong>Calling your API with the user's token</strong></summary>
|
|
619
510
|
|
|
620
511
|
```tsx
|
|
621
512
|
import { useSession } from '@lumoauth/react';
|
|
622
513
|
import { useEffect, useState } from 'react';
|
|
623
514
|
|
|
624
|
-
function DataView() {
|
|
515
|
+
export function DataView() {
|
|
625
516
|
const { isActive, getToken } = useSession();
|
|
626
517
|
const [data, setData] = useState(null);
|
|
627
518
|
|
|
628
519
|
useEffect(() => {
|
|
629
520
|
if (!isActive) return;
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
fetch('/api/data', {
|
|
633
|
-
headers: { Authorization: `Bearer ${token}` },
|
|
634
|
-
})
|
|
521
|
+
getToken().then((token) =>
|
|
522
|
+
fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } })
|
|
635
523
|
.then((r) => r.json())
|
|
636
|
-
.then(setData)
|
|
637
|
-
|
|
524
|
+
.then(setData),
|
|
525
|
+
);
|
|
638
526
|
}, [isActive, getToken]);
|
|
639
527
|
|
|
640
|
-
|
|
641
|
-
return <pre>{JSON.stringify(data, null, 2)}</pre>;
|
|
642
|
-
}
|
|
643
|
-
```
|
|
644
|
-
|
|
645
|
-
### User profile page
|
|
646
|
-
|
|
647
|
-
```tsx
|
|
648
|
-
import { SignedIn, SignedOut, UserProfile, RedirectToSignIn } from '@lumoauth/react';
|
|
649
|
-
|
|
650
|
-
function ProfilePage() {
|
|
651
|
-
return (
|
|
652
|
-
<>
|
|
653
|
-
<SignedOut>
|
|
654
|
-
<RedirectToSignIn />
|
|
655
|
-
</SignedOut>
|
|
656
|
-
<SignedIn>
|
|
657
|
-
<h1>Your Profile</h1>
|
|
658
|
-
<UserProfile afterSignOutUrl="/" />
|
|
659
|
-
</SignedIn>
|
|
660
|
-
</>
|
|
661
|
-
);
|
|
662
|
-
}
|
|
663
|
-
```
|
|
664
|
-
|
|
665
|
-
### Custom header with avatar
|
|
666
|
-
|
|
667
|
-
```tsx
|
|
668
|
-
import { useAuth, UserAvatar } from '@lumoauth/react';
|
|
669
|
-
|
|
670
|
-
function CustomHeader() {
|
|
671
|
-
const { user, isSignedIn, signIn, signOut } = useAuth();
|
|
672
|
-
|
|
673
|
-
return (
|
|
674
|
-
<header>
|
|
675
|
-
{isSignedIn ? (
|
|
676
|
-
<div className="user-info">
|
|
677
|
-
<UserAvatar size={36} />
|
|
678
|
-
<span>{user?.displayName}</span>
|
|
679
|
-
<button onClick={() => signOut()}>Log out</button>
|
|
680
|
-
</div>
|
|
681
|
-
) : (
|
|
682
|
-
<button onClick={() => signIn()}>Log in</button>
|
|
683
|
-
)}
|
|
684
|
-
</header>
|
|
685
|
-
);
|
|
528
|
+
return data ? <pre>{JSON.stringify(data, null, 2)}</pre> : <p>Loading…</p>;
|
|
686
529
|
}
|
|
687
530
|
```
|
|
688
531
|
|
|
689
|
-
|
|
532
|
+
</details>
|
|
690
533
|
|
|
691
534
|
## Appearance
|
|
692
535
|
|
|
693
|
-
|
|
536
|
+
Every ready-made component accepts an `appearance` prop:
|
|
694
537
|
|
|
695
538
|
```tsx
|
|
696
539
|
<SignIn appearance={{
|
|
697
540
|
theme: 'dark',
|
|
698
|
-
className: 'my-
|
|
541
|
+
className: 'my-card',
|
|
699
542
|
variables: { '--la-primary': '#6366f1' },
|
|
700
543
|
}} />
|
|
701
544
|
```
|
|
702
545
|
|
|
703
546
|
| Option | Type | Description |
|
|
704
|
-
|
|
705
|
-
| `theme` | `'light' \| 'dark'` | Force theme
|
|
706
|
-
| `className` | `string` |
|
|
707
|
-
| `variables` | `Record<string, string>` |
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
|
757
|
-
|
|
758
|
-
|
|
|
759
|
-
|
|
|
760
|
-
|
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
|
768
|
-
|
|
769
|
-
| `<
|
|
770
|
-
|
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
|
775
|
-
|
|
776
|
-
| `
|
|
777
|
-
|
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
547
|
+
|---|---|---|
|
|
548
|
+
| `theme` | `'light' \| 'dark'` | Force a theme. The default follows the system setting. |
|
|
549
|
+
| `className` | `string` | Extra class on the component's root element |
|
|
550
|
+
| `variables` | `Record<string, string>` | Values for CSS custom properties |
|
|
551
|
+
|
|
552
|
+
Commonly changed properties: `--la-primary`, `--la-primary-hover`, `--la-bg`,
|
|
553
|
+
`--la-text-primary`, `--la-text-secondary`, `--la-border`, `--la-radius-md` and
|
|
554
|
+
`--la-font-family`. The stylesheet defines more for spacing, shadows, font sizes and states.
|
|
555
|
+
|
|
556
|
+
## Sign-in strategies
|
|
557
|
+
|
|
558
|
+
**PKCE (default).** The user goes to the LumoAuth sign-in page and comes back to your callback
|
|
559
|
+
route. This is the right choice for browser apps. LumoAuth handles passwords, passkeys, social
|
|
560
|
+
sign-in and MFA on that page.
|
|
561
|
+
|
|
562
|
+
**Password.** `authStrategy="password"` shows an email and password form in `<SignIn>` and uses
|
|
563
|
+
the older resource-owner password grant. The organization must allow it. Use PKCE for new apps.
|
|
564
|
+
|
|
565
|
+
```tsx
|
|
566
|
+
<LumoAuthProvider domain="https://app.lumoauth.dev" orgId="acme-corp" clientId="abc" authStrategy="password">
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
To keep your own form but still use PKCE, call `useLumoAuth().auth.loginWithPassword()` and then
|
|
570
|
+
`signIn()`. The [client README](../client/README.md#passwordless-email-first-and-embedded-sign-in)
|
|
571
|
+
explains the flow, and the example app shows it on its `/embedded` page.
|
|
572
|
+
|
|
573
|
+
## Errors
|
|
574
|
+
|
|
575
|
+
The hooks and `<Protect>` catch errors and report them as `allowed: false`. `<AuthCallback>`
|
|
576
|
+
shows sign-in errors through its `error` prop. When you call the client from `useLumoAuth()`
|
|
577
|
+
yourself, it throws the error classes that are described in the
|
|
578
|
+
[client README](../client/README.md#errors). For example, a missing scope throws a
|
|
579
|
+
`LumoAuthPermissionDeniedError` with `requiredScopes`.
|
|
580
|
+
|
|
581
|
+
## API reference
|
|
582
|
+
|
|
583
|
+
| Export | Kind | Purpose |
|
|
584
|
+
|---|---|---|
|
|
585
|
+
| `LumoAuthProvider` | provider | Holds the session. Wrap the app once. |
|
|
586
|
+
| `SignIn`, `SignUp` | component | Sign-in and sign-up cards |
|
|
587
|
+
| `AuthCallback` | component | Finishes sign-in on the callback route |
|
|
588
|
+
| `UserButton`, `UserAvatar`, `UserProfile` | component | User menu, avatar and profile card |
|
|
589
|
+
| `Protect` | component | Renders children when a permission, relationship or policy allows it |
|
|
590
|
+
| `SignedIn`, `SignedOut` | component | Render by sign-in state |
|
|
591
|
+
| `RedirectToSignIn` | component | Starts sign-in when rendered |
|
|
592
|
+
| `SignInButton`, `SignUpButton`, `SignOutButton` | component | Unstyled triggers |
|
|
593
|
+
| `useAuth()` | hook | Full auth context |
|
|
594
|
+
| `useUser()` | hook | `LumoAuthUser \| null` |
|
|
595
|
+
| `useSignIn()` | hook | `{ signIn, signInWithRedirect, isLoading }` |
|
|
596
|
+
| `useSession()` | hook | `{ isActive, isLoaded, getToken, status }` |
|
|
597
|
+
| `useLumoAuth()` | hook | A `LumoAuth` client that uses the session token |
|
|
598
|
+
| `usePermission(slug)` | hook | `{ allowed, isLoading }` |
|
|
599
|
+
| `useZanzibar(request)` | hook | `{ allowed, isLoading }` |
|
|
600
|
+
| `useAbac(request)` | hook | `{ allowed, isLoading }`; needs `abac:read` |
|
|
601
|
+
| `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, reset }` |
|
|
602
|
+
| `useEmailFirst()` | hook | `{ checkEmail, isLoading, result, exists, reset }` |
|
|
603
|
+
| `LumoAuth` | class | The browser client, re-exported from `@lumoauth/client` |
|
|
604
|
+
|
|
605
|
+
The prop and return types are exported too, for example `LumoAuthProviderProps`,
|
|
606
|
+
`LumoAuthUser`, `ProtectProps` and `UseEmailFirstReturn`.
|
|
607
|
+
|
|
608
|
+
## Troubleshooting
|
|
609
|
+
|
|
610
|
+
| Symptom | Cause | Fix |
|
|
611
|
+
|---|---|---|
|
|
612
|
+
| `useAbac` and `<Protect abac={…}>` always deny | The token lacks `abac:read`. | Add `abac:read` to the provider's `scope` prop and to the OAuth client's allowed scopes, then sign in again. |
|
|
613
|
+
| `listSlugs()` throws `403` with `requiredScopes: ['authz:read']` | The token lacks `authz:read`. | Add `authz:read` to the `scope` prop and to the OAuth client, then sign in again. |
|
|
614
|
+
| `<Protect zanzibar={…}>` denies a user who has the relation | The tuple names the user by a different ID than the `sub` claim. | Write the tuple with the user's `sub`, or pass `subject` yourself. |
|
|
615
|
+
| `useZanzibar` about another user always denies | Asking about another subject needs `authz:check`. | Run that check on your server with a credential that holds `authz:check`. |
|
|
616
|
+
| The callback page shows a CORS error | Your origin is not in the OAuth client's allowed origins. | Add it in the LumoAuth dashboard. |
|
|
617
|
+
| The callback fails with a redirect URI error | `redirectUri` does not match a registered redirect URI exactly. | Register `<origin>/auth/callback`, or pass the registered value as `redirectUri`. |
|
|
618
|
+
| After sign-out, the user is signed straight back in | `afterSignOutUrl` is not a registered post-logout redirect URI, so the LumoAuth session did not end. | Register the URL on the OAuth client. |
|
|
619
|
+
| `signUp()` throws in password mode | Inline registration is not available. | Use PKCE mode, which sends the user to the registration page. |
|
|
620
|
+
| The page shows signed-out content first, then the user | A client-side provider must load the session after the page renders. | Use `@lumoauth/nextjs` for server-rendered sessions. |
|
|
621
|
+
|
|
622
|
+
## Versioning and compatibility
|
|
623
|
+
|
|
624
|
+
This package is version 1.0.0. It needs LumoAuth server API 1.0.0 or newer, React 18 or newer,
|
|
625
|
+
and `@lumoauth/client` 1.0.0.
|
|
626
|
+
|
|
627
|
+
## Related packages
|
|
628
|
+
|
|
629
|
+
| Package | Relationship |
|
|
630
|
+
|---|---|
|
|
631
|
+
| [`@lumoauth/nextjs`](../nextjs/README.md) | Re-exports this package and adds server-side sessions for Next.js |
|
|
632
|
+
| [`@lumoauth/client`](../client/README.md) | The client, session runtime and storage adapters underneath |
|
|
633
|
+
| [`@lumoauth/express`](../express/README.md), [`@lumoauth/backend`](../backend/README.md) | Server side |
|
|
634
|
+
| [`create-lumo-agent`](../create-lumo-agent/README.md) | Creates a Next.js agent app that uses this package for sign-in |
|
|
635
|
+
| [Workspace README](../../README.md) | How the packages fit together |
|
|
636
|
+
|
|
637
|
+
More: [React quickstart](https://docs.lumoauth.dev/quickstarts/react/),
|
|
638
|
+
[SDK overview](https://docs.lumoauth.dev/developer/sdks/), and the
|
|
639
|
+
[example app](../../examples/nextjs/README.md), which uses every component and hook.
|
|
640
|
+
|
|
641
|
+
## Licence
|
|
642
|
+
|
|
643
|
+
[MIT](./LICENSE)
|