Nothing Particularly Magnificent

    @octokit/auth-oauth-user
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    auth-oauth-user.js

    Octokit authentication strategy for OAuth user authentication

    @latest Build Status

    Important: @octokit/auth-oauth-user requires your app's client_secret, which must not be exposed. If you are looking for an OAuth user authentication strategy that can be used on a client (browser, IoT, CLI), check out @octokit/auth-oauth-user-client. Note that @octokit/auth-oauth-user-client requires a backend. The only exception is @octokit/auth-oauth-device which does not require the client_secret, but does not work in browsers due to CORS constraints.

    Table of contents

    Features

    Standalone usage

    Browsers

    Load @octokit/auth-oauth-user directly from cdn.skypack.dev

    <script type="module">
      import { createOAuthUserAuth } from "https://cdn.skypack.dev/@octokit/auth-oauth-user";
    </script>

    Node

    Install with npm install @octokit/auth-oauth-user

    const { createOAuthUserAuth } = require("@octokit/auth-oauth-user");

    Exchange code from OAuth web flow

    const auth = createOAuthUserAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      code: "code123",
      // optional
      state: "state123",
      redirectUrl: "https://acme-inc.com/login",
    });
    
    // Exchanges the code for the user access token authentication on first call
    // and caches the authentication for successive calls
    const { token } = await auth();

    About GitHub's OAuth web flow

    OAuth Device flow

    const auth = createOAuthUserAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      onVerification(verification) {
        // verification example
        // {
        //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
        //   user_code: "WDJB-MJHT",
        //   verification_uri: "https://github.com/login/device",
        //   expires_in: 900,
        //   interval: 5,
        // };
    
        console.log("Open %s", verification.verification_uri);
        console.log("Enter code: %s", verification.user_code);
      },
    });
    
    // resolves once the user entered the `user_code` on `verification_uri`
    const { token } = await auth();

    About GitHub's OAuth device flow

    Use an existing authentication

    const auth = createOAuthUserAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      clientType: "oauth-app",
      token: "token123",
    });
    
    // will return the passed authentication
    const { token } = await auth();

    See Authentication object.

    Usage with Octokit

    Browsers

    @octokit/auth-oauth-user cannot be used in the browser. It requires clientSecret to be set which must not be exposed to clients, and some of the OAuth APIs it uses do not support CORS.

    Node

    Install with npm install @octokit/core @octokit/auth-oauth-user. Optionally replace @octokit/core with a compatible module

    const { Octokit } = require("@octokit/core");
    const { createOAuthUserAuth } = require("@octokit/auth-oauth-user");
    const octokit = new Octokit({
      authStrategy: createOAuthUserAuth,
      auth: {
        clientId: "1234567890abcdef1234",
        clientSecret: "1234567890abcdef1234567890abcdef12345678",
        code: "code123",
      },
    });
    
    // Exchanges the code for the user access token authentication on first request
    // and caches the authentication for successive requests
    const {
      data: { login },
    } = await octokit.request("GET /user");
    console.log("Hello, %s!", login);

    createOAuthUserAuth(options) or new Octokit({ auth })

    The createOAuthUserAuth method accepts a single options object as argument. The same set of options can be passed as auth to the Octokit constructor when setting authStrategy: createOAuthUserAuth

    When using GitHub's OAuth web flow

    name type description
    clientId string Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
    clientSecret string Required. Client Secret for your GitHub/OAuth App. Create one on your app's settings page.
    clientType string Either "oauth-app" or "github-app". Defaults to "oauth-app".
    code string

    Required. The authorization code which was passed as query parameter to the callback URL from GitHub's OAuth web application flow.

    state string

    The unguessable random string you provided in Step 1 of GitHub's OAuth web application flow.

    redirectUrl string

    The redirect_uri parameter you provided in Step 1 of GitHub's OAuth web application flow.

    request function You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
    const { request } = require("@octokit/request");
    createOAuthAppAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      request: request.defaults({
        baseUrl: "https://ghe.my-company.com/api/v3",
      }),
    });

    When using GitHub's OAuth device flow

    name type description
    clientId string Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
    clientSecret string Required. Client Secret for your GitHub/OAuth App. The clientSecret is not needed for the OAuth device flow itself, but it is required for resetting, refreshing, and invalidating a token. Find the Client Secret on your app's settings page.
    clientType string Either "oauth-app" or "github-app". Defaults to "oauth-app".
    onVerification function

    Required. A function that is called once the device and user codes were retrieved

    The onVerification() callback can be used to pause until the user completes step 2, which might result in a better user experience.

    const auth = createOAuthUserAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      onVerification(verification) {
        console.log("Open %s", verification.verification_uri);
        console.log("Enter code: %s", verification.user_code);
    
        await prompt("press enter when you are ready to continue");
      },
    });
    request function You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
    const { request } = require("@octokit/request");
    createOAuthAppAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      onVerification(verification) {
        console.log("Open %s", verification.verification_uri);
        console.log("Enter code: %s", verification.user_code);
    
        await prompt("press enter when you are ready to continue");
      },
      request: request.defaults({
        baseUrl: "https://ghe.my-company.com/api/v3",
      }),
    });

    When passing an existing authentication object

    name type description
    clientType string Required. Either "oauth-app" or "github".
    clientId string Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
    clientSecret string Required. Client Secret for your GitHub/OAuth App. Create one on your app's settings page.
    token string Required. The user access token
    scopes array of strings Required if clientType is set to "oauth-app". Array of OAuth scope names the token was granted
    refreshToken string Only relevant if clientType is set to "github-app" and token expiration is enabled.
    expiresAt string Only relevant if clientType is set to "github-app" and token expiration is enabled. Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
    refreshTokenExpiresAt string Only relevant if clientType is set to "github-app" and token expiration is enabled. Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z
    request function You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
    const { request } = require("@octokit/request");
    createOAuthAppAuth({
      clientId: "1234567890abcdef1234",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
      request: request.defaults({
        baseUrl: "https://ghe.my-company.com/api/v3",
      }),
    });

    auth(options) or octokit.auth(options)

    The async auth() method is returned by createOAuthUserAuth(options) or set on the octokit instance when the Octokit constructor was called with authStrategy: createOAuthUserAuth.

    Once auth() receives a valid authentication object it caches it in memory and uses it for subsequent calls. It also caches if the token is invalid and no longer tries to send any requests. If the authentication is using a refresh token, a new token will be requested as needed. Calling auth({ type: "reset" }) will replace the internally cached authentication.

    Resolves with an authentication object.

    name type description
    type string

    Without setting type auth will return the current authentication object, or exchange the code from the strategy options on first call. If the current authentication token is expired, the tokens will be refreshed.

    Possible values for type are

    • "get": returns the token from internal state and creates it if none was created yet
    • "check": sends request to verify the validity of the current token
    • "reset": invalidates current token and replaces it with a new one
    • "refresh": GitHub Apps only, and only if expiring user tokens are enabled.
    • "delete": invalidates current token
    • "deleteAuthorization": revokes OAuth access for application. All tokens for the current user created by the same app are invalidated. The user will be prompted to grant access again during the next OAuth web flow.

    Authentication object

    There are three possible results

    1. OAuth APP authentication token
    2. GitHub APP user authentication token with expiring disabled
    3. GitHub APP user authentication token with expiring enabled

    The differences are

    1. scopes is only present for OAuth Apps
    2. refreshToken, expiresAt, refreshTokenExpiresAt are only present for GitHub Apps, and only if token expiration is enabled

    OAuth APP authentication token

    name type description
    type string "token"
    tokenType string "oauth"
    clientType string "oauth-app"
    clientId string The clientId from the strategy options
    clientSecret string The clientSecret from the strategy options
    token string The user access token
    scopes array of strings array of scope names enabled for the token
    invalid boolean

    Either undefined or true. Will be set to true if the token was invalided explicitly or found to be invalid

    GitHub APP user authentication token with expiring disabled

    name type description
    type string "token"
    tokenType string "oauth"
    clientType string "github-app"
    clientId string The clientId from the strategy options
    clientSecret string The clientSecret from the strategy options
    token string The user access token
    invalid boolean

    Either undefined or true. Will be set to true if the token was invalided explicitly or found to be invalid

    GitHub APP user authentication token with expiring enabled

    name type description
    type string "token"
    tokenType string "oauth"
    clientType string "github-app"
    clientId string The clientId from the strategy options
    clientSecret string The clientSecret from the strategy options
    token string The user access token
    refreshToken string The refresh token
    expiresAt string Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
    refreshTokenExpiresAt string Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z
    invalid boolean

    Either undefined or true. Will be set to true if the token was invalided explicitly or found to be invalid

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

    auth.hook() hooks directly into the request life cycle. It amends the request to authenticate correctly based on the request URL.

    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

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

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

    const requestWithAuth = request.defaults({
      request: {
        hook: auth.hook,
      },
    });
    
    const { data: user } = await requestWithAuth("GET /user");

    Types

    import {
      GitHubAppAuthentication,
      GitHubAppAuthenticationWithExpiration,
      GitHubAppAuthOptions,
      GitHubAppStrategyOptions,
      GitHubAppStrategyOptionsDeviceFlow,
      GitHubAppStrategyOptionsExistingAuthentication,
      GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
      GitHubAppStrategyOptionsWebFlow,
      OAuthAppAuthentication,
      OAuthAppAuthOptions,
      OAuthAppStrategyOptions,
      OAuthAppStrategyOptionsDeviceFlow,
      OAuthAppStrategyOptionsExistingAuthentication,
      OAuthAppStrategyOptionsWebFlow,
    } from "@octokit/auth-oauth-user";

    Contributing

    See CONTRIBUTING.md

    License

    MIT

    Install

    npm i @octokit/auth-oauth-user

    DownloadsWeekly Downloads

    250,997

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    95.5 kB

    Total Files

    21

    Last publish

    Collaborators

    • gr2m
    • octokitbot