Implementing the Authorization Code OAuth Flow with PKCE for Genesys Cloud and NICE CXone SPAs

How-To-Articles
1

Implementing the Authorization Code OAuth Flow with PKCE for Genesys Cloud and NICE CXone SPAs

What You Will Build

  • A client-side JavaScript module that securely authenticates a user against a Genesys Cloud or NICE CXone environment using the Authorization Code flow with PKCE.
  • The implementation uses the standard OAuth 2.1 best practices for single-page applications (SPAs), eliminating the need for a backend server to handle the token exchange.
  • The code is written in vanilla JavaScript (ES6+) to ensure compatibility with any frontend framework, including React, Vue, or Angular.

Prerequisites

  • OAuth Client Type: Confidential or Public client registered in the Genesys Cloud Admin Portal or NICE CXone Developer Portal. For SPAs, a Public client with no client secret is recommended, but PKCE is mandatory in both cases.
  • Required Scopes: openid, profile, email (for user info), plus application-specific scopes such as conversation:call:view or user:read.
  • SDK/API Version: Genesys Cloud API v2. NICE CXone API v2.
  • Language/Runtime: Node.js 14+ or any modern browser environment supporting fetch and crypto APIs.
  • External Dependencies: None. This tutorial uses native browser APIs.

Authentication Setup

The Authorization Code flow with Proof Key for Code Exchange (PKCE) is the industry standard for securing public clients like SPAs. It prevents authorization code interception attacks by binding the authorization request to the token exchange request using a cryptographic verifier.

The process involves three distinct phases:

  1. Challenge Generation: The client generates a cryptographic code verifier and derives a code challenge.
  2. Authorization Request: The user is redirected to the provider’s login page with the code challenge.
  3. Token Exchange: The provider redirects back with an authorization code, which the client exchanges for an access token using the code verifier.

Generating the PKCE Parameters

Before redirecting the user, you must generate the code_verifier and code_challenge. The verifier is a high-entropy random string, and the challenge is the SHA-256 hash of that verifier, Base64URL encoded.

/**
 * Generates a random string of bytes and encodes it as a Base64URL string.
 * @param {number} length - The number of bytes to generate.
 * @returns {Promise<string>} The Base64URL encoded string.
 */
async function generateRandomString(length) {
  const array = new Uint8Array(length);
  window.crypto.getRandomValues(array);
  
  return Array.from(array, byte => byte.toString(16).padStart(2, '0'))
    .join('')
    .substring(0, length);
}

/**
 * Encodes a string to Base64URL format.
 * @param {string} input - The string to encode.
 * @returns {string} The Base64URL encoded string.
 */
function base64UrlEncode(input) {
  let str = '';
  const bytes = new TextEncoder().encode(input);
  
  // Create a view of the bytes
  const buffer = bytes.buffer;
  
  // Convert to Base64
  let binary = '';
  const len = bytes.byteLength;
  for (let i = 0; i < len; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  str = window.btoa(binary);
  
  // Convert to Base64URL
  return str.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

/**
 * Generates the PKCE code challenge from the code verifier.
 * @param {string} codeVerifier - The raw code verifier string.
 * @returns {Promise<string>} The SHA-256 hashed and Base64URL encoded challenge.
 */
async function generateCodeChallenge(codeVerifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(codeVerifier);
  
  // Hash the verifier with SHA-256
  const hashBuffer = await window.crypto.subtle.digest('SHA-256', data);
  
  // Convert hash to Base64URL
  return base64UrlEncode(String.fromCharCode(...new Uint8Array(hashBuffer)));
}

Constructing the Authorization URL

You must construct the authorization URL using the provider’s specific endpoint. The redirect_uri must exactly match one of the URIs registered in your OAuth client configuration.

Genesys Cloud Endpoint: https://login.mypurecloud.com/as/authorization.oauth2
NICE CXone Endpoint: https://platformapi.niceincontact.com/oauth2/auth

/**
 * Constructs the authorization URL for the OAuth provider.
 * @param {Object} config - Configuration object containing client_id, redirect_uri, and scopes.
 * @param {string} codeChallenge - The PKCE code challenge.
 * @param {string} state - A random state string for CSRF protection.
 * @param {string} provider - 'genesys' or 'cxone'.
 * @returns {string} The full authorization URL.
 */
function buildAuthorizationUrl(config, codeChallenge, state, provider) {
  let baseUrl;
  
  if (provider === 'genesys') {
    baseUrl = 'https://login.mypurecloud.com/as/authorization.oauth2';
  } else if (provider === 'cxone') {
    baseUrl = 'https://platformapi.niceincontact.com/oauth2/auth';
  } else {
    throw new Error('Unsupported provider');
  }

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: config.clientId,
    redirect_uri: config.redirectUri,
    scope: config.scopes.join(' '),
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state: state
  });

  return `${baseUrl}?${params.toString()}`;
}

