Security Best Practices - Baanx API Documentation

Overview

Security is paramount when implementing OAuth 2.0. This guide covers essential security practices, common vulnerabilities, and how to protect your application and users from attacks.

Production Requirement: Review and implement ALL security practices in this guide before deploying to production.

OAuth 2.0 is fundamentally about user empowerment and consent. Security extends beyond protecting tokens—it includes respecting the authorization boundaries users establish.

User Agency First

Users grant your application permission to act on their behalf. This authorization is not blanket access—it’s permission to perform specific, expected actions.

Principle of Least Privilege

Only request and use the minimum permissions necessary. Just because you have a token doesn’t mean you should access all available user data.

Transparent Intent

Users should always understand what actions your application will perform on their behalf. Unexpected behavior erodes trust and violates consent.

Revocation Rights

Users must be able to revoke access at any time. Implement clear logout flows and honor token revocation immediately.

Critical Security Principle: Obtaining an access token grants you permission to act on behalf of the user—not permission to access or modify their data without their explicit understanding and consent for each type of action.

PKCE Implementation

PKCE (Proof Key for Code Exchange, pronounced “pixie”) is mandatory for all OAuth flows. It prevents authorization code interception attacks.

What is PKCE?

PKCE adds a cryptographic challenge to the OAuth flow:

Code Verifier: Random 43-128 character string
Code Challenge: SHA256 hash of the code verifier
Verification: Server validates verifier matches challenge

Implementation

import crypto from 'crypto';

function generateCodeVerifier(): string {
  // Generate 32 random bytes, base64url encode
  // Result: 43 characters (meets 43-128 requirement)
  return crypto
    .randomBytes(32)
    .toString('base64url');
}

function generateCodeChallenge(verifier: string): string {
  // Hash with SHA256, base64url encode
  return crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');
}

// Example usage
const codeVerifier = generateCodeVerifier();
const codeChallenge = generateCodeChallenge(codeVerifier);

console.log('Code Verifier:', codeVerifier);
console.log('Code Challenge:', codeChallenge);

// Store verifier securely for Step 4
sessionStorage.setItem('code_verifier', codeVerifier);

PKCE Requirements

Code Verifier

Length: 43-128 characters
Character set: [A-Z, a-z, 0-9, -, ., _, ~]
Cryptographically random
Single use only

Code Challenge

Algorithm: SHA256
Encoding: base64url (no padding)
Method: Must be S256
Derived from verifier

Common Mistake: Using plain text as code_challenge_method. Always use S256 (SHA256), never plain.

State Parameter (CSRF Protection)

The state parameter prevents Cross-Site Request Forgery (CSRF) attacks.

How It Works

Generate: Create random state before initiating OAuth
Send: Include in OAuth initiation request
Verify: Validate returned state matches original

import crypto from 'crypto';

function generateState(): string {
  // Generate cryptographically random state
  return crypto.randomBytes(16).toString('hex');
}

// Step 1: Generate and store state
const state = generateState();
sessionStorage.setItem('oauth_state', state);

// Include in OAuth initiation
const params = new URLSearchParams({
  state,
  // ... other params
});

// Step 3: Verify state on callback
function handleCallback(returnedState: string) {
  const originalState = sessionStorage.getItem('oauth_state');

  if (returnedState !== originalState) {
    throw new Error('State mismatch - possible CSRF attack');
  }

  // Clean up
  sessionStorage.removeItem('oauth_state');

  // Continue with token exchange
}

State Requirements:

Minimum 16 characters
Cryptographically random
Stored securely (session, not localStorage)
Validated exactly (case-sensitive)
Single use only

Secret Key Management

Your x-secret-key is highly sensitive and must be protected.

Do’s and Don’ts

✅ Do
❌ Don't

Store Secrets Securely

// Environment variables
const secretKey = process.env.SECRET_KEY;

// Server-side only
app.post('/api/oauth/initiate', async (req, res) => {
  const response = await fetch(oauthURL, {
    headers: {
      'x-secret-key': process.env.SECRET_KEY
    }
  });
});

// Use secret management services
// - AWS Secrets Manager
// - HashiCorp Vault
// - Azure Key Vault

Rotate Regularly

Rotate secrets every 90 days
Rotate immediately if compromised
Use different keys per environment

Never Expose Secrets

// ❌ NEVER in client-side code
const secretKey = 'sk_live_abc123...';

