Basic authentication for browsers and Node.js
@octokit/auth-basic is implementing one of GitHub’s authentication strategies.
Authenticating using username and password.
GitHub recommends to use basic authentication only for managing personal access tokens. Other endpoints won’t even work if a user enabled two-factor authentication ith 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 authorizationPUT /authorizations/clients/:client_id- Get-or-create an authorization for a specific appPUT /authorizations/clients/:client_id/:fingerprint- Get-or-create an authorization for a specific app and fingerprintPATCH /authorizations/:authorization_id- Update an existing authorizationDELETE /authorizations/:authorization_id- Delete an authorization
By default, @octokit/auth implements this best practice and retrieves a personal access token.
Some endpoint however do require basic authentication, such as List your authorizations or Delete an authorization. In order to retrieve the right authentication for the right endpoint, you can pass an optional url parameter to auth().
Minimal
import { createBasicAuth } from "@octokit/auth";
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 authentication = await auth();All strategy options
import { createBasicAuth } from "@octokit/auth";
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"
}
});Retrieve basic authentication
const authentication = await auth({ url: "/authorizations/:authorization_id" });| name | type | description |
|---|---|---|
username
|
string
|
Required. Username of the account to login with. |
password
|
string
|
Required. Password of the account to login with. |
on2Fa
|
function
|
Required. If the user has two-factor authentication (2FA) enabled, the on2Fa method will be called and expected to return a time-based one-time password (TOTP) which the user retrieves either via SMS or an authenticator app, based on their account settings. You can pass an empty function if you are certain the account has 2FA disabled.Alias: on2fa
|
token
|
object
|
An object matching "Create a new authorization" parameters, but camelCased. |
token.note
|
string
|
A note to remind you what the OAuth token is for. Personal access tokens must have a unique note. Attempting to create a token with with an existing note results in a 409 conflict error.Defaults to "octokit <timestamp> <fingerprint>", where <timestamp> has the format YYYY-MM-DD and <fingerprint> is a random string. Example: "octokit 2019-04-03 abc4567".
|
token.scopes
|
array of strings
|
A list of scopes that this authorization is in. See available scopes Defaults to an empty array |
token.noteUrl
|
string
|
A URL to remind you what app the OAuth token is for. Defaults to "https://github.com/octokit/auth.js#basic-auth" |
token.fingerprint
|
string
|
A unique string to distinguish an authorization from others created for the same client ID and user. Defaults to a random string |
token.clientId
|
string
|
The 20 character OAuth app client key for which to create the token. |
token.clientSecret
|
string
|
The 40 character OAuth app client secret for which to create the token. Note: do not share an OAuth app’s client secret with an untrusted client such as a website or native app. |
| name | type | description |
|---|---|---|
url
|
string
|
An absolute URL or endpoint route path. Examples
|
refresh
|
boolean
|
Information for a personal access token is retrieved from GET /user and cached for subsequent requests. To bypass and update cache, set refresh to true.Defaults to false.
|
There are three possible results
- A personal access token authentication
❌urlparameter does not match and endpoint requiring basic authentication
❌basic.token.clientId/basic.token.clientSecretnot passed as strategy options. - An oauth access token authentication
❌urlparameter does not match and endpoint requiring basic authentication
✅basic.token.clientId/basic.token.clientSecretpassed as strategy options. - Basic authentication
✅urlparameter matches and endpoint requiring basic authentication.
| name | type | description |
|---|---|---|
type
|
string
|
"token"
|
token
|
string
|
The personal access token |
user
|
object
|
{ login, id } - username and database id
|
scopes
|
array of strings
|
array of scope names |
headers
|
object
|
{ authorization } - value for the "Authorization" header.
|
query
|
object
|
{} - not used
|
| name | type | description |
|---|---|---|
type
|
string
|
"token"
|
token
|
string
|
The oauth access token |
user
|
object
|
{ login } - username
|
scopes
|
array of strings
|
array of scope names |
headers
|
object
|
{ authorization } - value for the "Authorization" header.
|
query
|
object
|
{} - not used
|
| name | type | description |
|---|---|---|
type
|
string
|
"basic"
|
username
|
string
|
The decoded username |
password
|
string
|
The decoded password |
user
|
object
|
{ login, id } - username and database id
|
headers
|
object
|
{ authorization } - value for the "Authorization" header.
|
query
|
object
|
{} - not used
|