Giter VIP home page Giter VIP logo

auth.js's Introduction

auth.js

GitHub API authentication library for browsers and Node.js

@latest Build Status

GitHub supports 4 authentication strategies. They are all implemented in @octokit/auth.

Example usage

Browsers

Load @octokit/auth directly from cdn.pika.dev

<script type="module">
  import {
    createBasicAuth,
    createAppAuth,
    createOAuthAppAuth,
    createTokenAuth,
  } from "https://cdn.pika.dev/@octokit/auth";
</script>
Node

Install with npm install @octokit/auth

const {
  createBasicAuth,
  createAppAuth,
  createOAuthAppAuth,
  createTokenAuth,
  createActionAuth,
} = require("@octokit/auth");
// or:
// import {
//   createBasicAuth,
//   createAppAuth,
//   createOAuthAppAuth,
//   createTokenAuth,
//   createActionAuth
// } from "@octokit/auth";
 
const auth = createBasicAuth({
  username: "monatheoctocat",
  password: "secret",
  on2Fa() {
    return prompt("Two-factor authentication Code:");
  },
});

Each function exported by @octokit/auth returns an async auth function.

The auth function resolves with an authentication object. If multiple authentication types are supported, a type parameter can be passed.

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

Additionally, auth.hook() can be used to directly hook into @octokit/request. If multiple authentication types are supported, the right authentication type will be applied automatically based on the request URL.

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

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

Official Strategies

Comparison

Module Strategy Options Auth Options Authentication objects

@octokit/auth-token

 
token

-

{
  type: "token",
  token: "secret123",
  tokenType, "oauth" // or "installation"
}

@octokit/auth-basic

 
{
  username*,
  password*,
  on2Fa*,
  token,
  request
}

{
  type*, // "basic" or "token"
  refresh
}

{
  type: "basic"
  username: "octocat",
  password: "secret",
  credentials: "b2N0b2NhdDpzZWNyZXQ=",
  totp: "123456"
}

{
  type: "token"
  tokenType: "pat",
  token: "secret123",
  id: 123,
  username: "octocat",
  scopes: []
}

{
  type: "token"
  tokenType: "oauth",
  token: "secret123",
  id: 123,
  appClientId: "abc123",
  username: "octocat",
  scopes: []
}

@octokit/auth-app

 
{
  id*,
  privateKey*,
  installationId,
  cache,
  request
}

{
  type*, // "app" or "installation"
  installationId,
  repositoryIds,
  permissions,
  refresh
}

{
  type: "app",
  token: "abc.def.1234",
  appId: 123,
  expiresAt: "2019-06-11T22:22:34Z"
}

{
  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'
}

@octokit/auth-oauth-app

 
{
  clientId*,
  clientSecret*,
  code,
  redirectUrl,
  state,
  request
}

{
  type*, // "oauth-app" or "token"
  url
}

{
  type: "oauth-app",
  clientId: "abc123",
  clientSecret: "abc123secret",
  headers: {},
  query: {
    clientId: "abc123",
    clientSecret: "abc123secret"
  }
}

{
  type: "token",
  tokenType: "oauth",
  token: "123secret",
  scopes: []
}

@octokit/auth-action

 
-

-

{
  type: "token",
  tokenType: "installation",
  token: "v1.123secret"
}

Token authentication

Example

const auth = createTokenAuth("1234567890abcdef1234567890abcdef12345678");
const { token, tokenType } = await auth();

See @octokit/auth-token for more details.

Basic and personal access token authentication

Example

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 { token } = await auth();
const { totp } = await auth({
  type: "basic",
});

See @octokit/auth-basic for more details.

GitHub App or installation authentication

Example

const auth = createAppAuth({
  id: 1,
  privateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
});

const appAuthentication = await auth({ type: "auth" });
const installationAuthentication = await auth({
  type: "installation",
  installationId: 123,
});

See @octokit/auth-app for more details.

OAuth app and OAuth access token authentication

Example

const auth = createOAuthAppAuth({
  clientId: "1234567890abcdef1234",
  clientSecret: "1234567890abcdef1234567890abcdef12345678",
  code: "random123", // code from OAuth web flow, see https://git.io/fhd1D
});

const appAuthentication = await auth({
  type: "oauth-app",
  url: "/orgs/:org/repos",
});
const tokenAuthentication = await auth({ type: "token" });

See @octokit/auth-oauth-app for more details.

GitHub Action authentication

Example

// expects process.env.GITHUB_ACTION and process.env.GITHUB_TOKEN to be set
const auth = createActionAuth();
const { token } = await auth();

See @octokit/auth-action for more details.

Community Strategies

.netrc authentication

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.

License

MIT

auth.js's People

Contributors

dependabot[bot] avatar gr2m avatar greenkeeper[bot] avatar toc-me[bot] avatar jovel avatar bishopb avatar travi avatar mdelagrange avatar

Watchers

James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.