0
# Simple OAuth2
1

2
Simple OAuth2 provides a comprehensive Node.js client library for the OAuth 2.0 authorization framework, enabling developers to implement OAuth 2.0 authentication flows in their applications. It supports all three main OAuth 2.0 grant types with a clean, promise-based API and built-in token management capabilities.
3

4
## Package Information
5

6
- **Package Name**: simple-oauth2
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install simple-oauth2`
10

11
## Core Imports
12

13
```javascript
14
const { AuthorizationCode, ClientCredentials, ResourceOwnerPassword } = require('simple-oauth2');
15
```
16

17
For ES modules:
18
```javascript
19
import { AuthorizationCode, ClientCredentials, ResourceOwnerPassword } from 'simple-oauth2';
20
```
21

22
## Basic Usage
23

24
```javascript
25
const { AuthorizationCode } = require('simple-oauth2');
26

27
// Configure OAuth2 client
28
const client = new AuthorizationCode({
29
  client: {
30
    id: 'your-client-id',
31
    secret: 'your-client-secret'
32
  },
33
  auth: {
34
    tokenHost: 'https://oauth-provider.com'
35
  }
36
});
37

38
// Generate authorization URL
39
const authorizationUri = client.authorizeURL({
40
  redirectURI: 'http://localhost:3000/callback',
41
  scope: 'read write',
42
  state: 'random-state-string'
43
});
44

45
// Exchange authorization code for access token
46
const tokenParams = {
47
  code: 'authorization-code-from-callback',
48
  redirectURI: 'http://localhost:3000/callback'
49
};
50

51
const accessToken = await client.getToken(tokenParams);
52
```
53

54
## Architecture
55

56
Simple OAuth2 follows a modular architecture with three main grant type classes and a shared AccessToken management system:
57

58
- **Grant Type Classes**: Handle OAuth 2.0 flow-specific logic (AuthorizationCode, ClientCredentials, ResourceOwnerPassword)
59
- **AccessToken Class**: Provides token lifecycle management (expiration checking, refresh, revocation)
60
- **Configuration System**: Joi-based validation ensuring correct OAuth 2.0 compliance
61
- **HTTP Client**: Underlying request handling with configurable options
62

63
## Configuration
64

65
All grant type classes accept a configuration object with these sections:
66

67
```typescript { .api }
68
interface OAuth2Config {
69
  client: {
70
    id: string;
71
    secret: string;
72
    idParamName?: string;
73
    secretParamName?: string;
74
  };
75
  auth: {
76
    tokenHost: string;
77
    tokenPath?: string;
78
    refreshPath?: string;
79
    revokePath?: string;
80
    authorizeHost?: string;
81
    authorizePath?: string;
82
  };
83
  options?: {
84
    scopeSeparator?: string;
85
    credentialsEncodingMode?: 'strict' | 'loose';
86
    bodyFormat?: 'form' | 'json';
87
    authorizationMethod?: 'header' | 'body';
88
  };
89
  http?: {
90
    // Any options supported by @hapi/wreck except baseUrl
91
    [key: string]: any;
92
  };
93
}
94
```
95

96
## Capabilities
97

98
### Authorization Code Grant
99

100
For web applications requiring user authorization through browser redirects.
101

102
```typescript { .api }
103
class AuthorizationCode {
104
  constructor(options: OAuth2Config);
105
  authorizeURL(params: AuthorizeParams): string;
106
  getToken(params: TokenParams, httpOptions?: any): Promise<AccessToken>;
107
  createToken(token: any): AccessToken;
108
}
109

110
interface AuthorizeParams {
111
  redirectURI: string;
112
  scope?: string | string[];
113
  state?: string;
114
  [key: string]: any;
115
}
116

117
interface TokenParams {
118
  code: string;
119
  redirectURI: string;
120
  scope?: string | string[];
121
  [key: string]: any;
122
}
123
```
124

125
[Authorization Code Grant Details](./authorization-code.md)
126

127
### Client Credentials Grant
128

129
For service-to-service authentication without user involvement.
130

131
```typescript { .api }
132
class ClientCredentials {
133
  constructor(options: OAuth2Config);
134
  getToken(params?: ClientCredentialsParams, httpOptions?: any): Promise<AccessToken>;
135
  createToken(token: any): AccessToken;
136
}
137

138
interface ClientCredentialsParams {
139
  scope?: string | string[];
140
  [key: string]: any;
141
}
142
```
143

144
[Client Credentials Grant Details](./client-credentials.md)
145

146
### Resource Owner Password Grant
147

148
For trusted applications where users provide credentials directly (deprecated but supported).
149

150
```typescript { .api }
151
class ResourceOwnerPassword {
152
  constructor(options: OAuth2Config);
153
  getToken(params: PasswordParams, httpOptions?: any): Promise<AccessToken>;
154
  createToken(token: any): AccessToken;
155
}
156

157
interface PasswordParams {
158
  username: string;
159
  password: string;
160
  scope?: string | string[];
161
  [key: string]: any;
162
}
163
```
164

165
[Resource Owner Password Grant Details](./resource-owner-password.md)
166

167
### Access Token Management
168

169
Comprehensive token lifecycle management for all grant types.
170

171
```typescript { .api }
172
class AccessToken {
173
  readonly token: TokenObject;
174
  
175
  expired(expirationWindowSeconds?: number): boolean;
176
  refresh(params?: RefreshParams, httpOptions?: any): Promise<AccessToken>;
177
  revoke(tokenType: 'access_token' | 'refresh_token', httpOptions?: any): Promise<void>;
178
  revokeAll(httpOptions?: any): Promise<void>;
179
  toJSON(): TokenObject;
180
}
181

182
interface TokenObject {
183
  access_token: string;
184
  refresh_token?: string;
185
  expires_at?: Date;
186
  token_type?: string;
187
  scope?: string;
188
  [key: string]: any;
189
}
190

191
interface RefreshParams {
192
  scope?: string | string[];
193
  [key: string]: any;
194
}
195
```
196

197
[Access Token Management Details](./access-token.md)