Common Errors

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=invalid_request&
  error_description=Request%20parameter%20is%20required&
  state=xyz789

// ❌ This approach will ALWAYS fail with Oten IDP
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectURI}&response_type=code&scope=openid profile email&state=${state}`;
// Missing required 'request' parameter

// Oten IDP requires either:
// Option 1: request parameter (JWT-Secured Authorization Request)
// Option 2: request_uri parameter (URL pointing to JAR)
// You CANNOT provide both or neither

// ❌ Invalid - neither request nor request_uri
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectURI}`;

// ❌ Invalid - both request and request_uri
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&request=${jwt}&request_uri=${uri}`;

// ✅ Correct implementation with JAR
const jwt = require('jsonwebtoken');
const crypto = require('crypto');

function createJAR(authParams, clientSecret) {
  const now = Math.floor(Date.now() / 1000);

  const jarPayload = {
    // JWT Claims
    iss: authParams.client_id,
    aud: 'https://account.oten.com',
    iat: now,
    exp: now + 300, // 5 minutes
    jti: crypto.randomUUID(),

    // OAuth Parameters (ALL must be in JAR)
    client_id: authParams.client_id,
    redirect_uri: authParams.redirect_uri,
    response_type: 'code',
    scope: authParams.scope,
    state: authParams.state,
    code_challenge: authParams.code_challenge,
    code_challenge_method: 'S256'
  };

  return jwt.sign(jarPayload, clientSecret, { algorithm: 'HS256' });
}

// Usage
const authParams = {
  client_id: process.env.CLIENT_ID,
  redirect_uri: process.env.REDIRECT_URI,
  scope: 'openid profile email',
  state: generateState(),
  code_challenge: generateCodeChallenge(),
};

const requestJWT = createJAR(authParams, process.env.CLIENT_SECRET);
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${authParams.client_id}&request=${requestJWT}`;

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=invalid_request_object&
  error_description=Invalid%20Request%20Object%3A%20JWT%20signature%20verification%20failed&
  state=xyz789

// Check if your JAR is valid JWT format
const jwtParts = requestJWT.split('.');
if (jwtParts.length !== 3) {
  console.error('Invalid JWT format - must have 3 parts separated by dots');
}

// Decode and inspect (without verification)
const header = JSON.parse(atob(jwtParts[0]));
const payload = JSON.parse(atob(jwtParts[1]));

console.log('JWT Header:', header);
console.log('JWT Payload:', payload);

// ✅ Correct HS256 implementation
const jwt = require('jsonwebtoken');

function createJAR_HS256(jarPayload, clientSecret) {
  // Ensure algorithm is exactly 'HS256'
  return jwt.sign(jarPayload, clientSecret, {
    algorithm: 'HS256',
    // Don't include keyid for HS256
  });
}

// Common mistakes to avoid:
// ❌ Wrong algorithm
// jwt.sign(payload, secret, { algorithm: 'RS256' }); // Not supported
// ❌ Wrong secret format
// jwt.sign(payload, Buffer.from(secret, 'base64')); // Use string directly

// ✅ Correct EdDSA implementation
const fs = require('fs');

function createJAR_EdDSA(jarPayload, privateKeyPath, keyId) {
  const privateKey = fs.readFileSync(privateKeyPath, 'utf8');

  return jwt.sign(jarPayload, privateKey, {
    algorithm: 'EdDSA',
    keyid: keyId // Required for EdDSA
  });
}

// Verify your private key format
const privateKey = fs.readFileSync('private-key.pem', 'utf8');
if (!privateKey.includes('BEGIN PRIVATE KEY')) {
  console.error('Private key must be in PEM format');
}

// Note: JAR is only required for confidential clients
// Public clients should use PKCE with direct parameters instead

// Ensure all required claims are present
function validateJARPayload(payload) {
  const requiredClaims = ['iss', 'aud', 'iat', 'exp', 'jti'];
  const requiredOAuthParams = ['client_id', 'redirect_uri', 'response_type'];

  const missing = [...requiredClaims, ...requiredOAuthParams]
    .filter(claim => !payload[claim]);

  if (missing.length > 0) {
    throw new Error(`Missing required claims: ${missing.join(', ')}`);
  }

  // Validate timing
  const now = Math.floor(Date.now() / 1000);
  if (payload.exp <= now) {
    throw new Error('JAR token expired');
  }

  if (payload.iat > now + 60) {
    throw new Error('JAR issued in future');
  }
}

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=invalid_request&
  error_description=JAR%20token%20has%20expired&
  state=xyz789

