GitHub API authentication strategies for Browsers, Node.js, and Deno
Module: @octokit/auth-token
The simplest authentication strategy requires a user to create a personal access token at https://github.com/settings/tokens/new and pass it as the single argument to the createTokenAuth() 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
const auth = createTokenAuth("1234567890abcdef1234567890abcdef12345678");
const { token } = await auth(); GitHub App or installation authentication
Module: @octokit/auth-app SDK: @octokit/app
A GitHub app has four different means of authentication.
Module: @octokit/auth-oauth-app SDK: @octokit/oauth-app
An OAuth app has two different means of authentication.
There are differences between OAuth Apps and the OAuth features from GitHub Apps:
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 the OAuth web flow or OAuth Device flow
There are differences between OAuth Apps and the OAuth features from GitHub Apps, see the list in OAuth app authentication.
Important: @octokit/auth-oauth-user requires your app's client_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), see OAUth user client authentication or Device authentication
🚧 TBD, see https://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 the web 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 between OAuth Apps and the OAuth features from GitHub Apps, see the list in OAuth app authentication.
GitHub Action authenticationModule: @octokit/auth-action SDK: @octokit/action
GitHub actions provide a secrets.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 the installation webhook event when the action is delete or suspend. 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 new octokit instance each time.
Module: octokit-auth-netrc
Similar to token 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");
const auth = createNetrcAuth();
const { token } = await auth();
See octokit-auth-netrc for more details.
How authentication strategies workAll authentication strategies implement the same interface
const auth = authenticationStrategy(strategyOptions); const authentication = await auth(authOptions); auth.hook(request, route, parameters);
It can be used with an Octokit constructor by setting the authStrategy and auth constructor options. auth.hook is automatically applied to all requests sent by the octokit instance.
const octokit = new Octokit({
authStrategy: authenticationStrategy,
auth: strategyOptions,
});
const authentication = await octokit.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-authenticated octokit 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.
authenticationStrategy(strategyOptions)
The authentication strategy is a synchronous method which returns the auth interface. strategyOptions can be optional, but must always be an object.
The auth interface is an asynchronous function which accepts authOptions and resolves with an authentication object. authOptions can be optional, but must always be an object. The auth interface also provides an auth.hook interface which can be used to hook into the request lifecycle of @octokit/request (see options.request.hook) or octokit.request.
authOptions.factory pattern
In some cases, auth(authOptions) needs to resolve with another auth interface, or octokit.auth(authOptions) with another octokit 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
const appOctokit = new Octokit({
authStrategy: createAppAuth
auth: { appId, privateKey }
})
const installationAuthentication = appOctokit.auth({
type: "installation",
installationId
})
This internal state would get lost if a separate octokit instance would be created for an installation
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: { appId, privateKey },
});
const installationOctokit = new Octokit({
authStrategy: createAppAuth,
auth: { appId, privateKey, installationId },
});
Instead, installationOctokit can be created from appOctokit.auth, and both can share the cached installation access tokens
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: { appId, privateKey },
});
const installationOctokit = appOctokit.auth({
type: "installation",
installationId,
factory: ({ octokitOptions, ...auth }) =>
new Octokit({ ...octokitOptions, auth }),
}); Create your own Octokit authentication strategy module
Use create-octokit-project, follow instructions, and send a pull request to add your own strategy to this README
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4
