Skip to content

Commit e413709

Browse files
bcbogdanbcbogdan
authored
Merge pull request #896 from supertokens/feat/webauthn/base
Add the webauthn docs
2 parents 0ba4167 + e83890c commit e413709

File tree

17 files changed

+14880
-6635
lines changed

17 files changed

+14880
-6635
lines changed

‎.vale/SuperTokens/headings.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,4 @@ exceptions:
5353
- JWTs
5454
- UI
5555
- Token
56+
- WebAuthn

‎docs/authentication/_passkeys/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Passkeys",
3+
"position": 7
4+
}

‎docs/authentication/_passkeys/customization.mdx

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

0 commit comments

Comments
 (0)