// Decode JAR to check expiration
const jwtParts = requestJWT.split('.');
const payload = JSON.parse(atob(jwtParts[1]));

const now = Math.floor(Date.now() / 1000);
const expiresAt = payload.exp;
const issuedAt = payload.iat;

console.log('Current time:', now);
console.log('JAR issued at:', issuedAt);
console.log('JAR expires at:', expiresAt);
console.log('JAR age (seconds):', now - issuedAt);
console.log('Time until expiry (seconds):', expiresAt - now);

if (expiresAt <= now) {
  console.error('JAR has expired');
}

// ✅ Always generate JAR just before use
function createFreshJAR(authParams, clientSecret) {
  const now = Math.floor(Date.now() / 1000);

  const jarPayload = {
    // JWT Claims
    iss: authParams.client_id,
    aud: 'https://account.oten.com',
    iat: now,
    exp: now + 300, // 5 minutes from now
    jti: crypto.randomUUID(),

    // OAuth Parameters
    ...authParams
  };

  return jwt.sign(jarPayload, clientSecret, { algorithm: 'HS256' });
}

// Generate JAR immediately before redirect
const requestJWT = createFreshJAR(authParams, clientSecret);
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&request=${requestJWT}`;

// Redirect immediately
res.redirect(authURL);

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code: code not found"
}

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code: code not found"
}

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code: code already used"
}

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code: code expired"
}

{
  "error": "invalid_grant",
  "error_description": "Invalid code verifier"
}

// Verify you're using the code from callback
app.get('/callback', (req, res) => {
  const { code, state, error } = req.query;

  if (error) {
    return handleAuthError(error, req, res);
  }

  if (!code) {
    return res.status(400).send('Missing authorization code');
  }

  // Use code immediately - don't store it
  exchangeCodeForTokens(code, req.session.codeVerifier);
});

// Ensure code_verifier matches code_challenge
async function exchangeCodeForTokens(code, codeVerifier) {
  const tokenRequest = {
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: process.env.REDIRECT_URI,
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    code_verifier: codeVerifier // Must match original code_challenge
  };

  const response = await fetch('/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams(tokenRequest)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Token exchange failed: ${error.error_description}`);
  }

  return await response.json();
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

// Check your environment variables
console.log('Client ID:', process.env.CLIENT_ID);
console.log('Client Secret exists:', !!process.env.CLIENT_SECRET);
console.log('Client Secret length:', process.env.CLIENT_SECRET?.length);

// Verify against Oten registration
if (!process.env.CLIENT_ID || !process.env.CLIENT_SECRET) {
  throw new Error('Missing client credentials in environment variables');
}

// ✅ Correct client authentication (client_secret_post)
const tokenRequest = {
  grant_type: 'authorization_code',
  code: authorizationCode,
  redirect_uri: process.env.REDIRECT_URI,
  client_id: process.env.CLIENT_ID,
  client_secret: process.env.CLIENT_SECRET // Include in body
};

// ❌ Don't use Basic authentication
// const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
// headers: { 'Authorization': `Basic ${auth}` } // Not supported

// If using client_credentials grant and getting IP errors
if (grantType === 'client_credentials') {
  // Check your current IP
  const response = await fetch('https://api.ipify.org?format=json');
  const { ip } = await response.json();
  console.log('Current IP:', ip);

  // Verify IP is in Oten client whitelist
  // Contact Oten support to add IP to whitelist
}

// Example error response for IP not in whitelist:
// {
//   "error": "invalid_client",
//   "error_description": "Invalid client IP: 192.168.1.100 is not in whitelist"
// }

// ✅ Client credentials grant requires confidential client
if (grantType === 'client_credentials') {
  // Ensure your client is registered as "confidential" not "public"
  // Public clients cannot use client_credentials grant

  const tokenRequest = {
    grant_type: 'client_credentials',
    client_id: process.env.CLIENT_ID, // Must be confidential client
    client_secret: process.env.CLIENT_SECRET, // Required for confidential clients
    scope: 'read:data write:data'
  };
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "unauthorized_client",
  "error_description": "Public clients are not authorized for client credentials grant"
}

