Skip to content

feat: add support for backchannel authentication #2261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

guabu
Copy link
Contributor

@guabu guabu commented Aug 7, 2025

📋 Changes

Adds support for Client-Initiated Backchannel Authentication. A new method backchannelAuthentication is exposed on the client that enables developers to initiate a backchannel authentication request and poll the token endpoint until it's complete.

The openid-client was added to handle the polling and retry logic without having to re-implement it ourselves using oauth4webapi and to start moving the implementation closer to that of auth0-auth-js.

🎯 Testing

  1. Call the backchannelAuthentication method from a server route/action
  2. Authorize or reject the authorization via a Guardian app
  3. The SDK will return the token set or error accordingly

@guabu guabu requested a review from a team as a code owner August 7, 2025 07:29
@adamjmcgrath
Copy link
Contributor

The openid-client was added to handle the polling and retry logic without having to re-implement it ourselves using oauth4webapi and to start moving the implementation closer to that of auth0-auth-js.

Would it make more sense to use auth0-auth-js for CIBA now if that's what the sdk is going to end up using?

@codecov-commenter
Copy link

Codecov Report

❌ Patch coverage is 89.78102% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.61%. Comparing base (0e83495) to head (6d33068).
⚠️ Report is 11 commits behind head on main.

Files with missing lines Patch % Lines
src/server/auth-client.ts 93.63% 7 Missing ⚠️
src/server/client.ts 12.50% 7 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2261      +/-   ##
==========================================
+ Coverage   85.39%   85.61%   +0.21%     
==========================================
  Files          26       26              
  Lines        2471     2606     +135     
  Branches      462      477      +15     
==========================================
+ Hits         2110     2231     +121     
- Misses        355      369      +14     
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment on lines +953 to +960
return [
new BackchannelAuthenticationError({
cause: new OAuth2Error({
code: e.error,
message: e.error_description
})
}),
null
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Errors that come from Auth0 in the redirect_uri callback may contain reflected user input via the OpenID Connect error and error_description query parameter. You should not render the error message, or error and error_description properties without properly escaping them first.

See

* You should **not** render the error `message`, or `error` and `error_description` properties without properly escaping them first.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is passing e.error_description safe here?

Copy link
Contributor

@tusharpandey13 tusharpandey13 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we think that exporting openid-client polling configuration can be useful here instead of hardcoding the default config?
https://github.com/panva/openid-client/blob/main/docs/interfaces/BackchannelAuthenticationGrantPollOptions.md

* Using Client-Initiated Backchannel Authentication requires the feature to be enabled in the Auth0 dashboard.
* @see https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow
*/
async getTokenByBackchannelAuth(options: BackchannelAuthenticationOptions) {
Copy link
Contributor

@tusharpandey13 tusharpandey13 Aug 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Authenticates using Client-Initiated Backchannel Authentication and returns the token set and optionally the ID token claims and authorization details.

Should this be named as authenticateWithBackchannel instead?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants