Repository files navigation

GitHub API authentication strategies for Browsers, Node.js, and Deno

• Official Authentication Strategies
  • Personal Access Token authentication
  • GitHub App or installation authentication
  • OAuth app authentication
  • OAuth user authentication
  • OAuth user client authentication
  • Device authentication
  • GitHub Action authentication
• Other Strategies
  • unauthenticated
  • callback
  • .netrc
• How authentication strategies work
  • authenticationStrategy(strategyOptions)
  • auth interface
  • TheauthOptions.factory pattern
• Create your own Octokit authentication strategy module
• License

Module:@octokit/auth-token

The simplest authentication strategy requires a user to create a personal access token athttps://github.com/settings/tokens/new and pass it as the single argument to thecreateTokenAuth() function. You can pass in any other token such as an installation access token or a OAuth user access token, but there are dedicated strategies for the respective use cases which might be a better fit.

@octokit/auth-token is the default authentication strategy built into@octokit/core

constauth=createTokenAuth("1234567890abcdef1234567890abcdef12345678");const{ token}=awaitauth();

Module:@octokit/auth-appSDK:@octokit/app

A GitHub app has four different means of authentication.

1. It can authenticate as itself using a JWT (JSON Web Token) derived from the app ID and a private key. JWT authentication is required to iterate through installations and repositories, use the marketplace APIs, or to create installation access tokens.
2. It can authenticate as an installation using an installation access tokens. GitHub apps can be actors like GitHub users. They can create issues, manage teams, and much more. Installing a GitHub app grants access to a GitHub user account or organization, and either all or selected repositories. The installation inherits the app's permissions at this point, they will not be altered if the app's permissions change until the user/organization account owner accepts the new permissions. Installation access tokens expire after 1h, and they can be created with a subset of the installations permissions and accessible repositories.
3. It can authenticate as OAuth App using Basic Authentication derived from the client ID and a client secret. Basic authentication is required to create, reset, refresh, scope, and delete OAuth user authentication tokens. See alsoOAuth App authentication
4. It can authenticate as user using an OAuth user-to-server access token. A user-to-server token authenticates as both a user and the app/installation. It can be created using theOAuth web flow orOAuth Device flow. See alsoOAuth user authentication

Module:@octokit/auth-oauth-appSDK:@octokit/oauth-app

An OAuth app has two different means of authentication.

3. It can authenticate as OAuth App using Basic Authentication derived from the client ID and a client secret. Basic authentication is required to create, reset, refresh, scope, and delete OAuth user authentication tokens.
4. It can authenticate as user using an OAuth user-to-server access token. A user-to-server token authenticates as both a user and the app/installation. It can be created using theOAuth web flow orOAuth Device flow. See alsoOAuth user authentication

There are differences betweenOAuth Apps and the OAuth features fromGitHub Apps:

• OAuth apps support scopes. Different scopes can be set each time a user-access token is created. They cannot be limited globally for the OAuth app.
• GitHub apps have permissions. The are set when the app is registered. The app cannot access any repository until it is installed by a user. The installation inherits the app's permissions at the time of the installation. Permission changes need to be approved by the user.
• OAuth apps create OAuth user access tokens which have work the same on all repositories
• GitHub apps create OAuth user-to-server access tokens which inher both the app's user permissions as well as each installation's repository and user/organization permissions.
• GitHub apps can enable expiration for its user-to-server access tokens. OAuth apps do not have such a feature.

Module:@octokit/auth-oauth-user

OAuth user authentication can be created by both OAuth Apps and GitHub Apps. OAuth Apps create OAuth user access tokens which are granted a set of scopes at the time of creation. GitHub apps create user-to-server tokens which authenticate as both a user and the app/installation. It can be created using theOAuth web flow orOAuth Device flow

There are differences betweenOAuth Apps and the OAuth features fromGitHub Apps, see the list inOAuth app authentication.

Important:@octokit/auth-oauth-user requires your app'sclient_secret, which must not be exposed to users. If you are looking for an OAuth user authentication strategy that can be used on a client (browser, IoT, CLI), seeOAUth user client authentication orDevice authentication

🚧 TBD, seehttps://github.com/octokit/auth-oauth-user-client.js#readme

Module:@octokit/auth-oauth-device

