Skip to content

Commit e908314

Browse files
niftyvictorniftyvictor
committed
docs improv
1 parent 46983ba commit e908314

File tree

6 files changed

+13440
-231
lines changed

6 files changed

+13440
-231
lines changed

‎v3/docs/authentication/webauthn/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
2-
"label": "Passkey Authentication",
2+
"label": "Passkeys",
33
"position": 7
44
}

‎v3/docs/authentication/webauthn/customise-credential-validation.mdx

Lines changed: 28 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,21 @@ The WebAuthN flow allows the user to customise the way credentials are generated
1212

1313
For example, in the case of a banking app, the user may want to use a YubiKey to generate and validate credentials. In this case, the user may want to use a required PIN or a biometric factor to validate the credential.
1414

15-
TODO: Add correct link
16-
Most of the customisation is done through function overrides. You can find more details about how they work here: [Overrides](https://deploy-preview-869--starlit-elf-06ee1a.netlify.app/docs/references/sdks/functions-overrides/backend-functions-override).
15+
Most of the customisation is done through function overrides. You can find more details about how they work here: [Overrides](/docs/references/sdks/functions-overrides/backend-functions-override).
1716

1817
## Recipe Configuration
1918

20-
TODO: Add correct link
21-
The recipe configuration is done by the `init` function. You can find more details about the recipe configuration here: [Recipe Configuration](#).
19+
The recipe configuration is done by the `init` function. You can find more details about the recipe configuration here: [Recipe Configuration](https://supertokens.com/docs/nodejs/modules/recipe_webauthn.html#init).
2220

2321
When configuring the recipe, you can pass the following options:
24-
- **Relying Party**: Details about the entity for which the credential is being generated. This includes the domain name (Relying Party ID) and display name (Relying Party Name) of your application that will be shown to the user during authentication. The Relying Party ID defaults to the API domain (`apiBasePath`) and the Relying Parth Name defaults to the application name (`appName`).
25-
- **Origin**: The origin URL that the credential is generated on. Defaults to the origin of the request.
22+
23+
| Option | Key Name | Description | Default Value |
24+
|--------|----------|-------------|---------------|
25+
| Relying Party ID | `getRelyingPartyId` | The domain name of your application that will be shown to the user during authentication | API domain (`apiBasePath`) |
26+
| Relying Party Name | `getRelyingPartyName` | The display name of your application that will be shown to the user during authentication | Application name (`appName`) |
27+
| Origin | `getOrigin` | The origin URL that the credential is generated on | Origin of the request |
28+
29+
All of the above options are optional and if not provided, the recipe will use the default values. For more details on the default values, please refer to the [Recipe Configuration](https://supertokens.com/docs/nodejs/modules/recipe_webauthn.html#init) documentation.
2630

2731
```ts
2832
import supertokens from "supertokens-node";
@@ -69,14 +73,17 @@ The credential is generated based on a set of options that you can pass to the `
6973

7074
The possible configurable options are:
7175

72-
- **Relying Party**: Details about the entity for which the credential is being generated. This includes the domain name (Relying Party ID) and display name (Relying Party Name) of your application that will be shown to the user during authentication. The Relying Party ID defaults to the API domain (`apiBasePath`) and the Relying Parth Name defaults to the application name (`appName`).
73-
- **Origin**: The origin URL that the credential is generated on. Defaults to the origin of the request.
74-
- **Timeout**: The time in milliseconds that the user has to complete the credential generation process. Defaults to `6000`.
75-
- **Attestation**: Controls how much information about the authenticator is included in the attestation statement. This controls what authenticators are supported. Defaults to `none`.
76-
- **Supported Algorithms**: The cryptographic algorithms that can be used for generating credentials. Different authenticators support different algorithms. Defaults to `[-8, -7, -257]`.
77-
- **Resident Key**: Whether the credential should be stored on the authenticator device. Defaults to `required`.
78-
- **User Verification**: Controls whether user verification (like PIN or biometrics) is required. Defaults to `preferred`.
79-
- **User Display Name**: The display name of the user. Defaults to the `email` field.
76+
| Option | Key Name | Description | Default Value |
77+
|--------|----------|-------------|---------------|
78+
| Relying Party ID | `relyingPartyId` | The domain name of your application that will be shown to the user during authentication. | API domain (`apiBasePath`) |
79+
| Relying Party Name | `relyingPartyName` | The display name of your application that will be shown to the user during authentication. | Application name (`appName`) |
80+
| Origin | `origin` | The origin URL that the credential is generated on. | Origin of the request |
81+
| Timeout | `timeout` | The time in milliseconds that the user has to complete the credential generation process. | `6000` |
82+
| Attestation | `attestation` | Controls how much information about the authenticator is included in the attestation statement. This controls what authenticators are supported. | `none` |
83+
| Supported Algorithms | `supportedAlgorithms` | The cryptographic algorithms that can be used for generating credentials. Different authenticators support different algorithms. | `[-8, -7, -257]` |
84+
| Resident Key | `residentKey` | Whether the credential should be stored on the authenticator device. | `required` |
85+
| User Verification | `userVerification` | Controls whether user verification (like PIN or biometrics) is required. | `preferred` |
86+
| User Display Name | `displayName` | The display name of the user. | `email` field |
8087

8188
Below is an example of how you can customise the credential generation options.
8289

@@ -133,10 +140,13 @@ supertokens.init({
133140

134141
When a user attempts to login using a WebAuthN credential, the credential is used for signing a challenge through the client using `navigator.credentials.get` function. The options for signing the challenge are generated on the server through the SDK and defined how the authentication will take place:
135142

136-
- **Relying Party ID**: The domain name (Relying Party ID) of your application that will be used for validating the credential.
137-
- **Origin**: The origin URL that the credential is generated on. Defaults to the origin of the request.
138-
- **Timeout**: The time in milliseconds that the user has to complete the credential validation process. Defaults to `6000`.
139-
- **User Verification**: Controls whether user verification (like PIN or biometrics) is required. Defaults to `preferred`.
143+
| Option | Key Name | Description | Default |
144+
|--------|----------|-------------|---------|
145+
| **Relying Party ID** | `relyingPartyId` | The domain name of your application that will be used for validating the credential. | - |
146+
| **Relying Party Name** | `relyingPartyName` | The human-readable name of your application. | - |
147+
| **Origin** | `origin` | The origin URL that the credential is generated on. | Origin of the request |
148+
| **Timeout** | `timeout` | The time in milliseconds that the user has to complete the credential validation process. | `6000` |
149+
| **User Verification** | `userVerification` | Controls whether user verification (like PIN or biometrics) is required. | `preferred` |
140150

141151
Below is an example of how you can customise the credential generation options.
142152

‎v3/docs/authentication/webauthn/initial-setup.mdx

Lines changed: 129 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,20 @@ sidebar_position: 2
66

77
import { UIType } from "/src/components/UITypeSwitch";
88

9+
import Tabs from '@theme/Tabs';
10+
import TabItem from '@theme/TabItem';
11+
import {
12+
FrontendPrebuiltUITabs,
13+
BackendTabs,
14+
FrontendCustomUITabs,
15+
ReactRouterVersionTabs,
16+
} from "/src/components/Tabs";
17+
import { AppInfoForm } from "/src/components/Forms";
18+
import { NodePackageManagerCard, JavascriptHttpLibraryCard, NpmOrScriptsCard, MobileFrameworksCard } from "/src/components/Cards";
19+
import { Question, Answer } from "/src/components/Question";
20+
import { ReferenceCard } from "/src/components/Cards";
21+
import ReactRouterCallout from "/docs/_blocks/react-router-callout.mdx";
22+
923
# Quickstart
1024

1125
## Overview
@@ -14,8 +28,9 @@ This page will show you how to add the WebAuthn recipe to your project. The tuto
1428

1529
## Before you start
1630

17-
-- important note --
18-
These intructions assume that you already have gone through our main quickstart guide. If you have skipped that page please follow the tutorial and return here once you're done.
31+
:::info Note
32+
These instructions assume that you already have gone through our main quickstart guide. If you have skipped that page please follow the tutorial and return here once you're done.
33+
:::
1934

2035

2136
## Steps
@@ -24,22 +39,122 @@ These intructions assume that you already have gone through our main quickstart
2439

2540
<UIType.PrebuiltUIContent>
2641

27-
prebuilt
2842

43+
### 1. Initialize the Frontend SDK
44+
45+
<FrontendPrebuiltUITabs showMobileTab>
46+
<FrontendPrebuiltUITabs.TabItem value="reactjs">
47+
#### 1.1 Add the `Webauthn` recipe in your main configuration file.
48+
49+
```tsx
50+
import React from 'react';
51+
52+
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
53+
// highlight-next-line
54+
import Webauthn from "supertokens-auth-react/recipe/webauthn";
55+
import Session from "supertokens-auth-react/recipe/session";
56+
57+
SuperTokens.init({
58+
appInfo: {
59+
// learn more about this on https://supertokens.com/docs/references/app-info
60+
apiDomain: "",
61+
apiBasePath: "",
62+
appName: "...",
63+
},
64+
recipeList: [
65+
// highlight-start
66+
WebAuthn.init(),
67+
// highlight-end
68+
Session.init()
69+
]
70+
});
71+
```
72+
73+
#### 1.2 Include the pre-built UI components in your application.
74+
75+
In order for the **pre-built UI** to render inside your application, you have to specify which routes show the authentication components.
76+
The **React SDK** uses [**React Router**](https://reactrouter.com/en/main) under the hood to achieve this.
77+
Based on whether you already use this package or not in your project, there are two different ways of configuring the routes.
78+
79+
<Question question="Do you use react-router-dom?" defaultAnswer="Yes">
80+
<Answer title="Yes">
81+
```tsx
82+
import React from 'react';
83+
import {
84+
BrowserRouter,
85+
Routes,
86+
Route,
87+
Link
88+
} from "react-router-dom";
89+
90+
// highlight-next-line
91+
import { WebauthnPreBuiltUI } from 'supertokens-auth-react/recipe/webauthn/prebuiltui';
92+
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
93+
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
94+
import * as reactRouterDom from "react-router-dom";
95+
96+
class App extends React.Component {
97+
render() {
98+
return (
99+
<SuperTokensWrapper>
100+
<BrowserRouter>
101+
<Routes>
102+
{/*This renders the login UI on the ^{appInfo.websiteBasePath} route*/}
103+
// highlight-next-line
104+
{getSuperTokensRoutesForReactRouterDom(reactRouterDom, [WebauthnPreBuiltUI])}
105+
{/*Your app routes*/}
106+
</Routes>
107+
</BrowserRouter>
108+
</SuperTokensWrapper>
109+
);
110+
}
111+
}
112+
```
113+
114+
<ReactRouterCallout />
115+
</Answer>
116+
<Answer title="No">
117+
118+
```tsx
119+
import React from 'react';
120+
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
121+
// highlight-next-line
122+
import { WebauthnPreBuiltUI } from 'supertokens-auth-react/recipe/webauthn/prebuiltui';
123+
import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui";
124+
125+
class App extends React.Component {
126+
render() {
127+
// highlight-start
128+
if (canHandleRoute([WebauthnPreBuiltUI])) {
129+
// This renders the login UI on the ^{appInfo.websiteBasePath} route
130+
return getRoutingComponent([WebauthnPreBuiltUI])
131+
}
132+
133+
// highlight-end
134+
135+
return (
136+
<SuperTokensWrapper>{/*Your app*/}</SuperTokensWrapper>
137+
);
138+
}
139+
}
140+
```
141+
</Answer>
142+
</Question>
143+
</FrontendPrebuiltUITabs.TabItem>
144+
</FrontendPrebuiltUITabs>
29145
</UIType.PrebuiltUIContent>
30146

31147
<UIType.CustomUIContent>
32148

33-
### 1. Initialize the Frontend SDK
34-
149+
#### 1.1 Add the `Webauthn` recipe in your main configuration file.
35150

36151
Call the SDK init function at the start of your application. The invocation includes the main configuration details, as well as the recipes that you will be using in your setup.
37152

38153
- Web
39154
```ts
40155
import SuperTokens from 'supertokens-web-js';
41156
import Session from 'supertokens-web-js/recipe/session';
42-
import WebAuthN from 'supertokens-web-js/recipe/webauthn'
157+
import Webauthn from 'supertokens-web-js/recipe/webauthn'
43158

44159
SuperTokens.init({
45160
appInfo: {
@@ -49,17 +164,12 @@ SuperTokens.init({
49164
},
50165
recipeList: [
51166
Session.init(),
52-
WebAuthN.init(),
167+
Webauthn.init(),
53168
],
54169
});
55170
```
56171

57-
### 2. Add the Authentication UI
58-
59-
The following section will demonstrate you what aspects you need to cover in order to implement the UI for the WebAuthN flow.
60-
61-
62-
#### 2.1 Add the Signup Form
172+
#### 1.2 Add the Signup Form
63173

64174
You will have to first add the UI elements which will render your form. When the users submits the form you will have to call the following API to create the credential and send it to the backend in order to create the user and store the credential.
65175

@@ -111,7 +221,7 @@ async function signUp(email: string) {
111221
}
112222
```
113223

114-
#### 2.2 Add the Login Form
224+
#### 1.3 Add the Login Form
115225

116226
You will have to first add the UI elements which will render your form. When the users submits the form you will have to call the following API to use the credential and send the response to the backend in order to login the user.
117227

@@ -155,12 +265,13 @@ async function signIn(email: string) {
155265
}
156266
}
157267
```
268+
</UIType.CustomUIContent>
158269

159-
### 3. Initialize the Backend SDK
270+
### 2. Initialize the Backend SDK
160271

161272
You will have to intialize the Backend SDK alongside the code that starts your server. The init call will include configuration details for your app, how the backend will connect to the SuperTokens Core, as well as the Recipes that will be used in your setup.
162273

163-
For the WebAuthN recipe, you can also specify the following optional parameters:
274+
For the WebAuthN recipe, you can also specify the following optional parameters:
164275
- `emailDelivery`: Configure how verification emails are sent to users. You can use the default email service or integrate your own email delivery provider.
165276

166277
- `getRelyingPartyId`: Set the domain name that will be associated with the WebAuthn credentials (e.g. "example.com"). This helps ensure credentials can only be used on your domain. It defaults to the origin domain.
@@ -195,22 +306,12 @@ supertokens.init({
195306
websiteBasePath: "/auth",
196307
},
197308
recipeList: [
198-
WebAuthN.init({
199-
getRelyingPartyId: () => {
200-
return '<YOUR_API_DOMAIN>';
201-
},
202-
getRelyingPartyName: () => {
203-
return '<YOUR_APP_NAME>';
204-
},
205-
}),
206-
Session.init()
309+
WebAuthN.init(),
310+
Session.init()
207311
]
208312
});
209313
```
210314

211-
</UIType.CustomUIContent>
212-
213-
214315
## Next Steps
215316

216317
Now that you have completed the main setup you can explore more advanced topics related to the WebAuthN recipe.

‎v3/docs/authentication/webauthn/introduction.mdx

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -31,16 +31,8 @@ Key aspects of passkeys include:
3131

3232
- **Platform Integration**: Passkeys are deeply integrated into operating systems and browsers, providing a seamless experience across different platforms and devices
3333

34-
- **Enhanced Security**:
35-
- End-to-end encryption during syncing
36-
- Phishing-resistant by design
37-
- Based on public key cryptography
38-
- Protected by biometric authentication or device PIN
39-
4034
- **Improved User Experience**:
41-
- No passwords to remember
4235
- Automatic syncing between devices
43-
- Quick and easy authentication using biometrics
4436
- Familiar system UI for authentication
4537

4638
While passkeys and WebAuthn credentials share the same underlying technology, passkeys add the convenience of cross-device availability while maintaining the strong security guarantees of WebAuthn.
@@ -51,7 +43,9 @@ Before diving into WebAuthn implementation, it's important to understand the key
5143

5244
For a more detailed explanation of the WebAuthn specification, you can refer to the [WebAuthn specification](https://www.w3.org/TR/webauthn/).
5345

54-
Note: Throughout our documentation, the terms "passkey" and "credential" are used interchangeably, though they have subtle technical differences explained below.
46+
:::info Note
47+
Throughout our documentation, the terms "passkey" and "credential" are used interchangeably, though they have subtle technical differences explained below.
48+
:::
5549

5650
- **Passkey**: A user-friendly term for WebAuthn credentials that are synced across a user's devices. Passkeys are:
5751
- More convenient than traditional credentials as they sync automatically
@@ -89,7 +83,6 @@ Note: Throughout our documentation, the terms "passkey" and "credential" are use
8983

9084
The WebAuthn feature in SuperTokens provides:
9185

92-
- Complete implementation of the WebAuthn standard
9386
- Support for platform authenticators (biometric sensors) and roaming authenticators (security keys)
9487
- Automatic handling of device registration and authentication
9588
- Integration with other SuperTokens features

0 commit comments

Comments
 (0)