@webex/plugin-authorization 3.8.1 → 3.9.0-webinar5k.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/OAUTH-FLOW-GUIDE.md +121 -0
- package/README.md +120 -19
- package/package.json +7 -7
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# Webex OAuth Authorization Flow - Overview Guide
|
|
2
|
+
|
|
3
|
+
This document provides an overview of how the Webex SDK handles OAuth authorization across different environments. For detailed environment-specific information, see the dedicated guides below.
|
|
4
|
+
|
|
5
|
+
## Environment-Specific Guides
|
|
6
|
+
|
|
7
|
+
### Browser OAuth Flow
|
|
8
|
+
|
|
9
|
+
For browser-based applications using the Webex SDK in web environments:
|
|
10
|
+
|
|
11
|
+
**📖 [BROWSER-OAUTH-FLOW-GUIDE.md](../plugin-authorization-browser/BROWSER-OAUTH-FLOW-GUIDE.md)**
|
|
12
|
+
|
|
13
|
+
Covers:
|
|
14
|
+
|
|
15
|
+
- Browser initialization and setup
|
|
16
|
+
- Implicit Grant vs Authorization Code Grant flows
|
|
17
|
+
- Browser-specific CSRF protection
|
|
18
|
+
- URL parsing and token extraction
|
|
19
|
+
- Browser storage and events
|
|
20
|
+
|
|
21
|
+
### Node.js OAuth Flow
|
|
22
|
+
|
|
23
|
+
For server-side applications using the Webex SDK in Node.js environments:
|
|
24
|
+
|
|
25
|
+
**📖 [NODE-OAUTH-FLOW-GUIDE.md](../plugin-authorization-node/NODE-OAUTH-FLOW-GUIDE.md)**
|
|
26
|
+
|
|
27
|
+
Covers:
|
|
28
|
+
|
|
29
|
+
- Server-side initialization and configuration
|
|
30
|
+
- Authorization Code Grant flow
|
|
31
|
+
- JWT authentication for server-to-server
|
|
32
|
+
- Secure token storage and management
|
|
33
|
+
- Server-side token refresh handling
|
|
34
|
+
|
|
35
|
+
## Quick Environment Detection
|
|
36
|
+
|
|
37
|
+
The Webex SDK automatically detects your environment and loads the appropriate authorization plugin:
|
|
38
|
+
|
|
39
|
+
### Browser Environment
|
|
40
|
+
|
|
41
|
+
- **Detects**: `window` object presence
|
|
42
|
+
- **Loads**: `@webex/plugin-authorization-browser`
|
|
43
|
+
- **Features**: URL parsing, browser storage, popup/redirect handling
|
|
44
|
+
- **Flows**: Implicit Grant (default), Authorization Code Grant
|
|
45
|
+
|
|
46
|
+
### Node.js Environment
|
|
47
|
+
|
|
48
|
+
- **Detects**: Node.js runtime
|
|
49
|
+
- **Loads**: `@webex/plugin-authorization-node`
|
|
50
|
+
- **Features**: Server-side token exchange, secure credential storage
|
|
51
|
+
- **Flows**: Authorization Code Grant (primary), JWT authentication
|
|
52
|
+
|
|
53
|
+
## Common OAuth Flow Steps
|
|
54
|
+
|
|
55
|
+
Regardless of environment, the OAuth flow follows these general steps:
|
|
56
|
+
|
|
57
|
+
1. **Initialization**: Configure SDK with client credentials and scopes
|
|
58
|
+
2. **Authorization**: Redirect user to Webex identity broker for authentication
|
|
59
|
+
3. **Code/Token Reception**: Receive authorization code or access token
|
|
60
|
+
4. **Token Exchange**: Exchange code for tokens (Authorization Code Grant)
|
|
61
|
+
5. **Token Storage**: Store and manage tokens securely
|
|
62
|
+
6. **Token Refresh**: Automatically refresh expired tokens
|
|
63
|
+
7. **API Access**: Make authenticated requests to Webex APIs
|
|
64
|
+
|
|
65
|
+
## Flow Type Comparison
|
|
66
|
+
|
|
67
|
+
| Aspect | Implicit Grant | Authorization Code Grant |
|
|
68
|
+
| ------------------ | --------------------- | ---------------------------------- |
|
|
69
|
+
| **Client Type** | Public | Confidential |
|
|
70
|
+
| **Client Secret** | Not required | Required |
|
|
71
|
+
| **Security** | Less secure | More secure |
|
|
72
|
+
| **Token Location** | URL hash | Server exchange |
|
|
73
|
+
| **Best For** | SPAs, mobile apps | Server apps, web apps with backend |
|
|
74
|
+
| **Supertoken** | Basic token structure | Enhanced token with metadata |
|
|
75
|
+
|
|
76
|
+
## Key Differences by Environment
|
|
77
|
+
|
|
78
|
+
### Browser-Specific Features
|
|
79
|
+
|
|
80
|
+
- **URL hash parsing** for token extraction
|
|
81
|
+
- **sessionStorage** for CSRF token storage
|
|
82
|
+
- **Popup window** support for authentication
|
|
83
|
+
- **Browser storage adapters** for token persistence
|
|
84
|
+
- **CORS handling** for API requests
|
|
85
|
+
|
|
86
|
+
### Node.js-Specific Features
|
|
87
|
+
|
|
88
|
+
- **Client secret** handling for secure authentication
|
|
89
|
+
- **Server-side token exchange** for Authorization Code Grant
|
|
90
|
+
- **Database/file storage** for token persistence
|
|
91
|
+
- **JWT creation and exchange** for guest authentication
|
|
92
|
+
- **Server-to-server** authentication flows
|
|
93
|
+
|
|
94
|
+
## Getting Started
|
|
95
|
+
|
|
96
|
+
1. **Choose your environment guide** based on where you're running the Webex SDK
|
|
97
|
+
2. **Follow the initialization steps** for your specific environment
|
|
98
|
+
3. **Implement the OAuth flow** appropriate for your application type
|
|
99
|
+
4. **Handle token management** according to your security requirements
|
|
100
|
+
|
|
101
|
+
For detailed implementation examples and code references, see the environment-specific guides linked above.
|
|
102
|
+
|
|
103
|
+
## Code References
|
|
104
|
+
|
|
105
|
+
- **Main Authorization Plugin**: `packages/@webex/plugin-authorization/`
|
|
106
|
+
- **Browser Plugin**: `packages/@webex/plugin-authorization-browser/`
|
|
107
|
+
- **Node.js Plugin**: `packages/@webex/plugin-authorization-node/`
|
|
108
|
+
- **WebexCore**: `packages/@webex/webex-core/src/webex-core.js`
|
|
109
|
+
- **Browser Sample**: `docs/samples/browser-auth/app.js`
|
|
110
|
+
|
|
111
|
+
## Maintainers
|
|
112
|
+
|
|
113
|
+
This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).
|
|
114
|
+
|
|
115
|
+
## Contribute
|
|
116
|
+
|
|
117
|
+
Pull requests welcome. Please see [CONTRIBUTING.md](https://github.com/webex/webex-js-sdk/blob/master/CONTRIBUTING.md) for more details.
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
© 2016-2025 Cisco and/or its affiliates. All Rights Reserved.
|
package/README.md
CHANGED
|
@@ -1,14 +1,6 @@
|
|
|
1
1
|
# @webex/plugin-authorization
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
> Loads @webex/plugin-authorization-browser or @webex/plugin-authorization-node as appropriate.
|
|
6
|
-
|
|
7
|
-
- [Install](#install)
|
|
8
|
-
- [Usage](#usage)
|
|
9
|
-
- [Contribute](#contribute)
|
|
10
|
-
- [Maintainers](#maintainers)
|
|
11
|
-
- [License](#license)
|
|
3
|
+
This package automatically loads the appropriate environment-specific authorization plugin for the Webex SDK.
|
|
12
4
|
|
|
13
5
|
## Install
|
|
14
6
|
|
|
@@ -16,27 +8,136 @@
|
|
|
16
8
|
npm install --save @webex/plugin-authorization
|
|
17
9
|
```
|
|
18
10
|
|
|
19
|
-
##
|
|
11
|
+
## What it Does
|
|
20
12
|
|
|
21
|
-
|
|
13
|
+
The `@webex/plugin-authorization` package serves as a universal entry point that automatically selects and loads the correct authorization implementation based on your environment:
|
|
22
14
|
|
|
23
|
-
|
|
15
|
+
- **Browser environments**: Loads `@webex/plugin-authorization-browser` for client-side applications
|
|
16
|
+
- **Node.js environments**: Loads `@webex/plugin-authorization-node` for server-side applications
|
|
24
17
|
|
|
25
|
-
|
|
26
|
-
npm install --save @webex/plugin-authorization
|
|
27
|
-
```
|
|
18
|
+
This allows you to use a single import while getting the optimal authorization implementation for your runtime environment.
|
|
28
19
|
|
|
29
20
|
## Usage
|
|
30
21
|
|
|
22
|
+
This is a plugin for the Cisco Webex JS SDK. Please see our developer portal and the API docs for full details.
|
|
23
|
+
|
|
31
24
|
```js
|
|
32
25
|
const Webex = require('webex');
|
|
33
26
|
|
|
34
|
-
const webex = Webex.init(
|
|
35
|
-
|
|
36
|
-
|
|
27
|
+
const webex = Webex.init({
|
|
28
|
+
credentials: {
|
|
29
|
+
client_id: 'your-client-id',
|
|
30
|
+
client_secret: 'your-client-secret', // Only for Node.js environments
|
|
31
|
+
redirect_uri: 'https://your-app.com/callback' // Only for browser environments
|
|
32
|
+
}
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
// The authorization methods available depend on your environment:
|
|
36
|
+
|
|
37
|
+
// In Node.js environments:
|
|
38
|
+
webex.authorization.requestAuthorizationCodeGrant({
|
|
39
|
+
code: 'authorization-code'
|
|
37
40
|
});
|
|
41
|
+
|
|
42
|
+
webex.authorization.requestAccessTokenFromJwt({
|
|
43
|
+
jwt: 'your-jwt-token'
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
// In browser environments:
|
|
47
|
+
webex.authorization.initiateLogin();
|
|
48
|
+
webex.authorization.initiateImplicitGrant();
|
|
38
49
|
```
|
|
39
50
|
|
|
51
|
+
## Environment Detection
|
|
52
|
+
|
|
53
|
+
The package uses the following logic to determine which implementation to load:
|
|
54
|
+
|
|
55
|
+
1. **Browser environments**: When running in a browser context, it loads the browser-specific plugin with support for redirects, popups, and client-side flows
|
|
56
|
+
2. **Node.js environments**: When running in Node.js, it loads the server-specific plugin with support for server-to-server authentication flows
|
|
57
|
+
|
|
58
|
+
## Client Types and OAuth Flows
|
|
59
|
+
|
|
60
|
+
The Webex SDK supports different OAuth flows based on the `clientType` you configure. This determines how your application authenticates with Webex:
|
|
61
|
+
|
|
62
|
+
### `clientType: 'confidential'` (Authorization Code Grant)
|
|
63
|
+
|
|
64
|
+
- **Flow:** Authorization Code Grant
|
|
65
|
+
- **How:** User is redirected to Webex login, receives an authorization code, and your backend exchanges it for tokens.
|
|
66
|
+
- **Requires:** Client secret (must be kept secure, so only for server-side or backend apps)
|
|
67
|
+
- **Use Case:** Web applications with a backend, integrations, bots, or any app that can securely store a client secret.
|
|
68
|
+
- **SDK Behavior:** Calls `initiateAuthorizationCodeGrant()` and uses `response_type=code`.
|
|
69
|
+
|
|
70
|
+
### `clientType: 'public'` (Implicit Grant)
|
|
71
|
+
|
|
72
|
+
- **Flow:** Implicit Grant
|
|
73
|
+
- **How:** User is redirected to Webex login, and receives an access token directly in the browser.
|
|
74
|
+
- **Requires:** No client secret (safe for browser-only apps)
|
|
75
|
+
- **Use Case:** Single-page applications (SPAs), mobile apps, or any app that cannot securely store a client secret.
|
|
76
|
+
- **SDK Behavior:** Calls `initiateImplicitGrant()` and uses `response_type=token`.
|
|
77
|
+
|
|
78
|
+
### `client_credentials` (Client Credentials Grant)
|
|
79
|
+
|
|
80
|
+
- **Flow:** Client Credentials Grant
|
|
81
|
+
- **How:** Application authenticates as itself (no user context), directly exchanges client ID and secret for a token.
|
|
82
|
+
- **Requires:** Client secret (must be kept secure, so only for server-side or backend apps)
|
|
83
|
+
- **Use Case:** Server-to-server integrations, bots, or background services.
|
|
84
|
+
- **SDK Behavior:** Only available in Node.js SDK via `getClientToken()`.
|
|
85
|
+
|
|
86
|
+
> **Note:** Only `'confidential'` and `'public'` are meaningful for browser SDK. `client_credentials` is only supported in Node.js/server SDKs.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Available Methods
|
|
91
|
+
|
|
92
|
+
The methods available through this plugin depend on your runtime environment:
|
|
93
|
+
|
|
94
|
+
### Browser Environment Methods
|
|
95
|
+
|
|
96
|
+
- `initiateLogin(options)` - Start the login process. Automatically chooses the correct flow based on `clientType`:
|
|
97
|
+
- If `clientType: 'confidential'`, uses Authorization Code Grant (`initiateAuthorizationCodeGrant`)
|
|
98
|
+
- Otherwise, uses Implicit Grant (`initiateImplicitGrant`)
|
|
99
|
+
- `initiateImplicitGrant(options)` - Begin implicit grant flow (redirects with `response_type=token`)
|
|
100
|
+
- `initiateAuthorizationCodeGrant(options)` - Begin authorization code flow (redirects with `response_type=code`)
|
|
101
|
+
- `requestAccessTokenFromJwt({ jwt })` - Authenticate using JWT
|
|
102
|
+
- `createJwt(options)` - Create JWT tokens
|
|
103
|
+
- `logout(options)` - Log out the user
|
|
104
|
+
|
|
105
|
+
#### Difference between `initiateAuthorizationCodeGrant` and `initiateImplicitGrant`
|
|
106
|
+
|
|
107
|
+
| Method | OAuth Flow | response_type | Token Delivery | Requires Client Secret | Use Case |
|
|
108
|
+
| -------------------------------- | ------------------------ | ------------- | --------------------- | ---------------------- | ----------------------- |
|
|
109
|
+
| `initiateAuthorizationCodeGrant` | Authorization Code Grant | `code` | Code in URL, exchange | Yes | Backend web apps |
|
|
110
|
+
| `initiateImplicitGrant` | Implicit Grant | `token` | Token in URL hash | No | SPAs, browser-only apps |
|
|
111
|
+
|
|
112
|
+
- **Authorization Code Grant**: More secure, requires backend to exchange code for tokens.
|
|
113
|
+
- **Implicit Grant**: Less secure, tokens delivered directly to browser.
|
|
114
|
+
|
|
115
|
+
See [Browser OAuth Flow Guide](../plugin-authorization-browser/BROWSER-OAUTH-FLOW-GUIDE.md) for more details.
|
|
116
|
+
|
|
117
|
+
### Node.js Environment Methods
|
|
118
|
+
|
|
119
|
+
- `requestAuthorizationCodeGrant(options)` - Exchange authorization code for token
|
|
120
|
+
- `requestAccessTokenFromJwt({ jwt })` - Authenticate using JWT
|
|
121
|
+
- `getClientToken(options)` - Obtain a client token using client_credentials grant
|
|
122
|
+
- `createJwt(options)` - Create JWT tokens
|
|
123
|
+
- `logout(options)` - Log out the user
|
|
124
|
+
|
|
125
|
+
### Common Properties
|
|
126
|
+
|
|
127
|
+
- `isAuthorizing` - Boolean indicating if authorization is in progress
|
|
128
|
+
- `isAuthenticating` - Alias for isAuthorizing
|
|
129
|
+
|
|
130
|
+
## Related Packages
|
|
131
|
+
|
|
132
|
+
- `@webex/plugin-authorization-browser` - Browser-specific implementation
|
|
133
|
+
- `@webex/plugin-authorization-node` - Node.js-specific implementation
|
|
134
|
+
|
|
135
|
+
For detailed documentation on environment-specific features, please refer to the individual package documentation.
|
|
136
|
+
|
|
137
|
+
See [Node OAuth Flow Guide](../plugin-authorization-node/NODE-OAUTH-FLOW-GUIDE.md) for Node.js-specific flows.
|
|
138
|
+
|
|
139
|
+
See [Browser OAuth Flow Guide](../plugin-authorization-browser/BROWSER-OAUTH-FLOW-GUIDE.md) for browser-specific flows.
|
|
140
|
+
|
|
40
141
|
## Maintainers
|
|
41
142
|
|
|
42
143
|
This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).
|
|
@@ -47,4 +148,4 @@ Pull requests welcome. Please see [CONTRIBUTING.md](https://github.com/webex/web
|
|
|
47
148
|
|
|
48
149
|
## License
|
|
49
150
|
|
|
50
|
-
© 2016-
|
|
151
|
+
© 2016-2025 Cisco and/or its affiliates. All Rights Reserved.
|
package/package.json
CHANGED
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
]
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"@webex/plugin-authorization-browser": "3.
|
|
27
|
-
"@webex/plugin-authorization-node": "3.
|
|
26
|
+
"@webex/plugin-authorization-browser": "3.9.0-webinar5k.1",
|
|
27
|
+
"@webex/plugin-authorization-node": "3.9.0-webinar5k.1"
|
|
28
28
|
},
|
|
29
29
|
"scripts": {
|
|
30
30
|
"build": "yarn build:src",
|
|
@@ -40,12 +40,12 @@
|
|
|
40
40
|
"@webex/eslint-config-legacy": "0.0.0",
|
|
41
41
|
"@webex/jest-config-legacy": "0.0.0",
|
|
42
42
|
"@webex/legacy-tools": "0.0.0",
|
|
43
|
-
"@webex/test-helper-chai": "3.
|
|
44
|
-
"@webex/test-helper-mocha": "3.
|
|
45
|
-
"@webex/test-helper-mock-webex": "3.
|
|
46
|
-
"@webex/test-helper-test-users": "3.
|
|
43
|
+
"@webex/test-helper-chai": "3.9.0-webinar5k.1",
|
|
44
|
+
"@webex/test-helper-mocha": "3.9.0-webinar5k.1",
|
|
45
|
+
"@webex/test-helper-mock-webex": "3.9.0-webinar5k.1",
|
|
46
|
+
"@webex/test-helper-test-users": "3.9.0-webinar5k.1",
|
|
47
47
|
"eslint": "^8.24.0",
|
|
48
48
|
"prettier": "^2.7.1"
|
|
49
49
|
},
|
|
50
|
-
"version": "3.
|
|
50
|
+
"version": "3.9.0-webinar5k.1"
|
|
51
51
|
}
|