Implementation

Step 1: Initiating the Login Flow

When the user clicks “Login,” your application must generate the PKCE parameters, store the verifier and state in a secure location (such as sessionStorage), and redirect the browser.

const OAUTH_CONFIG = {
  genesys: {
    clientId: 'YOUR_GENESYS_CLIENT_ID',
    redirectUri: 'http://localhost:3000/callback',
    scopes: ['openid', 'profile', 'conversation:call:view']
  },
  cxone: {
    clientId: 'YOUR_CXONE_CLIENT_ID',
    redirectUri: 'http://localhost:3000/callback',
    scopes: ['openid', 'profile', 'conversation:call:view']
  }
};

async function initiateLogin(provider) {
  const config = OAUTH_CONFIG[provider];
  
  // 1. Generate State for CSRF protection
  const state = generateRandomString(32);
  
  // 2. Generate PKCE Verifier (43-128 characters of unreserved characters)
  const codeVerifier = generateRandomString(64);
  
  // 3. Generate PKCE Challenge
  const codeChallenge = await generateCodeChallenge(codeVerifier);
  
  // 4. Store Verifier and State securely
  // In production, consider using httpOnly cookies if feasible, 
  // but sessionStorage is standard for SPA-only PKCE.
  sessionStorage.setItem('pkce_verifier', codeVerifier);
  sessionStorage.setItem('oauth_state', state);
  
  // 5. Redirect to Authorization Server
  const authUrl = buildAuthorizationUrl(config, codeChallenge, state, provider);
  window.location.href = authUrl;
}

Step 2: Handling the Callback and Exchanging the Code

After the user authenticates, the provider redirects to your redirect_uri with an authorization code and the state. You must validate the state, then exchange the code for tokens.

Important: This step happens entirely in the browser. You do not send the code_verifier to a backend server; you send it directly to the OAuth token endpoint.

Genesys Cloud Token Endpoint: https://login.mypurecloud.com/as/token.oauth2
NICE CXone Token Endpoint: https://platformapi.niceincontact.com/oauth2/token

/**
 * Exchanges the authorization code for an access token.
 * @param {string} code - The authorization code from the URL query params.
 * @param {string} provider - 'genesys' or 'cxone'.
 */
