0
# Passport OAuth
1

2
Passport OAuth provides OAuth 1.0 and OAuth 2.0 authentication strategies for Passport.js. This is a meta-module that combines passport-oauth1 and passport-oauth2 for backwards compatibility with the 0.1.x line of OAuth-based strategies.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const { OAuthStrategy, OAuth2Strategy, InternalOAuthError } = require('passport-oauth');
15
```
16

17
Individual imports:
18

19
```javascript
20
const OAuthStrategy = require('passport-oauth').OAuthStrategy;
21
const OAuth2Strategy = require('passport-oauth').OAuth2Strategy;
22
const InternalOAuthError = require('passport-oauth').InternalOAuthError;
23
```
24

25
## Basic Usage
26

27
```javascript
28
const { OAuthStrategy, OAuth2Strategy, InternalOAuthError } = require('passport-oauth');
29
const passport = require('passport');
30

31
// OAuth 1.0 strategy
32
passport.use('twitter', new OAuthStrategy({
33
  requestTokenURL: 'https://api.twitter.com/oauth/request_token',
34
  accessTokenURL: 'https://api.twitter.com/oauth/access_token',
35
  userAuthorizationURL: 'https://api.twitter.com/oauth/authorize',
36
  consumerKey: 'your-consumer-key',
37
  consumerSecret: 'your-consumer-secret',
38
  callbackURL: 'http://localhost:3000/auth/twitter/callback'
39
}, function(token, tokenSecret, profile, done) {
40
  // Handle user profile and authentication
41
  return done(null, profile);
42
}));
43

44
// OAuth 2.0 strategy
45
passport.use('google', new OAuth2Strategy({
46
  authorizationURL: 'https://accounts.google.com/oauth2/v2/auth',
47
  tokenURL: 'https://www.googleapis.com/oauth2/v4/token',
48
  clientID: 'your-client-id',
49
  clientSecret: 'your-client-secret',
50
  callbackURL: 'http://localhost:3000/auth/google/callback'
51
}, function(accessToken, refreshToken, profile, done) {
52
  // Handle user profile and authentication
53
  return done(null, profile);
54
}));
55

56
// Error handling
57
try {
58
  // OAuth operations
59
} catch (error) {
60
  if (error instanceof InternalOAuthError) {
61
    console.error('OAuth Error:', error.message);
62
  }
63
}
64
```
65

66
## Capabilities
67

68
### OAuth 1.0 Strategy
69

70
Constructor for implementing OAuth 1.0 authentication flows with service providers like Twitter.
71

72
```javascript { .api }
73
/**
74
 * OAuth 1.0 authentication strategy constructor
75
 * @param {OAuthOptions} options - Configuration options for OAuth 1.0
76
 * @param {Function} verify - Verification callback function
77
 * @constructor
78
 */
79
function OAuthStrategy(options, verify);
80

81
interface OAuthOptions {
82
  requestTokenURL: string;     // URL to obtain request token
83
  accessTokenURL: string;      // URL to obtain access token  
84
  userAuthorizationURL: string; // URL for user authorization
85
  consumerKey: string;         // OAuth consumer key
86
  consumerSecret: string;      // OAuth consumer secret
87
  callbackURL: string;         // Callback URL after authorization
88
  signatureMethod?: string;    // Signature method (default: HMAC-SHA1)
89
  customHeaders?: object;      // Custom headers for requests
90
  skipUserProfile?: boolean;   // Skip fetching user profile
91
}
92

93
type VerifyCallback = (
94
  token: string,
95
  tokenSecret: string, 
96
  profile: object,
97
  done: (error: any, user?: any) => void
98
) => void;
99
```
100

101
### OAuth 2.0 Strategy
102

103
Constructor for implementing OAuth 2.0 authentication flows with service providers like Google, Facebook, etc.
104

105
```javascript { .api }
106
/**
107
 * OAuth 2.0 authentication strategy constructor
108
 * @param {OAuth2Options} options - Configuration options for OAuth 2.0
109
 * @param {Function} verify - Verification callback function
110
 * @constructor
111
 */
112
function OAuth2Strategy(options, verify);
113

114
interface OAuth2Options {
115
  authorizationURL: string;    // URL for user authorization
116
  tokenURL: string;           // URL to obtain access token
117
  clientID: string;           // OAuth client ID
118
  clientSecret: string;       // OAuth client secret
119
  callbackURL: string;        // Callback URL after authorization
120
  scope?: string | string[];  // OAuth scopes
121
  scopeSeparator?: string;    // Scope separator (default: space)
122
  customHeaders?: object;     // Custom headers for requests
123
  skipUserProfile?: boolean;  // Skip fetching user profile
124
  pkce?: boolean;            // Use PKCE (Proof Key for Code Exchange)
125
  state?: boolean;           // Include state parameter
126
}
127

128
type OAuth2VerifyCallback = (
129
  accessToken: string,
130
  refreshToken: string,
131
  profile: object,
132
  done: (error: any, user?: any) => void
133
) => void;
134
```
135

136
### Internal OAuth Error
137

138
Error constructor for OAuth-related internal errors.
139

140
```javascript { .api }
141
/**
142
 * Internal OAuth error constructor for handling OAuth-specific errors
143
 * @param {string} message - Error message
144
 * @param {object} data - Additional error data
145
 * @constructor
146
 */
147
function InternalOAuthError(message, data);
148

149
interface InternalOAuthError extends Error {
150
  name: 'InternalOAuthError';
151
  message: string;
152
  data?: object;  // Additional error information from OAuth provider
153
}
154
```
155

156
## Migration Notes
157

158
This package exists for backwards compatibility with the 0.1.x line of OAuth strategies. For new applications, it is recommended to declare dependencies directly on the specific OAuth version modules:
159

160
- Use `passport-oauth1` for OAuth 1.0 implementations
161
- Use `passport-oauth2` for OAuth 2.0 implementations
162

163
## Error Handling
164

165
The `InternalOAuthError` constructor is available for handling OAuth-specific errors that may occur during the authentication process. These errors typically contain additional data from the OAuth provider that can help with debugging authentication issues.
166

167
```javascript
168
const { InternalOAuthError } = require('passport-oauth');
169

170
// Check for OAuth errors
171
if (error instanceof InternalOAuthError) {
172
  console.error('OAuth provider error:', error.message);
173
  console.error('Provider data:', error.data);
174
}
175
```