octokit/auth-oauth-app.jsPublic

NotificationsYou must be signed in to change notification settings
Fork14
Star74

GitHub OAuth App authentication for JavaScript

License

MIT license

74 stars 14 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 577 Commits
.github		.github
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Repository files navigation

auth-oauth-app.js

GitHub OAuth App authentication for JavaScript

@octokit/auth-oauth-app is implementing one ofGitHub’s authentication strategies.

It implements authentication using an OAuth app’s client ID and secret as well as creating user access tokens GitHub's OAuthweb application flow anddevice flow.

Standalone Usage

Browsers

Browsers	⚠️`@octokit/auth-oauth-app` is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client. If you know what you are doing, load`@octokit/auth-oauth-app` directly fromesm.sh <scripttype="module">import{createOAuthAppAuth}from"https://esm.sh/@octokit/auth-oauth-app";</script>
Node	Install with`npm install @octokit/auth-oauth-app` import{createOAuthAppAuth}from"@octokit/auth-oauth-app";

⚠️@octokit/auth-oauth-app is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client.

If you know what you are doing, load@octokit/auth-oauth-app directly fromesm.sh

<scripttype="module">import{createOAuthAppAuth}from"https://esm.sh/@octokit/auth-oauth-app";</script>

Node

Install withnpm install @octokit/auth-oauth-app

import{createOAuthAppAuth}from"@octokit/auth-oauth-app";

Important

As we useconditional exports, you will need to adapt yourtsconfig.json by setting"moduleResolution": "node16", "module": "node16".

See the TypeScript docs onpackage.json "exports".
See thishelpful guide on transitioning to ESM from@sindresorhus

Authenticate as app

constauth=createOAuthAppAuth({clientType:"oauth-app",clientId:"1234567890abcdef1234",clientSecret:"1234567890abcdef1234567890abcdef12345678",});constappAuthentication=awaitauth({type:"oauth-app",});

resolves with

{"type":"oauth-app","clientId":"1234567890abcdef1234","clientSecret":"1234567890abcdef1234567890abcdef12345678","headers": {"authorization":"basic MTIzNDU2Nzg5MGFiY2RlZjEyMzQ6MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3OA=="  }}

Authenticate user using OAuth Web Flow

Exchange code from GitHub's OAuth web flow, seehttps://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github

constauth=createOAuthAppAuth({clientType:"oauth-app",clientId:"1234567890abcdef1234",clientSecret:"1234567890abcdef1234567890abcdef12345678",});constuserAuthenticationFromWebFlow=awaitauth({type:"oauth-user",code:"random123",state:"mystate123",});

resolves with

{"clientType":"oauth-app","clientId":"1234567890abcdef1234","clientSecret":"1234567890abcdef1234567890abcdef12345678","type":"token","tokenType":"oauth","token":"useraccesstoken123","scopes": []}

Authenticate user using OAuth Device flow

Pass an asynchronousonVerification() method which will be called with the response from step 1 of the device flow. In that function you have to prompt the user to enter the user code at the provided verification URL.

auth() will not resolve until the user entered the code and granted access to the app.

Seehttps://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github