// Verify your client registration type
console.log('Client ID:', process.env.CLIENT_ID);
console.log('Grant type:', 'client_credentials');

// Check if you have a client secret (confidential clients only)
if (!process.env.CLIENT_SECRET) {
  console.error('Missing client secret - this indicates a public client');
  console.error('Public clients cannot use client_credentials grant');
}

// ✅ For public clients - use authorization_code with PKCE
if (clientType === 'public') {
  const tokenRequest = {
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: process.env.REDIRECT_URI,
    client_id: process.env.CLIENT_ID,
    code_verifier: codeVerifier // PKCE required for public clients
  };
}

// ✅ For confidential clients - can use client_credentials
if (clientType === 'confidential') {
  const tokenRequest = {
    grant_type: 'client_credentials',
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    scope: 'read:data'
  };
}

// If you need machine-to-machine authentication:
// 1. Register a new confidential client in Oten
// 2. Get client_id and client_secret
// 3. Configure IP whitelist if required
// 4. Use client_credentials grant

const confidentialClientConfig = {
  client_id: 'your_confidential_client_id',
  client_secret: 'your_confidential_client_secret',
  client_type: 'confidential',
  grant_types: ['client_credentials'],
  ip_whitelist: ['192.168.1.100', '10.0.0.50'] // Optional
};

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_client",
  "error_description": "Invalid client IP: 192.168.1.100 is not in whitelist"
}

// Check your current public IP
async function checkCurrentIP() {
  try {
    const response = await fetch('https://api.ipify.org?format=json');
    const { ip } = await response.json();
    console.log('Current public IP:', ip);
    return ip;
  } catch (error) {
    console.error('Failed to get IP:', error);
  }
}

// Check if IP is causing the issue
const currentIP = await checkCurrentIP();
console.log('If you see this IP in error message, it needs to be whitelisted:', currentIP);

// Contact Oten support to:
// 1. Check if IP whitelist is configured for your client
// 2. Add your IP address to the whitelist
// 3. Verify whitelist configuration

// Example whitelist configuration:
const clientConfig = {
  client_id: 'your_client_id',
  client_type: 'confidential',
  ip_whitelist: [
    '192.168.1.100',    // Your current IP
    '10.0.0.50',        // Server IP
    '203.0.113.0/24'    // IP range (if supported)
  ]
};

// After IP is added to whitelist, test the request
async function testClientCredentials() {
  const tokenRequest = {
    grant_type: 'client_credentials',
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    scope: 'read:data'
  };

  try {
    const response = await fetch('/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams(tokenRequest)
    });

    if (response.ok) {
      console.log('✅ IP whitelist validation passed');
      return await response.json();
    } else {
      const error = await response.json();
      console.error('❌ Still failing:', error);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
}

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=access_denied&
  error_description=The%20resource%20owner%20or%20authorization%20server%20denied%20the%20request&
  state=xyz789

app.get('/callback', (req, res) => {
  const { error, error_description, state } = req.query;

  if (error === 'access_denied') {
    // This is normal - user denied access
    return res.render('access-denied', {
      message: 'You chose not to grant access to this application.',
      action: 'You can try again if you change your mind.',
      loginUrl: '/login'
    });
  }

  // Handle other errors...
});

<!-- access-denied.html -->
<div class="error-message">
  <h2>Access Denied</h2>
  <p>You chose not to grant access to this application.</p>
  <p>If you change your mind, you can <a href="/login">try again</a>.</p>
</div>

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=server_error&
  error_description=The%20authorization%20server%20encountered%20an%20unexpected%20condition&
  state=xyz789

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "server_error",
  "error_description": "The authorization server encountered an unexpected condition that prevented it from fulfilling the request"
}

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      lastError = error;

      // Only retry for server errors
      if (error.message.includes('server_error') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }

  throw lastError;
}

// Usage for token exchange
const tokens = await makeRequestWithRetry(() =>
  exchangeCodeForTokens(code, codeVerifier)
);

# Check Oten service status
curl -I https://account.oten.com

# Check discovery endpoint
curl -s https://account.oten.com/.well-known/openid-configuration | jq .