device

Documentation

Overview

Package device facilitates performing OAuth Device Authorization Flow for client applications such as CLIs that can not receive redirects from a web site.

First, RequestCode should be used to obtain a CodeResponse.

Next, the user will need to navigate to VerificationURI in their web browser on any device and fill in the UserCode.

While the user is completing the web flow, the application should invoke PollToken, which blocks the goroutine until the user has authorized the app on the server.

https://docs.github.com/en/free-pro-team@latest/developers/apps/authorizing-oauth-apps#device-flow

Index

• Variables
• func PollToken(c httpClient, pollURL string, clientID string, code *CodeResponse) (*api.AccessToken, error)
• func Wait(ctx context.Context, c httpClient, uri string, opts WaitOptions) (*api.AccessToken, error)
• type CodeResponse
  • func RequestCode(c httpClient, uri string, clientID string, scopes []string) (*CodeResponse, error)
• type WaitOptions

Examples

• RequestCode

Variables

var (
	// ErrUnsupported is thrown when the server does not implement Device flow.
	ErrUnsupported = errors.New("device flow not supported")
	// ErrTimeout is thrown when polling the server for the granted token has timed out.
	ErrTimeout = errors.New("authentication timed out")
)

Functions

func PollToken

func PollToken(c httpClient, pollURL string, clientID string, code *CodeResponse) (*api.AccessToken, error)

PollToken polls the server at pollURL until an access token is granted or denied.

Deprecated: use Wait.

func Wait

func Wait(ctx context.Context, c httpClient, uri string, opts WaitOptions) (*api.AccessToken, error)

Wait polls the server at uri until authorization completes.

Types

type CodeResponse

type CodeResponse struct {
	// The user verification code is displayed on the device so the user can enter the code in a browser.
	UserCode string
	// The verification URL where users need to enter the UserCode.
	VerificationURI string
	// The optional verification URL that includes the UserCode.
	VerificationURIComplete string

	// The device verification code is 40 characters and used to verify the device.
	DeviceCode string
	// The number of seconds before the DeviceCode and UserCode expire.
	ExpiresIn int
	// The minimum number of seconds that must pass before you can make a new access token request to
	// complete the device authorization.
	Interval int
}

CodeResponse holds information about the authorization-in-progress.

func RequestCode

func RequestCode(c httpClient, uri string, clientID string, scopes []string) (*CodeResponse, error)

RequestCode initiates the authorization flow by requesting a code from uri.

Example

This demonstrates how to perform OAuth Device Authorization Flow for GitHub.com. After RequestCode successfully completes, the client app should prompt the user to copy the UserCode and to open VerificationURI in their web browser to enter the code.

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

	"github.com/cli/oauth/device"
)

func main() {
	clientID := os.Getenv("OAUTH_CLIENT_ID")
	scopes := []string{"repo", "read:org"}
	httpClient := http.DefaultClient

	code, err := device.RequestCode(httpClient, "https://github.com/login/device/code", clientID, scopes)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Copy code: %s\n", code.UserCode)
	fmt.Printf("then open: %s\n", code.VerificationURI)

	accessToken, err := device.Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", device.WaitOptions{
		ClientID:   clientID,
		DeviceCode: code,
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Access token: %s\n", accessToken.Token)
}

type WaitOptions

type WaitOptions struct {
	// ClientID is the app client ID value.
	ClientID string
	// ClientSecret is the app client secret value. Optional: only pass if the server requires it.
	ClientSecret string
	// DeviceCode is the value obtained from RequestCode.
	DeviceCode *CodeResponse
	// GrantType overrides the default value specified by OAuth 2.0 Device Code. Optional.
	GrantType string
	// contains filtered or unexported fields
}

WaitOptions specifies parameters to poll the server with until authentication completes.