keycloak-api-manager 5.0.4 → 5.0.6

package/README.md

@@ -66,11 +66,14 @@ In Keycloak 26.x, management-permissions APIs used by group/user fine-grained te
 - `setConfig(overrides)`
 - `getToken()`
 - `login(credentials)`
+- `loginPKCE(credentials)`
 - `auth(credentials)`
 - `stop()`
 
 `login(credentials)` is the preferred OIDC token endpoint helper for login/token grant flows (user/client).
 
+`loginPKCE(credentials)` is a specialized helper for Authorization Code + PKCE token exchange.
+
 `auth(credentials)` is kept as backward-compatible alias and does not replace the internal admin session configured by `configure()`.
 
 Configured handler namespaces:

package/docs/api/configuration.md

@@ -8,6 +8,7 @@ Core API methods for initializing and managing the Keycloak Admin Client connect
 - [setConfig()](#setconfig)
 - [getToken()](#gettoken)
 - [login()](#login)
+- [loginPKCE()](#loginpkce)
 - [auth()](#auth)
 - [stop()](#stop)
 
@@ -347,6 +348,148 @@ console.log(refreshed.access_token);
 
 ---
 
+## loginPKCE()
+
+Perform Authorization Code + PKCE token exchange.
+
+This helper is intended for the callback step after user login on Keycloak, where your backend receives an authorization `code` and exchanges it with `code_verifier`.
+
+**Syntax:**
+```javascript
+await KeycloakManager.loginPKCE(credentials)
+```
+
+### Parameters
+
+#### credentials (Object) ⚠️ Required
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `code` | string | ⚠️ Yes | Authorization code returned by Keycloak |
+| `redirect_uri` | string | ⚠️ Yes* | Redirect URI used in authorize request |
+| `redirectUri` | string | ⚠️ Yes* | CamelCase alias of `redirect_uri` |
+| `code_verifier` | string | ⚠️ Yes* | PKCE code verifier |
+| `codeVerifier` | string | ⚠️ Yes* | CamelCase alias of `code_verifier` |
+| `client_id` | string | 📋 Optional | Overrides runtime `clientId` |
+| `clientId` | string | 📋 Optional | CamelCase alias of `client_id` |
+| `client_secret` | string | 📋 Optional | Overrides runtime `clientSecret` |
+| `clientSecret` | string | 📋 Optional | CamelCase alias of `client_secret` |
+| `scope` | string | 📋 Optional | Additional scope string |
+
+`*` required with either snake_case or camelCase form.
+
+### Returns
+
+**Promise\<Object\>** - Token payload returned by Keycloak (`access_token`, `refresh_token`, `id_token`, `expires_in`, ...)
+
+### Complete End-to-End Example (Express)
+
+```javascript
+const crypto = require('crypto');
+const express = require('express');
+const KeycloakManager = require('keycloak-api-manager');
+
+const app = express();
+
+const KEYCLOAK_BASE_URL = 'https://keycloak.example.com';
+const REALM = 'my-realm';
+const CLIENT_ID = 'my-confidential-client';
+const CLIENT_SECRET = process.env.KC_CLIENT_SECRET;
+const REDIRECT_URI = 'https://my-app.example.com/auth/callback';
+
+// Demo in-memory store. In production, use Redis/session storage.
+const pkceStore = new Map();
+
+function base64url(buffer) {
+  return buffer
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+function createPkcePair() {
+  const codeVerifier = base64url(crypto.randomBytes(32));
+  const codeChallenge = base64url(
+    crypto.createHash('sha256').update(codeVerifier).digest()
+  );
+  const state = base64url(crypto.randomBytes(16));
+  return { codeVerifier, codeChallenge, state };
+}
+
+async function bootstrap() {
+  // Configure runtime context so loginPKCE can reuse baseUrl/realm/client credentials
+  await KeycloakManager.configure({
+    baseUrl: KEYCLOAK_BASE_URL,
+    realmName: REALM,
+    grantType: 'client_credentials',
+    clientId: CLIENT_ID,
+    clientSecret: CLIENT_SECRET
+  });
+}
+
+// 1) Start login flow: generate PKCE and redirect to Keycloak /auth endpoint
+app.get('/auth/login', (req, res) => {
+  const { codeVerifier, codeChallenge, state } = createPkcePair();
+  pkceStore.set(state, codeVerifier);
+
+  const authorizeUrl =
+    `${KEYCLOAK_BASE_URL}/realms/${REALM}/protocol/openid-connect/auth` +
+    `?client_id=${encodeURIComponent(CLIENT_ID)}` +
+    `&response_type=code` +
+    `&scope=${encodeURIComponent('openid profile email')}` +
+    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
+    `&code_challenge=${encodeURIComponent(codeChallenge)}` +
+    `&code_challenge_method=S256` +
+    `&state=${encodeURIComponent(state)}`;
+
+  res.redirect(authorizeUrl);
+});
+
+// 2) Callback: receive code+state, recover verifier, exchange code for tokens
+app.get('/auth/callback', async (req, res) => {
+  const { code, state } = req.query;
+  const codeVerifier = pkceStore.get(state);
+  pkceStore.delete(state);
+
+  if (!code || !state || !codeVerifier) {
+    return res.status(400).json({ error: 'Invalid PKCE callback parameters' });
+  }
+
+  try {
+    const tokenResponse = await KeycloakManager.loginPKCE({
+      code,
+      redirectUri: REDIRECT_URI,
+      codeVerifier
+    });
+
+    // Usually you create your own app session/JWT here, instead of returning raw tokens
+    return res.json({
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_in: tokenResponse.expires_in
+    });
+  } catch (error) {
+    return res.status(401).json({ error: error.message });
+  }
+});
+
+bootstrap()
+  .then(() => app.listen(3000, () => console.log('Listening on :3000')))
+  .catch((error) => {
+    console.error('Startup error:', error.message);
+    process.exit(1);
+  });
+```
+
+### Notes
+
+- `loginPKCE()` forces `grant_type=authorization_code`.
+- If `client_id/client_secret` are omitted, runtime values from `configure()` are used.
+- `loginPKCE()` does not generate authorize URLs, `state`, or PKCE challenge; it only performs token exchange.
+
+---
+
 ## stop()
 
 Stop the automatic token refresh timer and cleanup resources. Call this when shutting down your application.

package/docs/api-reference.md

@@ -77,6 +77,7 @@ KeycloakManager.stop();
 | `setConfig()` | Runtime configuration | Core |
 | `getToken()` | Get current access token | Core |
 | `login()` | Preferred OIDC token grant/login endpoint wrapper | Core |
+| `loginPKCE()` | Authorization Code + PKCE token exchange helper | Core |
 | `auth()` | Backward-compatible alias of `login()` | Core |
 | `stop()` | Stop token refresh timer | Core |
 | `realms` | Realm management | realmsHandler |

package/index.js

@@ -148,10 +148,10 @@ async function requestOidcToken(credentials = {}) {
         }
     });
 
-    if (runtimeConfig.clientId) {
+    if (runtimeConfig.clientId && !body.has('client_id')) {
         body.append('client_id', runtimeConfig.clientId);
     }
-    if (runtimeConfig.clientSecret) {
+    if (runtimeConfig.clientSecret && !body.has('client_secret')) {
         body.append('client_secret', runtimeConfig.clientSecret);
     }
 
@@ -184,3 +184,44 @@ exports.auth = async function auth(credentials = {}) {
 exports.login = async function login(credentials = {}) {
     return requestOidcToken(credentials);
 };
+
+exports.loginPKCE = async function loginPKCE(credentials = {}) {
+    const {
+        code,
+        redirect_uri,
+        redirectUri,
+        code_verifier,
+        codeVerifier,
+        client_id,
+        clientId,
+        client_secret,
+        clientSecret,
+        ...rest
+    } = credentials;
+
+    const resolvedCode = code;
+    const resolvedRedirectUri = redirect_uri || redirectUri;
+    const resolvedCodeVerifier = code_verifier || codeVerifier;
+    const resolvedClientId = client_id || clientId;
+    const resolvedClientSecret = client_secret || clientSecret;
+
+    if (!resolvedCode) {
+        throw new Error('loginPKCE requires "code".');
+    }
+    if (!resolvedRedirectUri) {
+        throw new Error('loginPKCE requires "redirect_uri" (or "redirectUri").');
+    }
+    if (!resolvedCodeVerifier) {
+        throw new Error('loginPKCE requires "code_verifier" (or "codeVerifier").');
+    }
+
+    return requestOidcToken({
+        grant_type: 'authorization_code',
+        code: resolvedCode,
+        redirect_uri: resolvedRedirectUri,
+        code_verifier: resolvedCodeVerifier,
+        ...(resolvedClientId ? { client_id: resolvedClientId } : {}),
+        ...(resolvedClientSecret ? { client_secret: resolvedClientSecret } : {}),
+        ...rest
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-api-manager",
-  "version": "5.0.4",
+  "version": "5.0.6",
   "description": "Enhanced Node.js wrapper for Keycloak Admin REST API. Professional alternative to @keycloak/keycloak-admin-client with advanced features, bug fixes, automatic token refresh, Organizations API support, fine-grained permissions, and comprehensive resource management. Battle-tested with 113+ integration tests.",
   "main": "index.js",
   "scripts": {

package/test/specs/clientCredentials.test.js

@@ -76,4 +76,70 @@ describe('Authentication - client_credentials grant', function () {
     expect(token).to.have.property('accessToken');
     expect(token.accessToken).to.be.a('string').and.to.have.length.greaterThan(0);
   });
+
+  it('supports login() for direct token grant', async function () {
+    if (!testClientId || !testClientSecret) {
+      this.skip();
+      return;
+    }
+
+    keycloakManager.setConfig({ realmName: TEST_REALM });
+
+    const tokenPayload = await keycloakManager.login({
+      grant_type: 'client_credentials',
+      client_id: testClientId,
+      client_secret: testClientSecret,
+    });
+
+    expect(tokenPayload).to.have.property('access_token');
+    expect(tokenPayload.access_token).to.be.a('string').and.to.have.length.greaterThan(0);
+    expect(tokenPayload).to.have.property('token_type');
+  });
+
+  it('validates loginPKCE required parameters', async function () {
+    try {
+      await keycloakManager.loginPKCE({});
+      throw new Error('Expected loginPKCE to fail when code is missing');
+    } catch (error) {
+      expect(error.message).to.include('requires "code"');
+    }
+
+    try {
+      await keycloakManager.loginPKCE({ code: 'dummy-code' });
+      throw new Error('Expected loginPKCE to fail when redirect_uri is missing');
+    } catch (error) {
+      expect(error.message).to.include('requires "redirect_uri"');
+    }
+
+    try {
+      await keycloakManager.loginPKCE({
+        code: 'dummy-code',
+        redirect_uri: 'https://example.local/callback',
+      });
+      throw new Error('Expected loginPKCE to fail when code_verifier is missing');
+    } catch (error) {
+      expect(error.message).to.include('requires "code_verifier"');
+    }
+  });
+
+  it('attempts PKCE token exchange and returns OIDC error for invalid code', async function () {
+    if (!testClientId || !testClientSecret) {
+      this.skip();
+      return;
+    }
+
+    try {
+      await keycloakManager.loginPKCE({
+        code: 'invalid-authorization-code',
+        redirect_uri: 'https://example.local/callback',
+        code_verifier: 'plain-verifier-for-test-only',
+        client_id: testClientId,
+        client_secret: testClientSecret,
+      });
+      throw new Error('Expected loginPKCE to fail with invalid authorization code');
+    } catch (error) {
+      expect(error).to.be.instanceOf(Error);
+      expect(error.message).to.be.a('string').and.to.have.length.greaterThan(0);
+    }
+  });
 });