Feature: CIBA Branding and Documentation

[btiernay]

Overview

The Auth0 JavaScript SDK already implements Client-Initiated Backchannel Authentication through 1 and 2 . This specification outlines requirements to rebrand this functionality with the searchable "CIBA" acronym and enhance documentation with complete working examples.

Current State Analysis

The SDK provides CIBA functionality through two mechanisms:

• Core AuthClient: Low-level CIBA implementation with automatic polling 1
• ServerClient: Server-side CIBA with session management 2

Requirements

1. Documentation Updates

Main README Enhancement
Update package descriptions to include "CIBA" terminology alongside existing "Client-Initiated Backchannel Authentication" references.

Examples Documentation
Update 3 and 4 to use "CIBA" acronym in section headers for searchability.

2. Complete CIBA Examples

Core AuthClient CIBA Example
Based on the existing implementation 1 :

import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!
});

// CIBA (Client-Initiated Backchannel Authentication) Flow
const cibaResponse = await authClient.backchannelAuthentication({
  bindingMessage: 'Login request from mobile app',
  loginHint: {
    sub: 'auth0|123456789' // User's subject identifier
  },
  authorizationParams: {
    audience: 'https://api.example.com',
    scope: 'openid profile email offline_access'
  }
});

console.log('CIBA tokens:', cibaResponse.accessToken, cibaResponse.idToken);

Server-Side CIBA with Session Management
Based on 2 :

import { ServerClient, StatefulStateStore, CookieTransactionStore } from '@auth0/auth0-server-js';

const auth0 = new ServerClient<StoreOptions>({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  stateStore: new StatefulStateStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new FastifyCookieHandler()),
  transactionStore: new CookieTransactionStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new FastifyCookieHandler())
});

// CIBA endpoint for push notification login
fastify.post('/auth/ciba-login', async (request, reply) => {
  const storeOptions = { request, reply };
  const { userId, deviceInfo } = request.body;
  
  try {
    // Initiate CIBA flow - sends push notification to user's device
    const cibaResult = await auth0.loginBackchannel({
      bindingMessage: `Login from ${deviceInfo.name}`,
      loginHint: { sub: userId },
      authorizationParams: {
        audience: 'https://api.example.com'
      }
    }, storeOptions);
    
    reply.send({ 
      success: true, 
      message: 'Push notification sent. Please approve on your device.',
      authorizationDetails: cibaResult.authorizationDetails 
    });
  } catch (error) {
    reply.code(400).send({ error: 'CIBA authentication failed' });
  }
});

// Check CIBA login status
fastify.get('/auth/ciba-status', async (request, reply) => {
  const storeOptions = { request, reply };
  const user = await auth0.getUser(storeOptions);
  
  if (user) {
    const tokenSet = await auth0.getAccessToken(storeOptions);
    reply.send({ authenticated: true, user, accessToken: tokenSet.accessToken });
  } else {
    reply.send({ authenticated: false });
  }
});

CIBA with Rich Authorization Requests (RAR)
Leveraging the existing RAR support 5 :

// CIBA with specific authorization details for high-value transactions
const cibaWithRAR = await auth0.loginBackchannel({
  bindingMessage: 'High-value transaction approval required',
  loginHint: { sub: 'auth0|123456789' },
  authorizationParams: {
    authorization_details: JSON.stringify([{
      type: 'payment_initiation',
      actions: ['transfer'],
      locations: ['https://bank.example.com'],
      amount: { value: '1000.00', currency: 'USD' },
      payee: { name: 'Merchant Corp', account: '12345' }
    }])
  }
}, storeOptions);

console.log('CIBA RAR response:', cibaWithRAR.authorizationDetails);

Express.js CIBA Implementation

import express from 'express';
import { ServerClient, StatefulStateStore, CookieTransactionStore } from '@auth0/auth0-server-js';

const app = express();
app.use(express.json());

const auth0 = new ServerClient<ExpressStoreOptions>({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  stateStore: new StatefulStateStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new ExpressCookieHandler()),
  transactionStore: new CookieTransactionStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new ExpressCookieHandler())
});

// CIBA login endpoint
app.post('/auth/ciba-login', async (req, res) => {
  const storeOptions = { request: req, response: res };
  const { userId, deviceName } = req.body;
  
  try {
    const cibaResult = await auth0.loginBackchannel({
      bindingMessage: `Login request from ${deviceName}`,
      loginHint: { sub: userId }
    }, storeOptions);
    
    res.json({ 
      success: true, 
      message: 'Push notification sent to your device',
      authorizationDetails: cibaResult.authorizationDetails 
    });
  } catch (error) {
    res.status(400).json({ error: 'CIBA authentication failed' });
  }
});

// CIBA status polling endpoint
app.get('/auth/ciba-status', async (req, res) => {
  const storeOptions = { request: req, response: res };
  const user = await auth0.getUser(storeOptions);
  
  res.json({ 
    authenticated: !!user,
    user: user || null 
  });
});

3. CIBA Security Features

The existing implementation provides these CIBA features through 6 :

• Automatic Polling: Polls token endpoint until user approves/denies
• Binding Messages: Human-readable transaction context 7
• Login Hints: Structured user identification 8
• RAR Support: Rich Authorization Requests for fine-grained permissions 9

4. Error Handling

CIBA operations use structured error handling through 10 :

// CIBA error handling example
try {
  const cibaResult = await auth0.loginBackchannel({
    bindingMessage: 'Login request',
    loginHint: { sub: userId }
  }, storeOptions);
} catch (error) {
  if (error.code === 'backchannel_authentication_error') {
    console.error('CIBA failed:', error.message, error.cause);
    // Handle specific CIBA errors
  }
}

Implementation Deliverables

1. Updated README sections with CIBA acronym branding
2. Complete working examples for Fastify, Express, and Next.js
3. Environment configuration guides for CIBA setup
4. Error handling documentation with specific CIBA error scenarios
5. RAR integration examples showing advanced CIBA use cases

Success Criteria

1. Searchability: "CIBA" appears in documentation headers and examples
2. Code Examples: Complete, working CIBA implementations for major frameworks
3. Framework Integration: Examples show CIBA working with popular web frameworks
4. RAR Support: Advanced examples demonstrate Rich Authorization Requests with CIBA
5. Error Handling: Clear documentation of CIBA-specific error scenarios

Notes

The existing CIBA implementation in 1 and 2 is fully functional but needs better discoverability through CIBA acronym usage. The server-side implementation automatically handles session management after successful CIBA authentication, making it ideal for web applications requiring push notification-based login flows.

[arpit-jn]

Thank you @btiernay for this detailed specification on enhancing our CIBA docs and examples.

To ensure this gets the broader visibility it deserves, both for internal review and community feedback, I'm moving this to GitHub Discussions. That's the perfect forum for us to collaborate on refining this plan before breaking it down into actionable issues.

Looking forward to continuing the conversation there.