// ❌ NEVER in frontend JavaScript
fetch('/oauth/initiate', {
  headers: {
    'x-secret-key': 'sk_live_abc123...'
  }
});

// ❌ NEVER in version control
// .env file:
SECRET_KEY=sk_live_abc123...  // This will be committed!

// ❌ NEVER in public repositories
// ❌ NEVER in error messages
// ❌ NEVER in logs
// ❌ NEVER in URLs

Also Avoid

Hardcoding in source code
Storing in localStorage/cookies
Passing in URL parameters
Including in mobile app bundles
Logging to console or files

Secret Detection

Add pre-commit hooks to prevent accidental commits:

#!/bin/bash

# Check for potential secrets
if git diff --cached | grep -E '(x-secret-key|SECRET_KEY|sk_live_|sk_test_)'; then
    echo "Error: Potential secret detected in commit"
    echo "Please remove secrets before committing"
    exit 1
fi

Redirect URI Security

The redirect URI (or callback URL) is where users return after authentication, and it’s critical for OAuth security. Incorrect configuration can lead to authorization code theft.

What You’ll Learn: This section covers redirect URI requirements, HTTPS vs HTTP, custom schemes for mobile apps, CORS considerations, and validation techniques. For a high-level overview, see the OAuth Quick Start.

What is a Redirect URI?

A redirect URI serves as the callback endpoint where the authorization server returns the user along with the authorization code after successful authentication.

Allowed URI Schemes

HTTPS (Required for Production)
HTTP (Development Only)
Custom Schemes (Mobile)

Web applications in production environments MUST use HTTPS

✅ https://app.example.com/oauth/callback
✅ https://dashboard.example.com/auth/callback
✅ https://api.example.com/v1/oauth/redirect

Production Requirement: HTTP redirect URIs are rejected in production. HTTPS ensures authorization codes are encrypted during transmission, preventing interception attacks.

HTTPS Requirements:

Valid SSL/TLS certificate
TLS 1.2 or higher
Proper certificate chain configuration
No mixed content warnings

Only allowed in sandbox/development environments

⚠️  http://localhost:3000/oauth/callback
⚠️  http://127.0.0.1:8080/callback
⚠️  http://dev.example.test/oauth/callback

Development Use: HTTP URIs are permitted for local development and sandbox testing only. They will be rejected in production environments.

When to use HTTP:

Local development (localhost)
Testing OAuth flows
Sandbox environment testing
Before SSL certificate setup

Mobile applications should use app-specific custom URL schemes

✅ myapp://oauth/callback
✅ com.example.myapp://auth/callback

Contact Required: If you need to use a custom URL scheme, you must contact your Technical Account Manager to have your custom scheme whitelisted before implementation.

Custom Scheme Best Practices:

