⚠️ Deprecation warning

Authentication using a username and password has been deprecated by GitHub on February 14, 2020.

It will be removed entirely on November 13, 2020. Brownouts are scheduled for September 30, 2020 and October 28, 2020.

See the official deprecation announcement for more details.

auth-basic.js

> GitHub API Basic authentication for browsers and Node.js


@octokit/auth-basic is implementing one of GitHub’s authentication strategies: authenticating using username and password.

- Usage
- createBasicAuth() options
- auth() options
- auth() result
- Personal access token authentication
- OAuth access token authentication
- Basic authentication result
- auth.hook(request, route, options) or auth.hook(request, options)
- Implementation details
- License

Usage

Get token or basic authentication using the auth() method.

`js
const auth = createBasicAuth({
username: "octocat",
password: "secret",
async on2Fa() {
// prompt user for the one-time password retrieved via SMS or authenticator app
return prompt("Two-factor authentication Code:");
},
});

const tokenAuthentication = await auth({
type: "token",
});

const basicAuthentication = await auth({
type: "basic",
});
`

Authenticate request using auth.hook()

`js
const { hook } = createBasicAuth({
username: "octocat",
password: "secret",
async on2Fa() {
// prompt user for the one-time password retrieved via SMS or authenticator app
return prompt("Two-factor authentication Code:");
},
});
const requestWithAuth = request.defaults({ request: { hook } });

const authorizations = await requestWithAuth("GET /authorizations");
`

All strategy options

`js
const auth = createBasicAuth({
username: "octocat",
password: "secret",
async on2Fa() {
return prompt("Two-factor authentication Code:");
},
token: {
note: "octokit 2019-04-03 abc4567",
scopes: [],
noteUrl: "https://github.com/octokit/auth.js#basic-auth",
fingerprint: "abc4567",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
},
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
`

createBasicAuth() options

auth() options

auth() result

There are three possible results that the async auth() method can resolve to

1. A personal access token authentication
auth({type: 'token'}) and basic.token.clientId / basic.token.clientSecret _not_ passed as strategy options.
2. An OAuth access token authentication
auth({type: 'token'}) and basic.token.clientId / basic.token.clientSecret passed as strategy options.
3. Basic authentication
auth({type: 'basic'})

$3

$3

$3

auth.hook(request, route, options) or auth.hook(request, options)

auth.hook() hooks directly into the request life cycle. It authenticates the request using either basic authentication or a token based on the request URL and handles two-factor authentication with request retries.

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

`js
const { data: authorizations } = await auth.hook(
request,
"GET /authorizations"
);
`

Or it can be passed as option to request().

`js
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});

const { data: authorizations } = await requestWithAuth("GET /authorizations");
`

The on2Fa() method passed as strategy option is (re-)called as needed.request() method

Implementation details

GitHub recommends to use basic authentication only for managing personal access tokens. By default, the auth.hook() method implements this best practice and retrieves a personal access token to authenticate requests. All personal access tokens must have a unique note / fingerprint. The auth() method is setting a defaults that are always different to avoid conflicts. But if you set a custom token.note option, fingerprint is not set to a random string by default in order to avoid multiple tokens with the same note.

Some endpoint however do require basic authentication, such as List your authorizations or Delete an authorization. The auth.hook() method is setting the correct authorization automatically based on the request URL.

There is a special case if the user enabled two-factor authentication with SMS as method, because an SMS with the time-based one-time password (TOTP) will only be sent if a request is made to one of these endpoints

- POST /authorizations - Create a new authorization
- PUT /authorizations/clients/:client_id - Get-or-create an authorization for a specific app
- PUT /authorizations/clients/:client_id/:fingerprint - Get-or-create an authorization for a specific app and fingerprint
- PATCH /authorizations/:authorization_id - Update an existing authorization

To guarantee the TOTP delivery via SMS, auth.hook()` is sending an additional request which has no other effect.

License

MIT