Device flow authentication is a way to create OAuth user authentication. Unlike theweb flow, there is no http redirect required in order to retrieve an OAuth code for the user access token exchange. It also does not require the client secret, which makes it a great solution for IoT devices or CLI applications.

Unfortunately the device flow cannot be used for browsers, as the APIs to request user/device codes and the user access token exchange are not enabled for cross-domain requests (CORS).

There are differences betweenOAuth Apps and the OAuth features fromGitHub Apps, see the list inOAuth app authentication.

Module:@octokit/auth-actionSDK:@octokit/action

GitHub actions provide asecrets.GITHUB_TOKEN variable which can be used to authenticate scripts run as part of a GitHub Action workflow.

Technically,secrets.GITHUB_TOKEN is an installation access token that has all repository permissions but only access to the current repositories. It expires after 6h or when the current workflow step is completed. It cannot be renewed as the app ID and private key credentials are not exposed.

Module:@octokit/auth-unauthenticated

This authentication strategy is useful to provide a helpful error message when no valid authentication can be provided. An example is an event handler for theinstallation webhook event when the action isdelete orsuspend. In this case the authorization for the installation has been revoked and no requests can be sent anymore. Instead of failing with a cryptic error message,@octokit/auth-unauthenticated can be used to explain that the access for the installation has been revoked.

Module:@octokit/auth-callback

This authentication strategy accepts a single{ callback } strategy option which returns either a falsy value or the string for a valid token. It's great for single-page web applications where a user can sign in/sign out without the need to re-instantiate a newoctokit instance each time.

Module:octokit-auth-netrc

Similar totoken authentication, but reads the token from your~/.netrc file

Example

// expects a personal access token to be set as `login` in the `~/.netrc` file for `api.github.com`const{ createNetrcAuth}=require("octokit-netrc-auth");constauth=createNetrcAuth();const{ token}=awaitauth();

Seeoctokit-auth-netrc for more details.

All authentication strategies implement the same interface

constauth=authenticationStrategy(strategyOptions);constauthentication=awaitauth(authOptions);auth.hook(request,route,parameters);

It can be used with anOctokit constructor by setting theauthStrategy andauth constructor options.auth.hook is automatically applied to all requests sent by theoctokit instance.

constoctokit=newOctokit({authStrategy:authenticationStrategy,auth:strategyOptions,});constauthentication=awaitoctokit.auth(authOptions);

This interface an auth strategy to hook into a request lifecycle, implement request retries if necessary or transparent on-demand authentication creation.

For example, when implementing a GitHub App which acts on webhook events, a pre-authenticatedoctokit instance should be provided to the event handler. But an installation access token should not be created until a request is sent in that event handler.

In other cases, tokens might be invalid due to out-of-sync time between GitHub's API servers and yours. The time difference can be detected and corrected with an additional request.

The authentication strategy is a synchronous method which returns theauth interface.strategyOptions can be optional, but must always be an object.

Theauth interface is an asynchronous function which acceptsauthOptions and resolves with anauthentication object.authOptions can be optional, but must always be an object. Theauth interface also provides anauth.hook interface which can be used to hook into the request lifecycle of@octokit/request (seeoptions.request.hook) oroctokit.request.

In some cases,auth(authOptions) needs to resolve with anotherauth interface, oroctokit.auth(authOptions) with anotheroctokit instance. For example, when using the GitHub App authentication strategy (@octokit/auth-app), the auth interface has an internal state that caches the installation access tokens it created for reusability

constappOctokit=newOctokit({authStrategy:createAppAuthauth:{appId, privateKey}})constinstallationAuthentication=appOctokit.auth({type:"installation",  installationId})

This internal state would get lost if a separateoctokit instance would be created for an installation

constappOctokit=newOctokit({authStrategy:createAppAuth,auth:{ appId, privateKey},});constinstallationOctokit=newOctokit({authStrategy:createAppAuth,auth:{ appId, privateKey, installationId},});

Instead,installationOctokit can be created fromappOctokit.auth, and both can share the cached installation access tokens

constappOctokit=newOctokit({authStrategy:createAppAuth,auth:{ appId, privateKey},});constinstallationOctokit=appOctokit.auth({type:"installation",  installationId,factory:({ octokitOptions, ...auth})=>newOctokit({ ...octokitOptions, auth}),});

Usecreate-octokit-project, follow instructions, and send a pull request to add your own strategy to this README

npm init octokit-project

MIT