Use reverse domain notation (e.g., com.example.app://)
Make it unique to avoid conflicts with other apps
Keep it lowercase
Avoid special characters
Document in your app configuration

Platform Setup Examples:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Whitelist Configuration

Strict Matching Required

Redirect URIs must be exactly whitelisted in your environment configuration. No wildcards or partial matches allowed.

// ✅ Correct - exact match
redirect_uri: 'https://app.example.com/oauth/callback'

// ❌ Wrong - subdomain mismatch
redirect_uri: 'https://staging.example.com/oauth/callback'

// ❌ Wrong - path mismatch
redirect_uri: 'https://app.example.com/oauth/different-callback'

// ❌ Wrong - protocol mismatch
redirect_uri: 'http://app.example.com/oauth/callback'

// ❌ Wrong - trailing slash mismatch
redirect_uri: 'https://app.example.com/oauth/callback/'

All components must match exactly: protocol, domain, path, and port (if specified).

CORS and Redirect URIs

When your frontend application makes OAuth API calls, CORS (Cross-Origin Resource Sharing) settings must align with your redirect URI configuration.

Origin Relationship: The redirect URI domain should typically match the origin making OAuth API requests to prevent cross-origin issues.

Same-Origin (Recommended)
Cross-Origin

Best Practice: Frontend and redirect URI on the same domain

Frontend Origin:  https://app.example.com
Redirect URI:     https://app.example.com/oauth/callback

No CORS configuration needed - requests and callbacks use the same origin.

When frontend and redirect URI are different origins

Frontend Origin:  https://dashboard.example.com
Redirect URI:     https://auth.example.com/callback

CORS Setup Required: Contact your Technical Account Manager to configure CORS headers for your frontend origin and redirect URI domain.

Required CORS Configuration:

Allowed Origins: Both frontend and redirect URI domains
Allowed Methods: GET, POST for OAuth endpoints
Allowed Headers: Authorization, Content-Type, x-client-key, x-secret-key
Credentials: Set to true for cookie-based sessions

Security Requirements

Never Use Wildcards

❌ https://*.example.com/callback
❌ https://example.com/*
✅ https://app.example.com/callback

Wildcards create security vulnerabilities allowing malicious redirects.

Use HTTPS in Production

❌ http://app.example.com/callback
✅ https://app.example.com/callback

HTTP exposes authorization codes to man-in-the-middle attacks.

Validate on Client

const ALLOWED_URIS = [
  'https://app.example.com/oauth/callback'
];

function validateRedirectURI(uri: string): boolean {
  return ALLOWED_URIS.includes(uri);
}

Client-side validation prevents configuration errors before API calls.

Environment-Specific URIs

const redirectUri = {
  development: 'http://localhost:3000/callback',
  staging: 'https://staging.example.com/callback',
  production: 'https://app.example.com/callback'
}[process.env.NODE_ENV];

Use different URIs for each environment to maintain security.

Common Redirect URI Pitfalls

Trailing Slash Mismatch

Problem: Redirect URI with/without trailing slash doesn’t match whitelist

Whitelisted: https://app.example.com/callback
Sent:        https://app.example.com/callback/
Result:      ❌ Mismatch

Solution: Ensure exact match including trailing slash presence/absence.

Protocol Mismatch

Problem: HTTP used when HTTPS is whitelisted (or vice versa)

Whitelisted: https://app.example.com/callback
Sent:        http://app.example.com/callback
Result:      ❌ Mismatch

Solution: Match protocol exactly; always use HTTPS in production.

Port Number Issues

Problem: Explicit port in URI when whitelist doesn’t include it

Whitelisted: https://app.example.com/callback
Sent:        https://app.example.com:443/callback
Result:      ❌ Possible mismatch

Solution: Omit default ports (80 for HTTP, 443 for HTTPS) unless explicitly required.

Custom Scheme Not Whitelisted

Problem: Mobile app uses custom scheme without prior approval

Sent:   myapp://oauth/callback
Result: ❌ Not whitelisted

Solution: Contact Technical Account Manager to whitelist custom schemes before implementation.

CORS Policy Blocked

Problem: Browser blocks OAuth API request due to CORS policy

Error: Access to fetch at 'https://api.baanx.com/v1/authorize/initiate'
from origin 'https://myapp.example.com' has been blocked by CORS policy

Solution:

Verify your frontend origin is whitelisted for CORS
Check redirect URI matches whitelisted configuration
Contact Technical Account Manager to update CORS settings

Client-Side Validation Implementation

const ALLOWED_REDIRECT_URIS = [
  'https://app.example.com/oauth/callback'
];

function validateRedirectURI(uri: string): boolean {
  return ALLOWED_REDIRECT_URIS.includes(uri);
}

function initiateOAuth(redirectUri: string) {
  if (!validateRedirectURI(redirectUri)) {
    throw new Error('Redirect URI not whitelisted');
  }

  // Continue with OAuth
}

Configuration Checklist

Determine Redirect URI Scheme

Choose appropriate URI based on platform:

Web production: https://yourdomain.com/oauth/callback
Web development: http://localhost:3000/oauth/callback
Mobile app: yourapp://oauth/callback (requires technical account manager approval)

Request Whitelisting

Contact your Technical Account Manager with:

Redirect URI(s) for each environment
Custom URL schemes (if mobile - requires approval)
CORS origins (if different from redirect URI domain)

Implement Callback Handler

Create endpoint to receive authorization code:

Extract code and state query parameters
Validate state matches original value
Exchange code for tokens via /token endpoint

Test Complete Flow

Verify end-to-end:

Initiate OAuth with your redirect URI
Complete authentication
Callback receives authorization code
Code successfully exchanges for tokens

Token Storage Security

How you store tokens is critical for both protecting user data and maintaining the trust users place in your application when they grant authorization. Secure storage prevents unauthorized access to user accounts through stolen tokens.

Dual Responsibility: Token security protects both your application’s integrity and the user’s trust. A compromised token allows attackers to act as the user within the scope of granted permissions.

Storage Methods by Platform

Web Applications
Mobile Apps
Server-Side

Best: HTTP-Only Cookies

// Server-side: Set secure cookie
res.cookie('access_token', token, {
  httpOnly: true,      // Not accessible via JavaScript
  secure: true,        // HTTPS only
  sameSite: 'strict',  // CSRF protection
  maxAge: 6 * 60 * 60 * 1000  // 6 hours
});

Alternative: Memory Storage

// For SPAs, store in memory (not localStorage)
class TokenStore {
  private token: string | null = null;

  set(token: string) {
    this.token = token;
  }

  get(): string | null {
    return this.token;
  }

  clear() {
    this.token = null;
  }
}

⚠️ Avoid localStorage

// ❌ Vulnerable to XSS attacks
localStorage.setItem('access_token', token);

iOS: Keychain

import KeychainSwift

let keychain = KeychainSwift()
keychain.synchronizable = false  // Don't sync to iCloud

// Store
keychain.set(token, forKey: "access_token")

// Retrieve
let token = keychain.get("access_token")

// Delete
keychain.delete("access_token")

Android: EncryptedSharedPreferences

val masterKey = MasterKey.Builder(context)
    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
    .build()

val sharedPreferences = EncryptedSharedPreferences.create(
    context,
    "secure_prefs",
    masterKey,
    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)

// Store
sharedPreferences.edit()
    .putString("access_token", token)
    .apply()

// Retrieve
val token = sharedPreferences.getString("access_token", null)

React Native: SecureStore

import * as SecureStore from 'expo-secure-store';

// Store
await SecureStore.setItemAsync('access_token', token);

// Retrieve
const token = await SecureStore.getItemAsync('access_token');

// Delete
await SecureStore.deleteItemAsync('access_token');

Database with Encryption

import crypto from 'crypto';

const ENCRYPTION_KEY = process.env.TOKEN_ENCRYPTION_KEY;

function encryptToken(token: string): string {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);

  let encrypted = cipher.update(token, 'utf8', 'hex');
  encrypted += cipher.final('hex');

  const authTag = cipher.getAuthTag();

  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
}

