Skip to content

Commit 07767a9

Browse files
bcbogdanbcbogdan
committed
Update the passkeys section
1 parent e908314 commit 07767a9

15 files changed

+1291
-676
lines changed

‎v3/docs/authentication/webauthn/_category_.json renamed to ‎v3/docs/authentication/passkeys/_category_.json

File renamed without changes.

‎v3/docs/authentication/passkeys/customization.mdx

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
---
2+
title: Customization
3+
hide_title: true
4+
sidebar_position: 4
5+
---
6+
7+
import { BackendTabs } from "/src/components/Tabs";
8+
9+
# Customization
10+
11+
## Overview
12+
13+
Like the other **SuperTokens** authentication recipes, you can customize the `WebAuthn` flow through different configuration options and overrides.
14+
The following page describes the options that you can change and the different scenarios that are enabled through customization.
15+
16+
---
17+
18+
## Backend recipe configuration
19+
20+
21+
The backend recipe accepts the following properties during initialization:
22+
23+
| Option | Description | Default |
24+
|--------|-------------|---------|
25+
| `getRelyingPartyId` | Sets the domain name that will be associated with the WebAuthn credentials. This helps ensure credentials can only be used on your domain. | The `apiDomain` value that you have set in `appConfig` |
26+
| `getRelyingPartyName` | Set a human-readable name for your application that will be shown to users during the WebAuthn registration process. | The `appName` value that you have set in `appConfig` |
27+
| `getOrigin` | Configure the origin URL that WebAuthn credentials will be bound to. This should match your application's domain and protocol. | Origin of the request |
28+
| `emailDelivery` | Configure how verification emails are sent to users. Read the [email delivery page](/docs/platform-configuration/email-delivery) for more information. | Default email service |
29+
| `validateEmailAddress` | Add custom validation logic for email addresses. | Basic email format validation |
30+
31+
All the properties are optional.
32+
In most cases, you can rely on the default values provided by the recipe.
33+
34+
<BackendTabs>
35+
36+
<BackendTabs.TabItem value="nodejs">
37+
38+
```ts
39+
import supertokens from "supertokens-node";
40+
import Session from "supertokens-node/recipe/session";
41+
import WebAuthn from "supertokens-node/recipe/webauthn";
42+
43+
supertokens.init({
44+
framework: "express",
45+
supertokens: {
46+
// https://try.supertokens.com is for demo purposes. Replace this with the address of your core instance (sign up on supertokens.com), or self host a core.
47+
connectionURI: "https://try.supertokens.com",
48+
// apiKey: <API_KEY(if configured)>,
49+
},
50+
appInfo: {
51+
// learn more about this on https://supertokens.com/docs/session/appinfo
52+
appName: "<YOUR_APP_NAME>",
53+
apiDomain: "<YOUR_API_DOMAIN>",
54+
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
55+
apiBasePath: "/auth",
56+
websiteBasePath: "/auth"
57+
},
58+
recipeList: [
59+
WebAuthn.init({
60+
getOrigin: () => {
61+
return "https://example.com";
62+
},
63+
getRelyingPartyId: () => {
64+
return "example.com";
65+
},
66+
getRelyingPartyName: () => {
67+
return "example";
68+
},
69+
}),
70+
Session.init() // initializes session features
71+
]
72+
});
73+
```
74+
75+
</BackendTabs.TabItem>
76+
77+
<BackendTabs.TabItem value="go">
78+
79+
:::caution
80+
81+
At the moment there is no support for using passkeys authentication in the Go SDK.
82+
83+
:::
84+
85+
</BackendTabs.TabItem>
86+
87+
<BackendTabs.TabItem value="python">
88+
89+
:::caution
90+
91+
At the moment there is no support for using passkeys authentication in the Python SDK.
92+
93+
:::
94+
95+
</BackendTabs.TabItem>
96+
97+
</BackendTabs>
98+
99+
---
100+
101+
## Credential generation
102+
103+
The credentials are generated by the client based on the options provided by the backend SDK.
104+
The frontend SDK uses the [`navigator.credentials.created`](https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/create) function to resolve this.
105+
106+
To change the options used to generate credentials, you need to override the `registerOptions` function.
107+
108+
<BackendTabs>
109+
110+
<BackendTabs.TabItem value="nodejs">
111+
112+
```ts
113+
import supertokens from "supertokens-node";
114+
import Session from "supertokens-node/recipe/session";
115+
import WebAuthn from "supertokens-node/recipe/webauthn";
116+
117+
supertokens.init({
118+
framework: "express",
119+
supertokens: {
120+
// https://try.supertokens.com is for demo purposes. Replace this with the address of your core instance (sign up on supertokens.com), or self host a core.
121+
connectionURI: "https://try.supertokens.com",
122+
// apiKey: <API_KEY(if configured)>,
123+
},
124+
appInfo: {
125+
// learn more about this on https://supertokens.com/docs/session/appinfo
126+
appName: "<YOUR_APP_NAME>",
127+
apiDomain: "<YOUR_API_DOMAIN>",
128+
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
129+
apiBasePath: "/auth",
130+
websiteBasePath: "/auth"
131+
},
132+
recipeList: [
133+
WebAuthn.init({
134+
override: {
135+
functions: (originalImplementation) => {
136+
return {
137+
...originalImplementation,
138+
registerOptions: (input) => {
139+
return originalImplementation.registerOptions({
140+
...input,
141+
attestation: "direct",
142+
residentKey: "required",
143+
timeout: 10 * 1000,
144+
userVerification: "required",
145+
displayName: "John Doe",
146+
supportedAlgorithms: [-257],
147+
relyingPartyId: 'example.com',
148+
relyingPartyName: 'example',
149+
origin: 'https://example.com',
150+
});
151+
},
152+
};
153+
},
154+
},
155+
}),
156+
Session.init() // initializes session features
157+
]
158+
});
159+
```
160+
161+
<br />
162+
163+
#### Input properties
164+
165+
| Name | Type | Description | Default Value |
166+
|----------|----------|-------------|---------------|
167+
| `relyingPartyId` | `string` | The domain name of your application that will be shown to the user during authentication. | - |
168+
| `relyingPartyName` | `string` | The display name of your application that will be shown to the user during authentication. | - |
169+
| `origin` | `string` | The origin URL that the credential is generated on. | - |
170+
| `timeout` | `number` | The time in milliseconds that the user has to complete the credential generation process. | `6000` |
171+
| `attestation` | `"none" \| "indirect" \| "direct" \| "enterprise"` | The amount of information about the authenticator that gets included in the attestation statement. This controls what authenticators are supported. | `none` |
172+
| `supportedAlgorithms` | `number[]` | The cryptographic algorithms that can be used for generating credentials. Different authenticators support different algorithms. | `[-8, -7, -257]` |
173+
| `residentKey` | `"discouraged" \| "preferred" \| "required"` | Whether the credential should be stored on the authenticator device. | `required` |
174+
| `userVerification` | `"discouraged" \| "preferred" \| "required"` | Whether user verification (like PIN or biometrics) is required. | `preferred` |
175+
| `displayName` | `string` | The display name of the user. | The user's `email` property |
176+
177+
178+
</BackendTabs.TabItem>
179+
180+
<BackendTabs.TabItem value="go">
181+
182+
:::caution
183+
184+
At the moment there is no support for using passkeys authentication in the Go SDK.
185+
186+
:::
187+
188+
</BackendTabs.TabItem>
189+
190+
<BackendTabs.TabItem value="python">
191+
192+
:::caution
193+
194+
At the moment there is no support for using passkeys authentication in the Python SDK.
195+
196+
:::
197+
198+
</BackendTabs.TabItem>
199+
200+
</BackendTabs>
201+
202+
---
203+
204+
## Credential validation
205+
206+
When a user attempts to login, their credential is used to sign a challenge on the client.
207+
The frontend SDK uses the [`navigator.credentials.get`](https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get) function to resolve this.
208+
209+
The options for signing the challenge are generated on the server, through the backend SDK, and then sent to the client.
210+
To change those, you need to override the `signInOptions` function.
211+
212+
213+
<BackendTabs>
214+
215+
<BackendTabs.TabItem value="nodejs">
216+
217+
```ts
218+
import supertokens from "supertokens-node";
219+
import Session from "supertokens-node/recipe/session";
220+
import WebAuthn from "supertokens-node/recipe/webauthn";
221+
222+
supertokens.init({
223+
framework: "express",
224+
supertokens: {
225+
// https://try.supertokens.com is for demo purposes. Replace this with the address of your core instance (sign up on supertokens.com), or self host a core.
226+
connectionURI: "https://try.supertokens.com",
227+
// apiKey: <API_KEY(if configured)>,
228+
},
229+
appInfo: {
230+
// learn more about this on https://supertokens.com/docs/session/appinfo
231+
appName: "<YOUR_APP_NAME>",
232+
apiDomain: "<YOUR_API_DOMAIN>",
233+
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
234+
apiBasePath: "/auth",
235+
websiteBasePath: "/auth"
236+
},
237+
recipeList: [
238+
WebAuthn.init({
239+
override: {
240+
functions: (originalImplementation) => {
241+
return {
242+
...originalImplementation,
243+
signInOptions: (input) => {
244+
return originalImplementation.signInOptions({
245+
...input,
246+
timeout: 10 * 1000,
247+
userVerification: "required",
248+
relyingPartyId: 'example.com',
249+
origin: 'https://example.com',
250+
});
251+
},
252+
};
253+
},
254+
},
255+
}),
256+
Session.init() // initializes session features
257+
]
258+
});
259+
```
260+
261+
#### Input properties
262+
263+
| Name | Type | Description | Default |
264+
|----------|----------|-------------|---------|
265+
| `relyingPartyId` | `string` | The domain name of your application that will be used for validating the credential. | - |
266+
| `relyingPartyName` | `string` | The human-readable name of your application. | - |
267+
| `origin` | `string` | The origin URL that the credential is generated on. | - |
268+
| `timeout` | `number` | The time in milliseconds that the user has to complete the credential validation process. | `6000` |
269+
| `userVerification` | `"discouraged" \| "preferred" \| "required"` | Controls whether user verification (like PIN or biometrics) is required. | `preferred` |
270+
271+
</BackendTabs.TabItem>
272+
273+
<BackendTabs.TabItem value="go">
274+
275+
:::caution
276+
277+
At the moment there is no support for using passkeys authentication in the Go SDK.
278+
279+
:::
280+
281+
</BackendTabs.TabItem>
282+
283+
<BackendTabs.TabItem value="python">
284+
285+
:::caution
286+
287+
At the moment there is no support for using passkeys authentication in the Python SDK.
288+
289+
:::
290+
291+
</BackendTabs.TabItem>
292+
293+
</BackendTabs>
294+
295+

0 commit comments

Comments
 (0)