Skip to content

Commit 3377f1a

Browse files
guabuguabu
committed
chore(docs): add support for backchannel authentication
1 parent 2c0126e commit 3377f1a

File tree

2 files changed

+78
-47
lines changed

2 files changed

+78
-47
lines changed

‎EXAMPLES.md‎

Lines changed: 77 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
- [Cookie Configuration](#cookie-configuration)
3333
- [Transaction Cookie Configuration](#transaction-cookie-configuration)
3434
- [Database sessions](#database-sessions)
35+
- [Back-Channel Authentication](#back-channel-authentication)
3536
- [Back-Channel Logout](#back-channel-logout)
3637
- [Combining middleware](#combining-middleware)
3738
- [ID Token claims and the user object](#id-token-claims-and-the-user-object)
@@ -48,8 +49,8 @@
4849
- [On the server (Pages Router)](#on-the-server-pages-router-3)
4950
- [Middleware](#middleware-3)
5051
- [Customizing Auth Handlers](#customizing-auth-handlers)
51-
- [Run custom code before Auth Handlers](#run-custom-code-before-auth-handlers)
52-
- [Run code after callback](#run-code-after-callback)
52+
- [Run custom code before Auth Handlers](#run-custom-code-before-auth-handlers)
53+
- [Run code after callback](#run-code-after-callback)
5354

5455
## Passing authorization parameters
5556

@@ -965,6 +966,7 @@ export const auth0 = new Auth0Client({
965966
## Transaction Cookie Configuration
966967

967968
### Customizing Transaction Cookie Expiration
969+
968970
You can configure transaction cookies expiration by providing a `maxAge` proeprty for `transactionCookie`.
969971

970972
```ts
@@ -975,11 +977,13 @@ export const auth0 = new Auth0Client({
975977
},
976978
}
977979
```
980+
978981
Transaction cookies are used to maintain state during authentication flows. The SDK provides several configuration options to manage transaction cookie behavior and prevent cookie accumulation issues.
979982
980983
### Transaction Management Modes
981984
982985
**Parallel Transactions (Default)**
986+
983987
```ts
984988
const authClient = new Auth0Client({
985989
enableParallelTransactions: true // Default: allows multiple concurrent logins
@@ -988,6 +992,7 @@ const authClient = new Auth0Client({
988992
```
989993
990994
**Single Transaction Mode**
995+
991996
```ts
992997
const authClient = new Auth0Client({
993998
enableParallelTransactions: false // Only one active transaction at a time
@@ -996,25 +1001,27 @@ const authClient = new Auth0Client({
9961001
```
9971002
9981003
**Use Parallel Transactions (Default) When:**
1004+
9991005
- Users might open multiple tabs and attempt to log in simultaneously
10001006
- You want maximum compatibility with typical user behavior
10011007
- Your application supports multiple concurrent authentication flows
10021008
10031009
**Use Single Transaction Mode When:**
1010+
10041011
- You want to prevent cookie accumulation issues in applications with frequent login attempts
10051012
- You prefer simpler transaction management
10061013
- Users typically don't need multiple concurrent login flows
10071014
- You're experiencing cookie header size limits due to abandoned transaction cookies edge cases
10081015
10091016
### Transaction Cookie Options
10101017
1011-
| Option | Type | Description |
1012-
| -------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1013-
| cookieOptions.maxAge | `number` | The expiration time for transaction cookies in seconds. Defaults to `3600` (1 hour). After this time, abandoned transaction cookies will expire automatically. |
1014-
| cookieOptions.prefix | `string` | The prefix for transaction cookie names. Defaults to `__txn_`. In parallel mode, cookies are named `__txn_{state}`. In single mode, just `__txn_`. |
1015-
| cookieOptions.sameSite | `"strict" \| "lax" \| "none"` | Controls when the cookie is sent with cross-site requests. Defaults to `"lax"`. |
1016-
| cookieOptions.secure | `boolean` | When `true`, the cookie will only be sent over HTTPS connections. Automatically determined based on your application's base URL protocol if not specified. |
1017-
| cookieOptions.path | `string` | Specifies the URL path for which the cookie is valid. Defaults to `"/"`. |
1018+
| Option | Type | Description |
1019+
| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1020+
| cookieOptions.maxAge | `number` | The expiration time for transaction cookies in seconds. Defaults to `3600` (1 hour). After this time, abandoned transaction cookies will expire automatically. |
1021+
| cookieOptions.prefix | `string` | The prefix for transaction cookie names. Defaults to `__txn_`. In parallel mode, cookies are named `__txn_{state}`. In single mode, just `__txn_`. |
1022+
| cookieOptions.sameSite | `"strict" \| "lax" \| "none"` | Controls when the cookie is sent with cross-site requests. Defaults to `"lax"`. |
1023+
| cookieOptions.secure | `boolean` | When `true`, the cookie will only be sent over HTTPS connections. Automatically determined based on your application's base URL protocol if not specified. |
1024+
| cookieOptions.path | `string` | Specifies the URL path for which the cookie is valid. Defaults to `"/"`. |
10181025
10191026
## Database sessions
10201027
@@ -1041,6 +1048,28 @@ export const auth0 = new Auth0Client({
10411048
});
10421049
```
10431050
1051+
## Using Client-Initiated Backchannel Authentication
1052+
1053+
Using Client-Initiated Backchannel Authentication can be done by calling `backchannelAuthentication()`:
1054+
1055+
```ts
1056+
import { auth0 } from "@/lib/auth0";
1057+
1058+
const tokenResponse = await auth0.backchannelAuthentication({
1059+
bindingMessage: "",
1060+
loginHint: {
1061+
sub: "auth0|123456789"
1062+
}
1063+
});
1064+
```
1065+
1066+
- `bindingMessage`: A human-readable message to be displayed at the consumption device and authentication device. This allows the user to ensure the transaction initiated by the consumption device is the same that triggers the action on the authentication device.
1067+
- `loginHint.sub`: The `sub` claim of the user that is trying to login using Client-Initiated Backchannel Authentication, and to which a push notification to authorize the login will be sent.
1068+
1069+
> [!IMPORTANT]
1070+
> Using Client-Initiated Backchannel Authentication requires the feature to be enabled in the Auth0 dashboard.
1071+
> Read [the Auth0 docs](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow) to learn more about Client-Initiated Backchannel Authentication.
1072+
10441073
## Back-Channel Logout
10451074
10461075
The SDK can be configured to listen to [Back-Channel Logout](https://auth0.com/docs/authenticate/login/logout/back-channel-logout) events. By default, a route will be mounted `/auth/backchannel-logout` which will verify the logout token and call the `deleteByLogoutToken` method of your session store implementation to allow you to remove the session.
@@ -1402,6 +1431,7 @@ export async function middleware(request: NextRequest) {
14021431
Authentication routes (`/auth/login`, `/auth/logout`, `/auth/callback`) are handled automatically by the middleware. You can intercept these routes in your middleware to run custom logic before the auth handlers execute.
14031432
14041433
This approach allows you to:
1434+
14051435
- Run custom code before authentication actions (logging, analytics, validation)
14061436
- Modify the response (set cookies, headers, etc.)
14071437
- Implement custom redirects or early returns when needed
@@ -1413,48 +1443,49 @@ The middleware-based approach provides the same level of control as v3's custom
14131443
### Run custom code before Auth Handlers
14141444
14151445
Following example shows how to run custom logic before the response of `logout` handler is returned:
1446+
14161447
```ts
14171448
export async function middleware(request) {
1449+
// prepare NextResponse object from auth0 middleware
1450+
const authRes = await auth0.middleware(request);
14181451

1419-
// prepare NextResponse object from auth0 middleware
1420-
const authRes = await auth0.middleware(request);
1421-
1422-
// The following interceptUrls can be used:
1423-
// "/auth/login" : intercept login auth handler
1424-
// "/auth/logout" : intercept logout auth handler
1425-
// "/auth/callback" : intercept callback auth handler
1426-
// "/your/login/returnTo/url" : intercept redirect after login, this is the login returnTo url
1427-
// "/your/logout/returnTo/url" : intercept redirect after logout, this is the logout returnTo url
1428-
1429-
const interceptUrl = "/auth/logout";
1430-
1431-
// intercept auth handler
1432-
if (request.nextUrl.pathname === interceptUrl) {
1433-
// do custom stuff
1434-
console.log("Pre-logout code")
1435-
1436-
// Example: Set a cookie
1437-
authRes.cookies.set('myCustomCookie', 'cookieValue', { path: '/' });
1438-
// Example: Set another cookie with options
1439-
authRes.cookies.set({
1440-
name: 'anotherCookie',
1441-
value: 'anotherValue',
1442-
httpOnly: true,
1443-
path: '/',
1444-
});
1445-
1446-
// Example: Delete a cookie
1447-
// authRes.cookies.delete('cookieNameToDelete');
1448-
1449-
// you can also do an early return here with your own NextResponse object
1450-
// return NextResponse.redirect(new URL('/custom-logout-page'));
1451-
}
1452+
// The following interceptUrls can be used:
1453+
// "/auth/login" : intercept login auth handler
1454+
// "/auth/logout" : intercept logout auth handler
1455+
// "/auth/callback" : intercept callback auth handler
1456+
// "/your/login/returnTo/url" : intercept redirect after login, this is the login returnTo url
1457+
// "/your/logout/returnTo/url" : intercept redirect after logout, this is the logout returnTo url
1458+
1459+
const interceptUrl = "/auth/logout";
1460+
1461+
// intercept auth handler
1462+
if (request.nextUrl.pathname === interceptUrl) {
1463+
// do custom stuff
1464+
console.log("Pre-logout code");
1465+
1466+
// Example: Set a cookie
1467+
authRes.cookies.set("myCustomCookie", "cookieValue", { path: "/" });
1468+
// Example: Set another cookie with options
1469+
authRes.cookies.set({
1470+
name: "anotherCookie",
1471+
value: "anotherValue",
1472+
httpOnly: true,
1473+
path: "/"
1474+
});
14521475

1453-
// return the original auth0-handled NextResponse object
1454-
return authRes
1476+
// Example: Delete a cookie
1477+
// authRes.cookies.delete('cookieNameToDelete');
1478+
1479+
// you can also do an early return here with your own NextResponse object
1480+
// return NextResponse.redirect(new URL('/custom-logout-page'));
1481+
}
1482+
1483+
// return the original auth0-handled NextResponse object
1484+
return authRes;
14551485
}
14561486
```
14571487
14581488
### Run code after callback
1459-
Please refer to [onCallback](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#oncallback)
1460-
for details on how to run code after callback.
1489+
1490+
Please refer to [onCallback](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#oncallback)
1491+
for details on how to run code after callback.

‎src/server/client.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -744,7 +744,7 @@ export class Auth0Client {
744744
* Using Client-Initiated Backchannel Authentication requires the feature to be enabled in the Auth0 dashboard.
745745
* @see https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow
746746
*/
747-
async backchannelLogin(options: BackchannelAuthenticationOptions) {
747+
async backchannelAuthentication(options: BackchannelAuthenticationOptions) {
748748
const [error, response] =
749749
await this.authClient.backchannelAuthentication(options);
750750

0 commit comments

Comments
 (0)