@octokit/auth-oauth-user
v5.1.1
Published
Octokit authentication strategy for OAuth clients
Downloads
5,148,305
Readme
auth-oauth-user.js
Octokit authentication strategy for OAuth user authentication
Important: @octokit/auth-oauth-user
requires your app's client_secret
, which must not be exposed. If you are looking for an OAuth user authentication strategy that can be used on a client (browser, IoT, CLI), check out @octokit/auth-oauth-user-client
. Note that @octokit/auth-oauth-user-client
requires a backend. The only exception is @octokit/auth-oauth-device
which does not require the client_secret
, but does not work in browsers due to CORS constraints.
- Features
- Standalone usage
- Usage with Octokit
createOAuthUserAuth(options)
ornew Octokit({ auth })
auth(options)
oroctokit.auth(options)
- Authentication object
auth.hook(request, route, parameters)
orauth.hook(request, options)
- Types
- Contributing
- License
Features
- Code for token exchange from GitHub's OAuth web flow
- GitHub's OAuth device flow
- Caches token for succesive calls
- Auto-refreshing for expiring user access tokens
- Applies the correct authentication strategy based on the request URL when using with
Octokit
- Token verification
- Token reset
- Token invalidation
- Application grant revocation
Standalone usage
Browsers
Load @octokit/auth-oauth-user
directly from esm.sh
<script type="module">
import { createOAuthUserAuth } from "https://esm.sh/@octokit/auth-oauth-user";
</script>
Node
Install with npm install @octokit/auth-oauth-user
import { createOAuthUserAuth } from "@octokit/auth-oauth-user";
Exchange code from OAuth web flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
// optional
state: "state123",
redirectUrl: "https://acme-inc.com/login",
});
// Exchanges the code for the user access token authentication on first call
// and caches the authentication for successive calls
const { token } = await auth();
About GitHub's OAuth web flow
OAuth Device flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
onVerification(verification) {
// verification example
// {
// device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
// user_code: "WDJB-MJHT",
// verification_uri: "https://github.com/login/device",
// expires_in: 900,
// interval: 5,
// };
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
},
});
// resolves once the user entered the `user_code` on `verification_uri`
const { token } = await auth();
About GitHub's OAuth device flow
Use an existing authentication
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
clientType: "oauth-app",
token: "token123",
});
// will return the passed authentication
const { token } = await auth();
Usage with Octokit
Browsers
@octokit/auth-oauth-user
cannot be used in the browser. It requires clientSecret
to be set which must not be exposed to clients, and some of the OAuth APIs it uses do not support CORS.
Node
Install with npm install @octokit/core @octokit/auth-oauth-user
. Optionally replace @octokit/core
with a compatible module
import { Octokit } from "@octokit/core";
import { createOAuthUserAuth } from "@octokit/auth-oauth-user";
const octokit = new Octokit({
authStrategy: createOAuthUserAuth,
auth: {
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
},
});
// Exchanges the code for the user access token authentication on first request
// and caches the authentication for successive requests
const {
data: { login },
} = await octokit.request("GET /user");
console.log("Hello, %s!", login);
createOAuthUserAuth(options)
or new Octokit({ auth })
The createOAuthUserAuth
method accepts a single options
object as argument. The same set of options can be passed as auth
to the Octokit
constructor when setting authStrategy: createOAuthUserAuth
When using GitHub's OAuth web flow
Required. The authorization code which was passed as query parameter to the callback URL from GitHub's OAuth web application flow.
The unguessable random string you provided in Step 1 of GitHub's OAuth web application flow.
The redirect_uri parameter you provided in Step 1 of GitHub's OAuth web application flow.
import { request } from "@octokit/request";
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
When using GitHub's OAuth device flow
Required. A function that is called once the device and user codes were retrieved
The onVerification()
callback can be used to pause until the user completes step 2, which might result in a better user experience.
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
onVerification(verification) {
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
await prompt("press enter when you are ready to continue");
},
});
import { request } from "@octokit/request";
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
onVerification(verification) {
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
await prompt("press enter when you are ready to continue");
},
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
When passing an existing authentication object
import { request } from "@octokit/request";
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
[!IMPORTANT] As we use conditional exports, you will need to adapt your
tsconfig.json
by setting"moduleResolution": "node16", "module": "node16"
.See the TypeScript docs on package.json "exports". See this helpful guide on transitioning to ESM from @sindresorhus
auth(options)
or octokit.auth(options)
The async auth()
method is returned by createOAuthUserAuth(options)
or set on the octokit
instance when the Octokit
constructor was called with authStrategy: createOAuthUserAuth
.
Once auth()
receives a valid authentication object it caches it in memory and uses it for subsequent calls. It also caches if the token is invalid and no longer tries to send any requests. If the authentication is using a refresh token, a new token will be requested as needed. Calling auth({ type: "reset" })
will replace the internally cached authentication.
Resolves with an authentication object.
Without setting type
auth will return the current authentication object, or exchange the code
from the strategy options on first call. If the current authentication token is expired, the tokens will be refreshed.
Possible values for type
are
"get"
: returns the token from internal state and creates it if none was created yet"check"
: sends request to verify the validity of the current token"reset"
: invalidates current token and replaces it with a new one"refresh"
: GitHub Apps only, and only if expiring user tokens are enabled."delete"
: invalidates current token"deleteAuthorization"
: revokes OAuth access for application. All tokens for the current user created by the same app are invalidated. The user will be prompted to grant access again during the next OAuth web flow.
Authentication object
There are three possible results
- OAuth APP authentication token
- GitHub APP user authentication token with expiring disabled
- GitHub APP user authentication token with expiring enabled
The differences are
scopes
is only present for OAuth AppsrefreshToken
,expiresAt
,refreshTokenExpiresAt
are only present for GitHub Apps, and only if token expiration is enabled
OAuth APP authentication token
Either undefined
or true
. Will be set to true
if the token was invalided explicitly or found to be invalid
GitHub APP user authentication token with expiring disabled
Either undefined
or true
. Will be set to true
if the token was invalided explicitly or found to be invalid
GitHub APP user authentication token with expiring enabled
Either undefined
or true
. Will be set to true
if the token was invalided explicitly or found to be invalid
auth.hook(request, route, parameters)
or auth.hook(request, options)
auth.hook()
hooks directly into the request life cycle. It amends the request to authenticate correctly based on the request URL.
The request
option is an instance of @octokit/request
. The route
/options
parameters are the same as for the request()
method.
auth.hook()
can be called directly to send an authenticated request
const { data: user } = await auth.hook(request, "GET /user");
Or it can be passed as option to request()
.
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});
const { data: user } = await requestWithAuth("GET /user");
Types
import {
GitHubAppAuthentication,
GitHubAppAuthenticationWithExpiration,
GitHubAppAuthOptions,
GitHubAppStrategyOptions,
GitHubAppStrategyOptionsDeviceFlow,
GitHubAppStrategyOptionsExistingAuthentication,
GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
GitHubAppStrategyOptionsWebFlow,
OAuthAppAuthentication,
OAuthAppAuthOptions,
OAuthAppStrategyOptions,
OAuthAppStrategyOptionsDeviceFlow,
OAuthAppStrategyOptionsExistingAuthentication,
OAuthAppStrategyOptionsWebFlow,
} from "@octokit/auth-oauth-user";
Contributing
See CONTRIBUTING.md