keycloak-api-manager 6.0.1 → 6.0.2

package/docs/api/configuration.md

@@ -7,10 +7,7 @@ Core API methods for initializing and managing the Keycloak Admin Client connect
 - [configure()](#configure)
 - [setConfig()](#setconfig)
 - [getToken()](#gettoken)
-- [login()](#login)
-- [generateAuthorizationUrl()](#generateauthorizationurl)
-- [loginPKCE()](#loginpkce)
-- [auth()](#auth)
+- [Deprecated OIDC Methods](#deprecated-oidc-methods)
 - [stop()](#stop)
 
 ---
@@ -39,7 +36,7 @@ Authentication configuration object.
 | `username` | string | 📋 Conditional | Required for `password` grant type |
 | `password` | string | 📋 Conditional | Required for `password` grant type |
 | `clientSecret` | string | 📋 Conditional | Required for `client_credentials` grant type |
-| `tokenLifeSpan` | number | 📋 Optional | Token refresh interval in seconds (default: 60) |
+| `tokenLifeSpan` | number | 📋 Optional | Token lifespan hint in seconds used to schedule refresh (`tokenLifeSpan / 2`) |
 | `scope` | string | 📋 Optional | OAuth2 scope (e.g., `'offline_access'` for refresh tokens) |
 
 ### Returns
@@ -53,6 +50,7 @@ Authentication configuration object.
 ```javascript
 const KeycloakManager = require('keycloak-api-manager');
 
+// Bootstrap admin session once at startup.
 await KeycloakManager.configure({
   baseUrl: 'https://keycloak.example.com:8443',
   realmName: 'master',
@@ -63,6 +61,7 @@ await KeycloakManager.configure({
   tokenLifeSpan: 60
 });
 
+// All handler calls below reuse the authenticated admin context.
 console.log('Authenticated successfully');
 ```
 
@@ -96,7 +95,10 @@ await KeycloakManager.configure({
 
 ### Automatic Token Refresh
 
-When `tokenLifeSpan` is set, the client automatically refreshes the access token before expiration using an internal timer. The refresh happens at `tokenLifeSpan` seconds interval.
+The client automatically refreshes the access token using an internal timer.
+
+- If `tokenLifeSpan` is provided and valid, refresh runs at half that interval (`tokenLifeSpan / 2`).
+- If `tokenLifeSpan` is omitted/invalid, a safe fallback interval of 30 seconds is used.
 
 ### Error Handling
 
@@ -139,7 +141,8 @@ Configuration overrides object.
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
 | `realmName` | string | 📋 Optional | Switch to a different realm context |
-| `requestConfig` | object | 📋 Optional | Axios request configuration overrides |
+| `baseUrl` | string | 📋 Optional | Override Keycloak base URL for subsequent calls |
+| `requestConfig` | object | 📋 Optional | HTTP client request overrides forwarded to `@keycloak/keycloak-admin-client` internals (typically Axios). Supported keys depend on the installed admin client version |
 
 ### Returns
 
@@ -170,6 +173,7 @@ const users = await KeycloakManager.users.find({ max: 100 });
 #### Custom Request Configuration
 
 ```javascript
+// Runtime realm switch is immediate and affects subsequent API calls.
 KeycloakManager.setConfig({
   realmName: 'my-realm',
   requestConfig: {
@@ -185,6 +189,7 @@ KeycloakManager.setConfig({
 
 - `setConfig()` does NOT perform token/login calls. It only updates the runtime context.
 - Changing `realmName` affects all subsequent API calls until changed again.
+- Changing `baseUrl` updates the runtime target URL and is normalized (trailing slash removed).
 - The access token remains valid across realm switches (as long as the authenticated user/service account has permissions).
 
 ---
@@ -195,7 +200,7 @@ Retrieve the current access token. Useful for debugging or passing the token to
 
 **Syntax:**
 ```javascript
-const token = await KeycloakManager.getToken()
+const { accessToken, refreshToken } = KeycloakManager.getToken()
 ```
 
 ### Parameters
@@ -204,7 +209,7 @@ None
 
 ### Returns
 
-**Promise\<string\>** - The current access token (JWT)
+**{ accessToken: string, refreshToken: string }** - Current token pair managed by the client
 
 ### Examples
 
@@ -218,14 +223,15 @@ await KeycloakManager.configure({
   clientId: 'admin-cli'
 });
 
-const token = await KeycloakManager.getToken();
-console.log('Access Token:', token);
+// Reads token currently managed by the internal refresh loop.
+const { accessToken } = KeycloakManager.getToken();
+console.log('Access Token:', accessToken);
 
 // Use token with custom HTTP client
 const axios = require('axios');
 const response = await axios.get('https://keycloak.example.com/admin/realms/master', {
   headers: {
-    'Authorization': `Bearer ${token}`
+    'Authorization': `Bearer ${accessToken}`
   }
 });
 ```
@@ -233,382 +239,28 @@ const response = await axios.get('https://keycloak.example.com/admin/realms/mast
 ### Notes
 
 - The returned token is automatically refreshed by the internal timer (if `tokenLifeSpan` was configured).
-- Token format is JWT (JSON Web Token).
-
----
-
-## auth()
-
-⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.login()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
-
-This method will be removed in v7.0.0. For user authentication flows, use `keycloak-express-middleware` v6.1.0+.
-
-See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
-
----
-
-**Legacy Note:** Backward-compatible alias of `login()`. Use `login()` instead (also deprecated).
-
-**Syntax:**
-```javascript
-await KeycloakManager.auth(credentials)
-```
-
-### Returns
-
-**Promise\<Object\>** - Same response as `login()`
-
----
-
-## login()
-
-⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.login()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
-
-This method will be removed in v7.0.0. For user authentication flows, use `keycloak-express-middleware` v6.1.0+.
-
-See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
+- `accessToken` is JWT (JSON Web Token). `refreshToken` may be undefined depending on grant/scope.
 
 ---
 
-Request tokens from Keycloak via the OIDC token endpoint.
-
-This method is intended for application-level login/token flows (for users, service clients, or third-party integrations) using this package as a wrapper.
-
-It does **not** reconfigure or replace the internal admin session created by `configure()`.
-
-**Syntax:**
-```javascript
-await KeycloakManager.login(credentials)
-```
-
-### Parameters
-
-#### credentials (Object) ⚠️ Required
-
-Form parameters sent to `/protocol/openid-connect/token`.
-
-Common fields:
+## Deprecated OIDC Methods
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `grant_type` | string | ⚠️ Yes | OAuth2 grant type (`password`, `client_credentials`, `refresh_token`, `authorization_code`) |
-| `username` | string | 📋 Conditional | Required for `password` grant |
-| `password` | string | 📋 Conditional | Required for `password` grant |
-| `client_id` | string | 📋 Optional | If omitted, runtime `clientId` from `configure()` is used |
-| `client_secret` | string | 📋 Optional | If omitted, runtime `clientSecret` from `configure()` is used |
-| `refresh_token` | string | 📋 Conditional | Required for `refresh_token` grant |
-| `scope` | string | 📋 Optional | OAuth scopes (e.g. `openid profile email offline_access`) |
-| `code` | string | 📋 Conditional | Required for `authorization_code` grant |
-| `redirect_uri` | string | 📋 Conditional | Required for `authorization_code` grant |
+The following methods are still available only for backward compatibility and are deprecated since v6.0.0:
 
-### Returns
+- `auth(credentials)`
+- `login(credentials)`
+- `generateAuthorizationUrl(options)`
+- `loginPKCE(credentials)`
 
-**Promise\<Object\>** - Token payload returned by Keycloak (e.g. `access_token`, `refresh_token`, `expires_in`, `token_type`)
+These methods will be removed in v7.0.0.
 
-### Examples
+For all user authentication flows (including Authorization Code + PKCE), use keycloak-express-middleware:
 
-#### Resource Owner Password Login
+- https://github.com/smartenv-crs4/keycloak-express-middleware
 
-```javascript
-// Admin setup for wrapper/handlers
-await KeycloakManager.configure({
-  baseUrl: 'https://keycloak.example.com',
-  realmName: 'master',
-  username: 'admin',
-  password: 'admin',
-  grantType: 'password',
-  clientId: 'admin-cli'
-});
-
-// Application login/token request for an end-user
-const tokenResponse = await KeycloakManager.login({
-  grant_type: 'password',
-  username: 'end-user',
-  password: 'user-password',
-  scope: 'openid profile email'
-});
-
-console.log(tokenResponse.access_token);
-```
-
-#### Client Credentials Login
-
-```javascript
-const tokenResponse = await KeycloakManager.login({
-  grant_type: 'client_credentials',
-  client_id: 'my-public-api',
-  client_secret: process.env.API_CLIENT_SECRET
-});
-
-console.log(tokenResponse.access_token);
-```
-
-#### Refresh Token Flow
-
-```javascript
-const refreshed = await KeycloakManager.login({
-  grant_type: 'refresh_token',
-  refresh_token: oldRefreshToken
-});
-
-console.log(refreshed.access_token);
-```
-
-### Notes
-
-- `login()` posts to `${baseUrl}/realms/${realmName}/protocol/openid-connect/token`.
-- `login()` returns raw token endpoint payload and throws on non-2xx responses.
-- `login()`/`auth()` do not change handler wiring, runtime config, or the internal admin refresh timer.
-- Runtime `clientId`/`clientSecret` are appended automatically if configured and not overridden in request payload.
-
----
-
-## generateAuthorizationUrl()
-
-⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.generateAuthorizationUrl()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
-
-This method will be removed in v7.0.0. For PKCE authentication flows, use `keycloak-express-middleware` v6.1.0+.
-
-See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
-
----
-
-Generate OAuth2 Authorization Code + PKCE flow initialization. Returns a ready-to-use authorization URL and PKCE pair for server-side session storage.
-
-This helper simplifies the first step of PKCE login: generating the authorization URL with PKCE challenge and state parameter.
-
-**Syntax:**
-```javascript
-const pkceFlow = KeycloakManager.generateAuthorizationUrl(options)
-```
-
-### Parameters
-
-#### options (Object) ⚠️ Required
-
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `redirect_uri` | string | ⚠️ Yes* | Redirect URI where user returns after login |
-| `redirectUri` | string | ⚠️ Yes* | CamelCase alias of `redirect_uri` |
-| `scope` | string | 📋 Optional | Space-separated scopes (default: `'openid profile email'`) |
-| `state` | string | 📋 Optional | Custom state value (auto-generated if not provided) |
-
-`*` required with either snake_case or camelCase form.
-
-### Returns
-
-**Object** - PKCE flow initialization data:
-
-```javascript
-{
-  authUrl: 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth?...',
-  state: 'random_state_string',
-  codeVerifier: 'random_code_verifier_string'
-}
-```
-
-- `authUrl`: Ready-to-use authorization URL to redirect user to
-- `state`: CSRF token to validate in callback (store in session)
-- `codeVerifier`: PKCE proof to exchange for code in callback (store in session, **never expose to client**)
-
-### Example
-
-```javascript
-// Step 1: Generate authorization URL
-app.get('/auth/login', (req, res) => {
-  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
-    redirect_uri: `${process.env.APP_URL}/auth/callback`,
-    scope: 'openid profile email'
-  });
-  
-  // Store in session server-side
-  req.session.pkce_state = pkceFlow.state;
-  req.session.pkce_verifier = pkceFlow.codeVerifier;
-  
-  // Redirect user to Keycloak
-  res.redirect(pkceFlow.authUrl);
-});
-
-// Step 2: In callback, recover verifier and exchange code
-app.get('/auth/callback', async (req, res) => {
-  const { code, state } = req.query;
-  
-  // Validate state
-  if (state !== req.session.pkce_state) {
-    return res.status(400).send('CSRF attack detected');
-  }
-  
-  // Exchange code for token
-  const tokens = await KeycloakManager.loginPKCE({
-    code,
-    redirect_uri: `${process.env.APP_URL}/auth/callback`,
-    code_verifier: req.session.pkce_verifier
-  });
-  
-  // Use tokens...
-});
-```
-
-### Notes
-
-- `generateAuthorizationUrl()` does **not** call Keycloak; it generates URLs and PKCE values locally.
-- `state` and `codeVerifier` must be stored **server-side only** in session storage, never in cookies or local storage.
-- `codeVerifier` must be kept secret and never exposed to the browser.
-- `state` provides CSRF protection and must be validated in the callback.
-- Uses cryptographically secure random generation for `codeVerifier` and `state`.
-- Code challenge is SHA256-hashed (S256 method), not plain text.
-
----
-
-## loginPKCE()
-
-⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.loginPKCE()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
-
-This method will be removed in v7.0.0. For PKCE authentication flows, use `keycloak-express-middleware` v6.1.0+.
-
-See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
-
----
-
-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`.
-
-> **📖 For a complete step-by-step guide on implementing PKCE flow in your application, see [PKCE Login Flow Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)**
-
-**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
+Migration 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.
+- [OIDC Migration Plan](../../OIDC_MIGRATION_PLAN.md)
 
 ---
 
@@ -698,7 +350,7 @@ const KeycloakManager = require('keycloak-api-manager');
 
 async function keycloakWorkflow() {
   try {
-    // 1. Configure and authenticate
+    // 1) Configure and authenticate once.
     await KeycloakManager.configure({
       baseUrl: 'https://keycloak.example.com:8443',
       realmName: 'master',
@@ -710,27 +362,28 @@ async function keycloakWorkflow() {
     });
     console.log('✓ Authenticated');
     
-    // 2. Work in master realm
+    // 2) Run operations in the current realm context.
     const masterRealms = await KeycloakManager.realms.find();
     console.log(`✓ Found ${masterRealms.length} realms`);
     
-    // 3. Switch to application realm
+    // 3) Switch realm context for following API calls.
     KeycloakManager.setConfig({ realmName: 'my-app' });
     console.log('✓ Switched to my-app realm');
     
-    // 4. Perform operations
+    // 4) Execute admin operations in the target realm.
     const users = await KeycloakManager.users.find({ max: 100 });
     console.log(`✓ Found ${users.length} users in my-app`);
     
-    // 5. Get current token for debugging
-    const token = await KeycloakManager.getToken();
-    console.log('✓ Current token:', token.substring(0, 50) + '...');
+    // 5) Optionally inspect the token for debugging/integration checks.
+    const { accessToken } = KeycloakManager.getToken();
+    console.log('✓ Current token:', accessToken.substring(0, 50) + '...');
     
-    // 6. Cleanup
+    // 6) Always stop refresh timer before process exit.
     KeycloakManager.stop();
     console.log('✓ Stopped token refresh');
     
   } catch (error) {
+    // Ensure timer cleanup also happens on failures.
     console.error('✗ Error:', error.message);
     KeycloakManager.stop();
     process.exit(1);

package/docs/api-reference.md

@@ -4,8 +4,8 @@ Complete API documentation for keycloak-api-manager.
 
 ## Table of Contents
 
-### Guides (Practical Implementation)
-- [PKCE Login Flow Guide](guides/PKCE-Login-Flow.md) - Step-by-step OAuth2 Authorization Code + PKCE implementation guide
+### Guides
+- [OIDC Migration Plan](../OIDC_MIGRATION_PLAN.md) - Deprecation status and migration notes to keycloak-express-middleware
 
 ### Core API
 - [Configuration & Authentication](api/configuration.md) - Setup, authentication, and lifecycle management
@@ -78,11 +78,11 @@ KeycloakManager.stop();
 |-----------|-------------|--------|
 | `configure()` | Authentication and setup | Core |
 | `setConfig()` | Runtime configuration | Core |
-| `getToken()` | Get current access token | Core |
-| `login()` | Preferred OIDC token grant/login endpoint wrapper | Core |
-| `generateAuthorizationUrl()` | Generate PKCE authorization URL and verifier pair | Core |
-| `loginPKCE()` | Authorization Code + PKCE token exchange helper | Core |
-| `auth()` | Backward-compatible alias of `login()` | Core |
+| `getToken()` | Get current access/refresh token pair | Core |
+| `login()` | Deprecated OIDC token endpoint wrapper (moved to keycloak-express-middleware) | Core |
+| `generateAuthorizationUrl()` | Deprecated PKCE helper (moved to keycloak-express-middleware) | Core |
+| `loginPKCE()` | Deprecated PKCE token exchange helper (moved to keycloak-express-middleware) | Core |
+| `auth()` | Deprecated backward-compatible alias of `login()` | Core |
 | `stop()` | Stop token refresh timer | Core |
 | `realms` | Realm management | realmsHandler |
 | `users` | User management | usersHandler |