function decryptToken(encryptedToken: string): string {
  const [ivHex, authTagHex, encrypted] = encryptedToken.split(':');

  const iv = Buffer.from(ivHex, 'hex');
  const authTag = Buffer.from(authTagHex, 'hex');
  const decipher = crypto.createDecipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);

  decipher.setAuthTag(authTag);

  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');

  return decrypted;
}

Session Storage

import session from 'express-session';
import RedisStore from 'connect-redis';
import { createClient } from 'redis';

const redisClient = createClient();

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true,
    httpOnly: true,
    maxAge: 6 * 60 * 60 * 1000
  }
}));

Common Vulnerabilities

Authorization Code Interception

Attack: Attacker intercepts authorization code during redirect.Prevention:

Use PKCE (mandatory)
Short authorization code lifetime (10 minutes)
HTTPS only in production
Validate redirect URI strictly

Example:

// ✅ Protected by PKCE
// Even if code is intercepted, attacker doesn't have code_verifier
const tokens = await exchangeCode({
  code: interceptedCode,
  code_verifier: storedVerifier  // Attacker doesn't have this
});

Cross-Site Request Forgery (CSRF)

Attack: Attacker tricks user into initiating OAuth with attacker’s code.Prevention:

Use state parameter (mandatory)
Validate state on callback
Cryptographically random state

Example:

// ✅ Protected by state validation
if (returnedState !== storedState) {
  throw new Error('CSRF attack detected');
}

Token Leakage via Logs

Attack: Tokens exposed in application or server logs.Prevention:

Never log tokens
Redact Authorization headers
Use log sanitization

Example:

// ✅ Sanitize logs
function sanitizeHeaders(headers: Headers) {
  const sanitized = { ...headers };
  if (sanitized.authorization) {
    sanitized.authorization = 'Bearer [REDACTED]';
  }
  return sanitized;
}

logger.info('API call', { headers: sanitizeHeaders(headers) });

XSS (Cross-Site Scripting)

Attack: Malicious script steals tokens from localStorage.Prevention:

Don’t store tokens in localStorage
Use HTTP-only cookies
Implement Content Security Policy
Sanitize user inputs

Example:

// ❌ Vulnerable
localStorage.setItem('token', accessToken);

// ✅ Secure
res.cookie('token', accessToken, { httpOnly: true });

Replay Attacks

Attack: Reuse intercepted authorization code or token.Prevention:

Authorization codes are single-use
Short token lifetimes
Implement token revocation
Use HTTPS

