Repository files navigation

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 theofficial deprecation announcement for more details.

GitHub API Basic authentication for browsers and Node.js

@octokit/auth-basic is implementing one ofGitHub’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) orauth.hook(request, options)
• Implementation details
• License

<scripttype="module">import{createBasicAuth}from"https://cdn.skypack.dev/@octokit/auth-basic";</script>

const{ createBasicAuth}=require("@octokit/auth-basic");// or: import { createBasicAuth } from "@octokit/auth-basic";

Get token or basic authentication using theauth() method.

constauth=createBasicAuth({username:"octocat",password:"secret",asyncon2Fa(){// prompt user for the one-time password retrieved via SMS or authenticator appreturnprompt("Two-factor authentication Code:");},});consttokenAuthentication=awaitauth({type:"token",});constbasicAuthentication=awaitauth({type:"basic",});

Authenticaterequest usingauth.hook()

const{ hook}=createBasicAuth({username:"octocat",password:"secret",asyncon2Fa(){// prompt user for the one-time password retrieved via SMS or authenticator appreturnprompt("Two-factor authentication Code:");},});constrequestWithAuth=request.defaults({request:{ hook}});constauthorizations=awaitrequestWithAuth("GET /authorizations");

All strategy options

constauth=createBasicAuth({username:"octocat",password:"secret",asyncon2Fa(){returnprompt("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",}),});

const{ request}=require("@octokit/request");createAppAuth({clientId:123,clientSecret:"secret",request:request.defaults({baseUrl:"https://ghe.my-company.com/api/v3",}),});

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

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

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.

Therequest option is an instance of@octokit/request. Theroute/options parameters are the same as for therequest() method.

auth.hook() can be called directly to send an authenticated request

const{data:authorizations}=awaitauth.hook(request,"GET /authorizations");

Or it can be passed as option torequest().

constrequestWithAuth=request.defaults({request:{hook:auth.hook,},});const{data:authorizations}=awaitrequestWithAuth("GET /authorizations");

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

GitHub recommends to use basic authentication only for managingpersonal access tokens. By default, theauth.hook() method implements this best practice and retrieves a personal access token to authenticate requests. All personal access tokens must have a uniquenote /fingerprint. Theauth() method is setting a defaults that are always different to avoid conflicts. But if you set a customtoken.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 asList your authorizations orDelete an authorization. Theauth.hook() method is setting the correct authorization automatically based on the request URL.

There is a special case if the user enabledtwo-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.

MIT