@webex/plugin-authorization-node 3.8.1 → 3.9.0

package/NODE-OAUTH-FLOW-GUIDE.md

@@ -0,0 +1,257 @@
+# Webex Node.js OAuth Authorization Flow - Technical Guide
+
+This document explains how the Webex SDK handles OAuth authorization in Node.js environments, covering server-side authentication flows and token management.
+
+## Table of Contents
+
+[Node.js Webex Initialization](#1-nodejs-webex-initialization)
+[Node.js OAuth Flow Types](#2-nodejs-oauth-flow-types)
+[Authorization Code Exchange](#3-authorization-code-exchange)  
+[Server-Side Token Management](#4-server-side-token-management)  
+[Node.js Refresh Token Management](#5-nodejs-refresh-token-management)  
+[Node.js Ready and Authorization Events](#6-nodejs-ready-and-authorization-events)
+
+---
+
+## 1. Node.js Webex Initialization
+
+### 1.1 Basic Node.js Setup
+
+Node.js applications initialize the Webex SDK with server-side OAuth parameters:
+
+- **client_id**: Your registered application ID
+- **client_secret**: Your application's client secret (required for server-side)
+- **scope**: Requested permissions (e.g., 'spark:all spark:kms')
+- **clientType**: 'confidential' (default for Node.js)
+
+**Reference**: See `packages/@webex/plugin-authorization-node/README.md` for Node.js specific configuration
+
+### 1.2 Node.js Environment Detection
+
+The SDK automatically loads the Node.js authorization plugin:
+
+- **Environment**: Detects Node.js runtime automatically
+- **Plugin**: Loads `@webex/plugin-authorization-node`
+- **Flow Type**: Defaults to Authorization Code Grant (confidential client)
+
+**Reference**: Main authorization plugin in `packages/@webex/plugin-authorization/README.md`
+
+### 1.3 Node.js vs Browser Differences
+
+#### Node.js Environment Benefits
+
+- **Security**: Client secret can be safely stored server-side
+- **Token Management**: Enhanced server-side token handling
+- **No URL Parsing**: No need to parse browser URLs for tokens
+- **Server-to-Server**: Direct API authentication without user interaction
+
+#### Node.js Limitations
+
+- **No Browser Redirects**: Cannot redirect users to OAuth pages
+- **Backend Only**: Requires separate frontend for user authentication flows
+- **Server Infrastructure**: Needs server environment to run
+
+---
+
+## 2. Node.js OAuth Flow Types
+
+### 2.1 Authorization Code Grant (Primary)
+
+Node.js primarily uses Authorization Code Grant:
+
+1. **Frontend initiates**: Browser redirects user to OAuth provider
+2. **User authenticates**: At Webex identity broker
+3. **Code received**: Authorization code sent to redirect URI
+4. **Backend exchange**: Node.js exchanges code for tokens using client secret
+
+### 2.2 JWT Authentication (Server-to-Server)
+
+Node.js JWT authentication for guest/bot scenarios:
+
+1. **Create JWT**: Server creates JWT with guest issuer credentials
+2. **Exchange for token**: JWT exchanged for Webex access token
+3. **API access**: Use access token for Webex API calls
+
+**Reference**: JWT methods in Node.js authorization plugin
+
+### 2.3 Client Credentials Flow
+
+For server-to-server authentication without user context:
+
+1. **Direct token request**: Using client_id and client_secret
+2. **No user involvement**: Pure server-to-server authentication
+3. **Limited scope**: Typically restricted to bot/integration scopes
+
+---
+
+## 3. Authorization Code Exchange
+
+### 3.1 Node.js Code Reception
+
+In Node.js environment, authorization code is received via:
+
+1. **Redirect URI endpoint**: Your server handles the OAuth callback
+2. **Code extraction**: Extract `code` parameter from query string
+3. **State validation**: Verify state parameter for CSRF protection
+4. **Error handling**: Check for OAuth error parameters
+
+### 3.2 Node.js Token Exchange Process
+
+Node.js performs secure token exchange:
+
+1. **POST request** to OAuth token endpoint
+2. **Parameters**:
+   - grant_type: "authorization_code"
+   - client_id: Your application ID
+   - client_secret: Your application secret
+   - code: Authorization code received
+   - redirect_uri: Must match registered URI
+
+### 3.3 Node.js Token Response
+
+Successful exchange returns:
+
+- **access_token**: For API authorization
+- **refresh_token**: For token renewal
+- **expires_in**: Token lifetime in seconds
+- **token_type**: Usually "Bearer"
+- **scope**: Granted permissions
+
+**Reference**: Token exchange implementation in Node.js authorization plugin
+
+---
+
+## 4. Server-Side Token Management
+
+### 4.1 Node.js Token Storage
+
+Node.js token storage considerations:
+
+1. **Secure storage**: Database, encrypted files, or secure key stores
+2. **User association**: Link tokens to specific user accounts
+3. **Session management**: Associate tokens with user sessions
+4. **Encryption**: Encrypt tokens at rest
+
+### 4.2 Node.js Supertoken Structure
+
+Node.js can create enhanced supertoken structures:
+
+- **Standard OAuth tokens**: access_token, refresh_token
+- **Metadata**: User information, scope details
+- **Expiration tracking**: Calculated expiry times
+- **Custom fields**: Application-specific data
+
+### 4.3 Node.js Token Validation
+
+Server-side token validation:
+
+1. **Expiry checking**: Validate token hasn't expired
+2. **Scope verification**: Ensure token has required permissions
+3. **Refresh triggers**: Automatic refresh when near expiry
+4. **Error handling**: Handle invalid or revoked tokens
+
+---
+
+## 5. Node.js Refresh Token Management
+
+### 5.1 Node.js Token Expiration Monitoring
+
+Node.js monitors token expiration through:
+
+- **Scheduled checks**: Periodic token validity verification
+- **API response monitoring**: Watch for 401 Unauthorized responses
+- **Proactive refresh**: Refresh before expiration
+- **Retry logic**: Automatic retry with refreshed tokens
+
+### 5.2 Node.js Refresh Process
+
+Server-side refresh token flow:
+
+1. **POST request** to token endpoint
+2. **Parameters**:
+   - grant_type: "refresh_token"
+   - refresh_token: Current refresh token
+   - client_id: Application identifier
+   - client_secret: Application secret
+
+### 5.3 Node.js Refresh Response Handling
+
+Handle refresh response:
+
+1. **Update stored tokens**: Replace old tokens with new ones
+2. **Update user sessions**: Refresh tokens in active sessions
+3. **Handle refresh failure**: Re-authenticate user if refresh fails
+4. **Concurrent requests**: Handle multiple simultaneous refresh attempts
+
+### 5.4 Node.js JWT Refresh
+
+For JWT-based authentication:
+
+1. **JWT expiration monitoring**: Track JWT token expiry
+2. **Automatic renewal**: Create new JWT when needed
+3. **Re-exchange process**: Exchange new JWT for fresh access token
+4. **Callback integration**: Use jwtRefreshCallback for automation
+
+**Reference**: JWT refresh implementation in Node.js authorization plugin
+
+---
+
+## 6. Node.js Ready and Authorization Events
+
+### 6.1 Node.js SDK Initialization
+
+Node.js SDK initialization phases:
+
+1. **Module loading**: Load required Node.js modules
+2. **Plugin initialization**: Initialize Node.js authorization plugin
+3. **Configuration validation**: Validate client credentials
+4. **Service discovery**: Load Webex service endpoints
+5. **Ready state**: SDK ready for API calls
+
+### 6.2 Node.js Authorization Events
+
+Node.js-specific events:
+
+- **ready**: SDK initialized and ready for requests
+- **unauthorized**: Token invalid or expired
+- **token:refresh**: Token has been refreshed
+- **auth:error**: Authentication error occurred
+
+### 6.3 Node.js Authentication Status
+
+Check Node.js authentication status:
+
+- `webex.canAuthorize`: Boolean for authenticated request capability
+- `webex.credentials.supertoken`: Current token information
+- `webex.ready`: Boolean for SDK initialization complete
+
+### 6.4 Node.js Error Handling
+
+Node.js specific error scenarios:
+
+1. **Invalid client credentials**: Wrong client_id or client_secret
+2. **Network failures**: Connection issues to Webex APIs
+3. **Token expiry**: Handle expired tokens gracefully
+4. **Rate limiting**: Handle API rate limit responses
+5. **Service unavailability**: Handle Webex service outages
+
+---
+
+## Node.js Code References
+
+- **Main Node.js Plugin**: `packages/@webex/plugin-authorization-node/`
+- **Node.js Plugin Docs**: `packages/@webex/plugin-authorization-node/README.md`
+- **WebexCore**: `packages/@webex/webex-core/src/webex-core.js`
+- **Common Authorization**: `packages/@webex/plugin-authorization/README.md`
+
+## Maintainers
+
+This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).
+
+## Contribute
+
+Pull requests welcome. Please see [CONTRIBUTING.md](https://github.com/webex/webex-js-sdk/blob/master/CONTRIBUTING.md) for more details.
+
+## License
+
+© 2016-2025 Cisco and/or its affiliates. All Rights Reserved.

package/README.md

@@ -1,14 +1,6 @@
 # @webex/plugin-authorization-node
 
-[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
-
-> Authorization plugin loaded when the Cisco Webex JS SDK is used in a non-browser environment.
-
-- [Install](#install)
-- [Usage](#usage)
-- [Contribute](#contribute)
-- [Maintainers](#maintainers)
-- [License](#license)
+This package provides authentication functionality for Node.js applications using the Webex SDK.
 
 ## Install
 
@@ -18,27 +10,81 @@ npm install --save @webex/plugin-authorization-node
 
 ## Usage
 
-This is a plugin for the Cisco Webex JS SDK . Please see our [developer portal](https://developer.webex.com/) and the [API docs](https://webex.github.io/webex-js-sdk/api/) for full details.
+This is a plugin for the Cisco Webex JS SDK. Please see our developer portal and the API docs for full details.
 
-## Install
+```js
+const Webex = require('webex');
 
-```bash
-npm install --save @webex/plugin-authorization-node
+const webex = Webex.init({
+  credentials: {
+    client_id: 'your-client-id',
+    client_secret: 'your-client-secret'
+  }
+});
+
+// Exchange authorization code for access token
+webex.authorization.requestAuthorizationCodeGrant({
+  code: 'authorization-code'
+}).then(() => {
+  console.log('Authentication successful');
+});
+
+// Use JWT for authentication
+webex.authorization.requestAccessTokenFromJwt({
+  jwt: 'your-jwt-token'
+}).then(() => {
+  console.log('JWT authentication successful');
+});
+
+// Create JWT token
+webex.authorization.createJwt({
+  issuer: 'guest-issuer-id',
+  secretId: 'base64-encoded-secret',
+  displayName: 'Guest User',
+  expiresIn: '12h'
+}).then(({jwt}) => {
+  console.log('JWT created:', jwt);
+});
 ```
 
-## Usage
+## Methods
 
-```js
+### requestAuthorizationCodeGrant(options)
 
-const Webex = require('webex');
+Exchanges an authorization code for an access token.
 
-const webex = Webex.init();
-webex.authorization-node.get(id)
-  .then((authorization-node) => {
-    console.log(authorization-node);
-  })
+- `options.code` - The authorization code received from the provider
 
-```
+### requestAccessTokenFromJwt(options)
+
+Requests access token using JWT.
+
+- `options.jwt` - JWT token for authentication
+
+### createJwt(options)
+
+Creates a JWT token.
+
+- `options.issuer` - Guest issuer ID
+- `options.secretId` - Base64 encoded secret
+- `options.displayName` - Display name (optional)
+- `options.expiresIn` - Token expiration time
+
+### logout(options)
+
+Logs out the current user.
+
+- `options.token` - Token to invalidate (optional)
+
+## Properties
+
+### isAuthorizing
+
+Boolean indicating if authorization is in progress.
+
+### isAuthenticating
+
+Alias for isAuthorizing.
 
 ## Maintainers
 
@@ -50,4 +96,4 @@ Pull requests welcome. Please see [CONTRIBUTING.md](https://github.com/webex/web
 
 ## License
 
-© 2016-2020 Cisco and/or its affiliates. All Rights Reserved.
+© 2016-2025 Cisco and/or its affiliates. All Rights Reserved.

package/dist/authorization.js

@@ -181,7 +181,7 @@ var Authorization = _webexCore.WebexPlugin.extend((_dec = (0, _common.whileInFli
       return _promise.default.reject(e);
     }
   },
-  version: "3.8.1"
+  version: "3.9.0"
 }, ((0, _applyDecoratedDescriptor2.default)(_obj, "requestAuthorizationCodeGrant", [_dec, _common.oneFlight], (0, _getOwnPropertyDescriptor.default)(_obj, "requestAuthorizationCodeGrant"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "requestAccessTokenFromJwt", [_common.oneFlight], (0, _getOwnPropertyDescriptor.default)(_obj, "requestAccessTokenFromJwt"), _obj)), _obj)));
 var _default = exports.default = Authorization;
 //# sourceMappingURL=authorization.js.map

package/package.json

@@ -25,19 +25,19 @@
     "@webex/eslint-config-legacy": "0.0.0",
     "@webex/jest-config-legacy": "0.0.0",
     "@webex/legacy-tools": "0.0.0",
-    "@webex/test-helper-appid": "3.8.1",
-    "@webex/test-helper-chai": "3.8.1",
-    "@webex/test-helper-mocha": "3.8.1",
-    "@webex/test-helper-mock-webex": "3.8.1",
-    "@webex/test-helper-test-users": "3.8.1",
+    "@webex/test-helper-appid": "3.9.0",
+    "@webex/test-helper-chai": "3.9.0",
+    "@webex/test-helper-mocha": "3.9.0",
+    "@webex/test-helper-mock-webex": "3.9.0",
+    "@webex/test-helper-test-users": "3.9.0",
     "eslint": "^8.24.0",
     "prettier": "^2.7.1",
     "sinon": "^9.2.4"
   },
   "dependencies": {
-    "@webex/common": "3.8.1",
-    "@webex/internal-plugin-device": "3.8.1",
-    "@webex/webex-core": "3.8.1",
+    "@webex/common": "3.9.0",
+    "@webex/internal-plugin-device": "3.9.0",
+    "@webex/webex-core": "3.9.0",
     "jsonwebtoken": "^9.0.0",
     "uuid": "^3.3.2"
   },
@@ -51,5 +51,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner jest"
   },
-  "version": "3.8.1"
+  "version": "3.9.0"
 }