constauth=createOAuthAppAuth({clientType:"oauth-app",clientId:"1234567890abcdef1234",clientSecret:"1234567890abcdef1234567890abcdef12345678",});constuserAuthenticationFromDeviceFlow=awaitauth({asynconVerification(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 with

{"clientType":"oauth-app","clientId":"1234567890abcdef1234","clientSecret":"1234567890abcdef1234567890abcdef12345678","type":"token","tokenType":"oauth","token":"useraccesstoken123","scopes": []}

Usage with Octokit

Browsers	⚠️`@octokit/auth-oauth-app` is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client. If you know what you are doing, load`@octokit/auth-oauth-app` and`@octokit/core` (or a compatible module) directly fromesm.sh <scripttype="module">import{createOAuthAppAuth}from"https://esm.sh/@octokit/auth-oauth-app";import{Octokit}from"https://esm.sh/@octokit/core";</script>
Node	Install with`npm install @octokit/core @octokit/auth-oauth-app`. Optionally replace`@octokit/core` with a compatible module import{Octokit}from"@octokit/core";import{createOAuthAppAuth,createOAuthUserAuth,}from"@octokit/auth-oauth-app";

Browsers

⚠️@octokit/auth-oauth-app is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client.

If you know what you are doing, load@octokit/auth-oauth-app and@octokit/core (or a compatible module) directly fromesm.sh

<scripttype="module">import{createOAuthAppAuth}from"https://esm.sh/@octokit/auth-oauth-app";import{Octokit}from"https://esm.sh/@octokit/core";</script>

Node

Install withnpm install @octokit/core @octokit/auth-oauth-app. Optionally replace@octokit/core with a compatible module

import{Octokit}from"@octokit/core";import{createOAuthAppAuth,createOAuthUserAuth,}from"@octokit/auth-oauth-app";

constappOctokit=newOctokit({authStrategy:createOAuthAppAuth,auth:{clientId:"1234567890abcdef1234",clientSecret:"1234567890abcdef1234567890abcdef12345678",},});// Send requests as appawaitappOctokit.request("POST /application/{client_id}/token",{client_id:"1234567890abcdef1234",access_token:"existingtoken123",});console.log("token is valid");// create a new octokit instance that is authenticated as the userconstuserOctokit=awaitappOctokit.auth({type:"oauth-user",code:"code123",factory:(options)=>{returnnewOctokit({authStrategy:createOAuthUserAuth,auth:options,});},});// Exchanges the code for the user access token authentication on first request// and caches the authentication for successive requestsconst{data:{ login},}=awaituserOctokit.request("GET /user");console.log("Hello, %s!",login);

`createOAuthAppAuth(options)` or`new Octokit({ auth })`

ThecreateOAuthAppAuth method accepts a singleoptions object as argument. The same set of options can be passed asauth to theOctokit constructor when settingauthStrategy: createOAuthAppAuth

name	type	description
`clientId`	`string`	Required. Find your OAuth app’s`Client ID` in your account’s developer settings.
`clientSecret`	`string`	Required. Find your OAuth app’s`Client Secret` in your account’s developer settings.
`clientType`	`string`	Must be set to either`"oauth-app"` or`"github-app"`. Defaults to`"oauth-app"`
`request`	`function`	You can pass in your own`@octokit/request` instance. For usage with enterprise, set`baseUrl` to the API root endpoint. Example: import{request}from"@octokit/request";createOAuthAppAuth({clientId:"1234567890abcdef1234",clientSecret:"1234567890abcdef1234567890abcdef12345678",request:request.defaults({baseUrl:"https://ghe.my-company.com/api/v3",}),});

`auth(options)` or`octokit.auth(options)`

The asyncauth() method returned bycreateOAuthAppAuth(options) accepts different options depending on your use case

Client ID/Client Secret Basic authentication

All REST API routes starting with/applications/{client_id} need to be authenticated using the OAuth/GitHub App's Client ID and a client secret.

name	type	description
`type`	`string`	Required. Must be set to`"oauth-app"`

OAuth web flow

Exchangecode for a user access token. SeeWeb application flow.

name	type	description
`type`	`string`	Required. Must be set to`"oauth-user"`.
`code`	`string`	Required. The authorization`code` which was passed as query parameter to the callback URL from theOAuth web application flow.
`redirectUrl`	`string`	The URL in your application where users are sent after authorization. Seeredirect urls.
`state`	`string`	The unguessable random string you provided in Step 1 of theOAuth web application flow.
`factory`	`function`	When the`factory` option is, the`auth({type: "oauth-user", code, factory })` call with resolve with whatever the`factory` function returns. The`factory` function will be called with all the strategy option that`auth` was created with, plus the additional options passed to`auth`, besides`type` and`factory`. For example, you can create a new`auth` instance for a user using`createOAuthUserAuth` which implements auto-refreshing tokens, among other features. You can import`createOAuthUserAuth` directly from`@octokit/auth-oauth-app` which will ensure compatibility. import{createOAuthAppAuth,createOAuthUserAuth,}from"@octokit/auth-oauth-app";constappAuth=createOAuthAppAuth({clientType:"github-app",clientId:"lv1.1234567890abcdef",clientSecret:"1234567890abcdef1234567890abcdef12345678",});constuserAuth=awaitappAuth({type:"oauth-user", code,factory:createOAuthUserAuth,});// will create token upon first call, then cache authentication for successive calls,// until token needs to be refreshed (if enabled for the GitHub App)constauthentication=awaituserAuth();

OAuth device flow

Create a user access token without an http redirect. SeeDevice flow.

The device flow does not require a client secret, but it is required as strategy option for@octokit/auth-oauth-app, even for the device flow. If you want to implement the device flow without requiring a client secret, use@octokit/auth-oauth-device.

name	type	description
`type`	`string`	Required. Must be set to`"oauth-user"`.
`onVerification`	`function`	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. constauth=auth({type:"oauth-user",asynconVerification(verification){console.log("Open %s",verification.verification_uri);console.log("Enter code: %s",verification.user_code);awaitprompt("press enter when you are ready to continue");},});
`scopes`	`array of strings`	Only relevant if the`clientType` strategy option is set to`"oauth-app"`.Array of OAuth scope names that the user access token should be granted. Defaults to no scopes (`[]`).
`factory`	`function`	When the`factory` option is, the`auth({type: "oauth-user", code, factory })` call with resolve with whatever the`factory` function returns. The`factory` function will be called with all the strategy option that`auth` was created with, plus the additional options passed to`auth`, besides`type` and`factory`. For example, you can create a new`auth` instance for a user using`createOAuthUserAuth` which implements auto-refreshing tokens, among other features. You can import`createOAuthUserAuth` directly from`@octokit/auth-oauth-app` which will ensure compatibility. import{createOAuthAppAuth,createOAuthUserAuth,}from"@octokit/auth-oauth-app";constappAuth=createOAuthAppAuth({clientType:"github-app",clientId:"lv1.1234567890abcdef",clientSecret:"1234567890abcdef1234567890abcdef12345678",});constuserAuth=awaitappAuth({type:"oauth-user", onVerification,factory:createOAuthUserAuth,});// will create token upon first call, then cache authentication for successive calls,// until token needs to be refreshed (if enabled for the GitHub App)constauthentication=awaituserAuth();

Authentication object

The asyncauth(options) method to one of four possible authentication objects

OAuth App authentication forauth({ type: "oauth-app" })
OAuth user access token authentication forauth({ type: "oauth-app" }) and App is an OAuth App (OAuth user access token)
GitHub APP user authentication token with expiring disabled forauth({ type: "oauth-app" }) and App is a GitHub App (user-to-server token)
GitHub APP user authentication token with expiring enabled forauth({ type: "oauth-app" }) and App is a GitHub App (user-to-server token)

OAuth App authentication

name	type	description
`type`	`string`	`"oauth-app"`
`clientType`	`string`	`"oauth-app"` or`"github-app"`
`clientId`	`string`	The client ID as passed to the constructor.
`clientSecret`	`string`	The client secret as passed to the constructor.
`headers`	`object`	`{ authorization }`.

OAuth user access token authentication

name	type	description
`type`	`string`	`"token"`
`tokenType`	`string`	`"oauth"`
`clientType`	`string`	`"oauth-app"`
`clientId`	`string`	The`clientId` from the strategy options
`clientSecret`	`string`	The`clientSecret` from the strategy options
`token`	`string`	The user access token
`scopes`	`array of strings`	array of scope names enabled for the token

GitHub APP user authentication token with expiring disabled

name	type	description
`type`	`string`	`"token"`
`tokenType`	`string`	`"oauth"`
`clientType`	`string`	`"github-app"`
`clientId`	`string`	The app's`Client ID`
`clientSecret`	`string`	One of the app's client secrets
`token`	`string`	The user access token

GitHub APP user authentication token with expiring enabled

name	type	description
`type`	`string`	`"token"`
`tokenType`	`string`	`"oauth"`
`clientType`	`string`	`"github-app"`
`clientId`	`string`	The app's`Client ID`
`clientSecret`	`string`	One of the app's client secrets
`token`	`string`	The user access token
`refreshToken`	`string`	The refresh token
`expiresAt`	`string`	Date timestamp inISO 8601 standard. Example:`2022-01-01T08:00:0.000Z`
`refreshTokenExpiresAt`	`string`	Date timestamp inISO 8601 standard. Example:`2021-07-01T00:00:0.000Z`

`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 usingclientId andclientSecret as basic auth for the API endpoints that support it. It throws an error in other cases.

Therequest option is an instance of@octokit/request. Theroute/options parameters are the same as for therequest() method.

auth.hook() can be called directly to send an authenticated request

const{data:user}=awaitauth.hook(request,"POST /applications/{client_id}/token",{client_id:"1234567890abcdef1234",access_token:"token123",},);

Or it can be passed as option torequest().

constrequestWithAuth=request.defaults({request:{hook:auth.hook,},});const{data:user}=awaitrequestWithAuth("POST /applications/{client_id}/token",{client_id:"1234567890abcdef1234",access_token:"token123",},);

Types

import{// strategy optionsOAuthAppStrategyOptions,GitHubAppStrategyOptions,// auth optionsAppAuthOptions,WebFlowAuthOptions,OAuthAppDeviceFlowAuthOptions,GitHubAppDeviceFlowAuthOptions,// auth interfacesOAuthAppAuthInterface,GitHubAuthInterface,// authentication objectAppAuthentication,OAuthAppUserAuthentication,GitHubAppUserAuthentication,GitHubAppUserAuthenticationWithExpiration,}from"@octokit/auth-oauth-app";

Implementation details

Client ID and secret can be passed as Basic auth in theAuthorization header in order to get a higher rate limit compared to unauthenticated requests. This is meant for the use on servers only: never expose an OAuth client secret on a client such as a web application!

auth.hook will set the correct authentication header automatically based on the request URL. For allOAuth Application endpoints, theAuthorization header is set to basic auth. For all other endpoints and token is retrieved and used in theAuthorization header. The token is cached and used for succeeding requests.

To reset the cached access token, you can do this

const{ token}=awaitauth({type:"oauth-user"});awaitauth.hook(request,"POST /applications/{client_id}/token",{client_id:"1234567890abcdef1234",access_token:token,});