Server-side check:

def exchange_code(code: str):
    if redis.get(f'used_code:{code}'):
        raise Exception('Code already used')

    # Mark as used
    redis.setex(f'used_code:{code}', 600, '1')

    # Exchange for tokens

Phishing Attacks

Attack: Fake login page steals user credentials.Prevention (Hosted UI):

Use hosted UI for authentication
Educate users to verify URL
Implement domain verification

Prevention (API Mode):

Use certificate pinning
Implement biometric authentication
Add additional verification steps

Security Checklist

Pre-Production

PKCE Implementation

Code verifier is 43-128 characters
SHA256 used for code challenge
code_challenge_method is S256
Verifier stored securely
Verifier validated on exchange

State Parameter

State is cryptographically random
State is at least 16 characters
State stored in secure session
State validated on callback
State is single-use

Secret Management

Secrets in environment variables
Secrets never in client code
Secrets never in version control
Secrets not logged
Different keys per environment

Token Storage

Error Handling

Runtime Security

Monitoring

Security Headers

Implement these HTTP security headers:

import helmet from 'helmet';

app.use(helmet());

app.use((req, res, next) => {
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('X-XSS-Protection', '1; mode=block');
  res.setHeader('Content-Security-Policy', "default-src 'self'");
  res.setHeader('Referrer-Policy', 'no-referrer');
  next();
});

Incident Response

If you suspect a security breach:

Immediate Actions

Revoke all affected tokens immediately
Rotate compromised secrets
Force password reset for affected users
Disable compromised client keys

Investigation

Review access logs
Identify scope of breach
Document timeline
Preserve evidence

Notification

Notify affected users
Report to security team
Comply with regulations (GDPR, etc.)
Update security documentation

Prevention

Implement additional controls
Update security practices
Conduct security review
Train development team

Additional Resources

OAuth 2.0 Security BCP

Official OAuth 2.0 Security Best Current Practice

OWASP Top 10

Web application security risks

RFC 7636 (PKCE)

PKCE specification

RFC 6749 (OAuth 2.0)

OAuth 2.0 Authorization Framework

Next Steps

Hosted UI Flow

Implement OAuth with hosted authentication

API Mode Flow

Implement OAuth with custom UI

Token Management

Master token lifecycle

Troubleshooting

Common issues and solutions

Getting Started

OAuth 2.0 & Authentication

User Management

Wallet Management

Non-Custodial Wallet Delegation

Card Operations

​Overview

​User Consent and Authorization Principles

User Agency First

Principle of Least Privilege

Transparent Intent

Revocation Rights

​PKCE Implementation

​What is PKCE?

​Implementation

​PKCE Requirements

Code Verifier

Code Challenge

​State Parameter (CSRF Protection)

​How It Works

​Secret Key Management

​Do’s and Don’ts

​Secret Detection

​Redirect URI Security

​What is a Redirect URI?

​Allowed URI Schemes

​Whitelist Configuration

Strict Matching Required

​CORS and Redirect URIs

​Security Requirements

Never Use Wildcards

Use HTTPS in Production

Validate on Client

Environment-Specific URIs

​Common Redirect URI Pitfalls

​Client-Side Validation Implementation

​Configuration Checklist

​Token Storage Security

​Storage Methods by Platform

​Common Vulnerabilities

​Security Checklist

​Pre-Production

PKCE Implementation

State Parameter

Secret Management

Redirect URI

Token Storage

Error Handling

​Runtime Security

​Monitoring

​Security Headers

​Incident Response

​Additional Resources

OAuth 2.0 Security BCP

OWASP Top 10

RFC 7636 (PKCE)

RFC 6749 (OAuth 2.0)

​Next Steps

Hosted UI Flow

API Mode Flow

Token Management

Troubleshooting

Overview

User Consent and Authorization Principles

PKCE Implementation

What is PKCE?

Implementation

PKCE Requirements

State Parameter (CSRF Protection)

How It Works

Secret Key Management

Do’s and Don’ts

Secret Detection

Redirect URI Security

What is a Redirect URI?

Allowed URI Schemes

Whitelist Configuration

CORS and Redirect URIs

Security Requirements

Common Redirect URI Pitfalls

Client-Side Validation Implementation

Configuration Checklist

Token Storage Security

Storage Methods by Platform

Common Vulnerabilities

Security Checklist

Pre-Production

Runtime Security

Monitoring

Security Headers

Incident Response

Additional Resources

Next Steps