|
+### OAuth user authentication
-`@octokit/auth-token`
+**Module**: [`@octokit/auth-oauth-user`](https://github.com/octokit/auth-oauth-user.js#readme)
- |
+OAuth user authentication 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](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) or [OAuth Device flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#device-flow)
-```
-token
-```
+There are differences between [OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps) and the OAuth features from [GitHub Apps](https://docs.github.com/en/developers/apps/building-github-apps), see the list in [OAuth app authentication](#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](#oauth-user-client-authentication) or [Device authentication](#device-authentication)
-```
--
-```
+### OAuth user client authentication
- |
+🚧 TBD, see https://github.com/octokit/auth-oauth-user-client.js#readme
-```
-{
- type: "token",
- token: "secret123",
- tokenType, "oauth" // or "installation"
-}
-```
+### Device authentication
- |
-|
+**Module**: [`@octokit/auth-oauth-device`](https://github.com/octokit/auth-oauth-device.js#readme)
-`@octokit/auth-app`
+[Device flow authentication](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#device-flow) is a way to create OAuth user authentication. Unlike the [web flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-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).
-```
-{
- id*,
- privateKey*,
- installationId,
- cache,
- request
-}
-```
+There are differences between [OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps) and the OAuth features from [GitHub Apps](https://docs.github.com/en/developers/apps/building-github-apps), see the list in [OAuth app authentication](#oauth-app-authentication).
- |
+### GitHub Action authentication
-```
-{
- type*, // "app" or "installation"
- installationId,
- repositoryIds,
- permissions,
- refresh
-}
-```
+**Module**: [`@octokit/auth-action`](https://github.com/octokit/auth-action.js#readme)
+**SDK**: [`@octokit/action`](https://github.com/octokit/action.js#readme)
- |
+GitHub actions provide a [`secrets.GITHUB_TOKEN`](https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables) variable which can be used to authenticate scripts run as part of a GitHub Action workflow.
-```
-{
- type: "app",
- token: "abc.def.1234",
- appId: 123,
- expiresAt: "2019-06-11T22:22:34Z"
-}
-```
+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.
- |
+## Other Strategies
-```
-{
- type: "token",
- tokenType: "installation",
- token: "v1.secret123",
- installationId: 1234,
- expiresAt: "2019-06-11T22:22:34Z",
- repositoryIds: [12345],
- permissions: {
- single_file: 'write'
- },
- singleFileName: '.github/myapp.yml'
-}
-```
+### unauthenticated
- |
-|
+**Module**: [`@octokit/auth-unauthenticated`](https://github.com/octokit/auth-unauthenticated.js#readme)
-`@octokit/auth-oauth-app`
+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](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#installation) 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.
- |
+### callback
-```
-{
- clientId*,
- clientSecret*,
- code,
- redirectUrl,
- state,
- request
-}
-```
+**Module**: [`@octokit/auth-callback`](https://github.com/octokit/auth-callback.js#readme)
- |
+This authentication strategy accepts a single `{ callback }` startegy 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.
-```
-{
- type*, // "oauth-app" or "token"
- url
-}
-```
+### .netrc
- |
+**Module**: [`octokit-auth-netrc`](https://github.com/travi/octokit-auth-netrc/#readme)
-```
-{
- type: "oauth-app",
- clientId: "abc123",
- clientSecret: "abc123secret",
- headers: {},
- query: {
- clientId: "abc123",
- clientSecret: "abc123secret"
- }
-}
-```
+Similar to [token authentication](#personal-access-token-authentication), but reads the token from your `~/.netrc` file
- |
+Example
-```
-{
- type: "token",
- tokenType: "oauth",
- token: "123secret",
- scopes: []
-}
+```js
+// 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](https://github.com/travi/octokit-auth-netrc) for more details.
-`@octokit/auth-action`
+## How authentication strategies work
- |
+All authentication strategies implement the same interface
-```
--
+```js
+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.
-```
--
+```js
+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.
-```
-{
- type: "token",
- tokenType: "installation",
- token: "v1.123secret"
-}
-```
+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.
- |
-