async function exchangeCodeForToken(code, provider) {
  const config = OAUTH_CONFIG[provider];
  const codeVerifier = sessionStorage.getItem('pkce_verifier');
  const storedState = sessionStorage.getItem('oauth_state');
  
  // Retrieve state from URL to validate against stored state
  const urlParams = new URLSearchParams(window.location.search);
  const returnedState = urlParams.get('state');
  
  // Security Check: Ensure state matches
  if (returnedState !== storedState) {
    throw new Error('State mismatch. Potential CSRF attack.');
  }
  
  // Determine Token Endpoint
  let tokenUrl;
  if (provider === 'genesys') {
    tokenUrl = 'https://login.mypurecloud.com/as/token.oauth2';
  } else if (provider === 'cxone') {
    tokenUrl = 'https://platformapi.niceincontact.com/oauth2/token';
  }
  
  // Prepare Request Body
  const requestBody = new URLSearchParams({
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: config.redirectUri,
    client_id: config.clientId,
    code_verifier: codeVerifier
  });
  
  try {
    const response = await fetch(tokenUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        // Note: No Authorization header with Basic Auth is needed for public clients with PKCE
      },
      body: requestBody
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Token exchange failed: ${errorData.error_description || response.statusText}`);
    }
    
    const tokens = await response.json();
    
    // Clear sensitive data from sessionStorage
    sessionStorage.removeItem('pkce_verifier');
    sessionStorage.removeItem('oauth_state');
    
    // Store tokens securely
    localStorage.setItem('access_token', tokens.access_token);
    localStorage.setItem('refresh_token', tokens.refresh_token);
    localStorage.setItem('token_expiry', Date.now() + (tokens.expires_in * 1000));
    
    console.log('Authentication successful:', tokens);
    
    // Redirect to dashboard or home page
    window.location.href = '/dashboard';
    
  } catch (error) {
    console.error('Error exchanging code:', error);
    window.location.href = '/error?message=' + encodeURIComponent(error.message);
  }
}

// Entry point for callback handling
function handleCallback(provider) {
  const urlParams = new URLSearchParams(window.location.search);
  const code = urlParams.get('code');
  const error = urlParams.get('error');
  
  if (error) {
    console.error('Auth Error:', error);
    window.location.href = '/error?message=' + encodeURIComponent(error);
    return;
  }
  
  if (code) {
    exchangeCodeForToken(code, provider);
  }
}

Step 3: Using the Access Token with the SDK

Once you have the access token, you can use the official SDKs. The SDKs handle the caching and refreshing of tokens if you provide the initial token.

Genesys Cloud SDK (JavaScript):

import PlatformClient from 'genesys-cloud-purecloud-platform-client';

// Initialize the SDK with the access token
const platformClient = PlatformClient.create({
  basePath: 'https://api.mypurecloud.com',
  accessToken: localStorage.getItem('access_token')
});

// Optional: Configure automatic token refresh
// The SDK can handle refresh tokens if provided during initialization or via a callback
platformClient.setRefreshToken(localStorage.getItem('refresh_token'));

async function fetchUserDetails() {
  try {
    // This call requires the 'user:read' scope
    const response = await platformClient.UsersApi.getUserMe();
    console.log('Logged in as:', response.body.name);
    return response.body;
  } catch (error) {
    if (error.status === 401) {
      console.error('Token expired. Re-authentication required.');
      // Trigger re-login flow
      initiateLogin('genesys');
    } else {
      throw error;
    }
  }
}

NICE CXone SDK (JavaScript):

import { ApiClient, Configuration } from '@nice-dx/cxone-sdk';

// Initialize the SDK
const config = new Configuration({
  basePath: 'https://platformapi.niceincontact.com',
  accessToken: localStorage.getItem('access_token')
});

const apiClient = new ApiClient(config);

async function fetchCXoneUser() {
  try {
    // CXone uses a different method pattern
    const response = await apiClient.authApi.getMe();
    console.log('Logged in as:', response.data.name);
    return response.data;
  } catch (error) {
    if (error.response && error.response.status === 401) {
      console.error('Token expired. Re-authentication required.');
      initiateLogin('cxone');
    } else {
      throw error;
    }
  }
}

Complete Working Example

This is a complete, single-file HTML/JS module that demonstrates the full flow for Genesys Cloud. It can be saved as index.html and opened in a browser (preferably via a local server to avoid CORS issues with fetch, although the token endpoint typically allows cross-origin requests).

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>OAuth2 PKCE Demo</title>
    <style>
        body { font-family: sans-serif; padding: 20px; }
        button { padding: 10px 20px; cursor: pointer; }
        #status { margin-top: 20px; color: green; }
        #error { margin-top: 20px; color: red; }
    </style>
</head>
<body>
    <h1>Genesys Cloud OAuth2 PKCE Login</h1>
    <div id="login-view">
        <button id="login-btn">Login with Genesys Cloud</button>
    </div>
    <div id="dashboard-view" style="display:none;">
        <h2>Welcome, <span id="user-name"></span></h2>
        <button id="logout-btn">Logout</button>
        <pre id="token-display"></pre>
    </div>
    <div id="status"></div>
    <div id="error"></div>

    <script type="module">
        // Configuration
        const CONFIG = {
            clientId: 'YOUR_CLIENT_ID_HERE', // Replace with your Client ID
            redirectUri: window.location.origin + window.location.pathname, // Must match registered URI
            scopes: ['openid', 'profile', 'user:read'],
            provider: 'genesys'
        };

        // PKCE Utilities
        async function generateRandomString(length) {
            const array = new Uint8Array(length);
            window.crypto.getRandomValues(array);
            return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('').substring(0, length);
        }

        function base64UrlEncode(input) {
            let str = '';
            const bytes = new TextEncoder().encode(input);
            let binary = '';
            const len = bytes.byteLength;
            for (let i = 0; i < len; i++) {
                binary += String.fromCharCode(bytes[i]);
            }
            str = window.btoa(binary);
            return str.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
        }

        async function generateCodeChallenge(codeVerifier) {
            const encoder = new TextEncoder();
            const data = encoder.encode(codeVerifier);
            const hashBuffer = await window.crypto.subtle.digest('SHA-256', data);
            return base64UrlEncode(String.fromCharCode(...new Uint8Array(hashBuffer)));
        }

        // Login Flow
        async function login() {
            const state = await generateRandomString(32);
            const codeVerifier = await generateRandomString(64);
            const codeChallenge = await generateCodeChallenge(codeVerifier);

            sessionStorage.setItem('pkce_verifier', codeVerifier);
            sessionStorage.setItem('oauth_state', state);

            const baseUrl = 'https://login.mypurecloud.com/as/authorization.oauth2';
            const params = new URLSearchParams({
                response_type: 'code',
                client_id: CONFIG.clientId,
                redirect_uri: CONFIG.redirectUri,
                scope: CONFIG.scopes.join(' '),
                code_challenge: codeChallenge,
                code_challenge_method: 'S256',
                state: state
            });

            window.location.href = `${baseUrl}?${params.toString()}`;
        }

        // Token Exchange
        async function exchangeCode(code) {
            const codeVerifier = sessionStorage.getItem('pkce_verifier');
            const storedState = sessionStorage.getItem('oauth_state');
            const urlParams = new URLSearchParams(window.location.search);
            const returnedState = urlParams.get('state');

            if (returnedState !== storedState) {
                throw new Error('State mismatch');
            }

            const tokenUrl = 'https://login.mypurecloud.com/as/token.oauth2';
            const body = new URLSearchParams({
                grant_type: 'authorization_code',
                code: code,
                redirect_uri: CONFIG.redirectUri,
                client_id: CONFIG.clientId,
                code_verifier: codeVerifier
            });

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

            if (!response.ok) {
                const err = await response.json();
                throw new Error(err.error_description || 'Token exchange failed');
            }

            const data = await response.json();
            localStorage.setItem('access_token', data.access_token);
            localStorage.setItem('refresh_token', data.refresh_token);
            localStorage.setItem('token_expiry', Date.now() + (data.expires_in * 1000));
            
            sessionStorage.removeItem('pkce_verifier');
            sessionStorage.removeItem('oauth_state');
            
            return data;
        }

        // Fetch User Info
        async function getUserInfo() {
            const token = localStorage.getItem('access_token');
            if (!token) return null;

            const response = await fetch('https://api.mypurecloud.com/api/v2/users/me', {
                headers: { 'Authorization': `Bearer ${token}` }
            });

            if (response.status === 401) {
                localStorage.removeItem('access_token');
                localStorage.removeItem('refresh_token');
                return null;
            }

            return await response.json();
        }

        // UI Logic
        const loginBtn = document.getElementById('login-btn');
        const logoutBtn = document.getElementById('logout-btn');
        const loginView = document.getElementById('login-view');
        const dashboardView = document.getElementById('dashboard-view');
        const userNameSpan = document.getElementById('user-name');
        const tokenDisplay = document.getElementById('token-display');
        const errorDiv = document.getElementById('error');

        loginBtn.addEventListener('click', login);

        logoutBtn.addEventListener('click', () => {
            localStorage.removeItem('access_token');
            localStorage.removeItem('refresh_token');
            window.location.href = window.location.pathname;
        });

        // Check for callback or existing session
        async function init() {
            const urlParams = new URLSearchParams(window.location.search);
            const code = urlParams.get('code');
            const error = urlParams.get('error');

            if (error) {
                errorDiv.textContent = `Auth Error: ${error}`;
                return;
            }

            if (code) {
                try {
                    await exchangeCode(code);
                    // Reload to clear URL params and show dashboard
                    window.location.href = window.location.pathname;
                } catch (err) {
                    errorDiv.textContent = `Token Exchange Failed: ${err.message}`;
                }
                return;
            }

            // Check for existing valid token
            const user = await getUserInfo();
            if (user) {
                loginView.style.display = 'none';
                dashboardView.style.display = 'block';
                userNameSpan.textContent = user.name;
                tokenDisplay.textContent = JSON.stringify({ token: localStorage.getItem('access_token').substring(0, 20) + '...' }, null, 2);
            } else {
                loginView.style.display = 'block';
                dashboardView.style.display = 'none';
            }
        }

        init();
    </script>
</body>
</html>

Common Errors & Debugging

Error: invalid_grant or invalid_code_verifier

Cause: The code_verifier sent in the token request does not match the code_challenge sent in the authorization request. This usually happens if the hashing algorithm (SHA-256) or the Base64URL encoding implementation differs between the generation and exchange steps.

Fix: Ensure you are using the exact same codeVerifier string that was stored in sessionStorage and that the codeChallenge was derived from it using SHA-256. Verify your Base64URL encoding removes padding (=) and replaces + and / with - and _.

Error: invalid_client

Cause: The client_id is incorrect, or the redirect_uri in the token request does not exactly match the redirect_uri used in the authorization request.

Fix: Check your OAuth client configuration in the Genesys Cloud or CXone admin portal. Ensure the redirect URI is registered and matches character-for-character, including trailing slashes.

Error: 401 Unauthorized when calling API

Cause: The access token has expired. Access tokens typically expire in 30 minutes (Genesys) or 1 hour (CXone).

Fix: Implement a token refresh mechanism. Before making an API call, check if Date.now() > token_expiry. If so, use the refresh_token to obtain a new access token via the token endpoint with grant_type: 'refresh_token'.

Error: CORS Policy blocking token request

Cause: The browser blocks the fetch request to the token endpoint because the origin is not allowed.

Fix: Genesys Cloud and NICE CXone token endpoints are configured to allow CORS for standard OAuth flows. However, ensure you are not sending custom headers that trigger a preflight check unsupported by the provider. Stick to Content-Type: application/x-www-form-urlencoded.

Official References