oauth

README

oauth

A library for Go client applications that need to perform OAuth authorization against a server, typically GitHub.com.

Traditionally, OAuth for web applications involves redirecting to a URI after the user authorizes an app. While web apps (and some native client apps) can receive a browser redirect, client apps such as CLI applications do not have such an option.

To accommodate client apps, this library implements the OAuth Device Authorization Grant which GitHub.com now supports. With Device flow, the user is presented with a one-time code that they will have to enter in a web browser while authorizing the app on the server. Device flow is suitable for cases where the web browser may be running on a separate device than the client app itself; for example a CLI application could run within a headless, containerized instance, but the user may complete authorization using a browser on their phone.

To transparently enable OAuth authorization on any GitHub host (e.g. GHES instances without OAuth “Device flow” support), this library also bundles an implementation of OAuth web application flow in which the client app starts a local server at http://127.0.0.1:<port>/ that acts as a receiver for the browser redirect. First, Device flow is attempted, and the localhost server is used as fallback. With the localhost server, the user's web browser must be running on the same machine as the client application itself.

Usage

• OAuth Device flow with fallback
• manual OAuth Device flow
• manual OAuth web application flow

Applications that need more control over the user experience around authentication should directly interface with github.com/cli/oauth/device and github.com/cli/oauth/webapp packages.

In theory, these packages would enable authorization on any OAuth-enabled host. In practice, however, this was only tested for authorizing with GitHub.

Refresh tokens

Set RequestRefreshToken to request an expiring access token and refresh token:

flow := &oauth.Flow{
    Host:                host,
    ClientID:            clientID,
    Scopes:              []string{"repo"},
    RequestRefreshToken: true,
}

requestedAt := time.Now().UTC()
token, err := flow.DetectFlow()
if err != nil {
    return err
}

Servers that do not support expiring tokens may ignore the request and return a token without expiration metadata or a refresh token.

The expiry fields are relative durations. Calculate and persist an absolute expiration time when a token is issued:

expiresAt := time.Time{}
if token.ExpiresIn > 0 {
    expiresAt = requestedAt.Add(token.ExpiresIn)
}
if err := saveToken(token, expiresAt); err != nil {
    return err
}

After loading the token and its persisted expiration time, exchange an expired token's refresh token and persist the returned token pair:

if token.RefreshToken != "" && !expiresAt.IsZero() && !time.Now().Before(expiresAt) {
    requestedAt := time.Now().UTC()
    refreshedToken, err := oauth.Refresh(oauth.RefreshOptions{
        Host:         host,
        ClientID:     clientID,
        ClientSecret: clientSecret,
        RefreshToken: token.RefreshToken,
        HTTPClient:   http.DefaultClient,
    })
    if err != nil {
        return err
    }

    refreshedExpiresAt := time.Time{}
    if refreshedToken.ExpiresIn > 0 {
        refreshedExpiresAt = requestedAt.Add(refreshedToken.ExpiresIn)
    }
    if err := saveToken(refreshedToken, refreshedExpiresAt); err != nil {
        return err
    }

    token = refreshedToken
    expiresAt = refreshedExpiresAt
}

GitHub rotates refresh tokens on every refresh, so always persist the refresh token returned by Refresh. Rotation is optional in OAuth, and when a server omits a new refresh token, Refresh returns the one that was passed in.

Documentation

Overview

Package oauth is a library for Go client applications that need to perform OAuth authorization against a server, typically GitHub.com.

Index

• Variables
• func Refresh(opts RefreshOptions) (*api.AccessToken, error)
• type Flow
  • func (oa *Flow) DetectFlow() (*api.AccessToken, error)
  • func (oa *Flow) DeviceFlow() (*api.AccessToken, error)
  • func (oa *Flow) WebAppFlow() (*api.AccessToken, error)
• type Host
  • func GitHubHost(hostURL string) *Host
  • func NewGitHubHost(hostURL string) (*Host, error)
• type RefreshOptions

Examples

• Flow.DetectFlow
• Refresh

Variables

var ErrRefreshTokenInvalid = errors.New("refresh token is invalid or expired")

ErrRefreshTokenInvalid is returned when the server rejects a refresh token because it is invalid, expired, or already used.

Functions

func Refresh

func Refresh(opts RefreshOptions) (*api.AccessToken, error)

Refresh exchanges a refresh token for a new access token and refresh token. If the server omits a refresh token from the response, the returned token carries the refresh token from opts, since RFC 6749 section 6 allows the server to keep the previous one valid. Applications that require rotation must enforce it themselves.

Example

package main

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

	"github.com/cli/oauth"
)

func main() {
	host, err := oauth.NewGitHubHost("https://github.com")
	if err != nil {
		panic(err)
	}
	flow := &oauth.Flow{
		Host:                host,
		ClientID:            os.Getenv("OAUTH_CLIENT_ID"),
		ClientSecret:        os.Getenv("OAUTH_CLIENT_SECRET"), // only applicable to web app flow
		Scopes:              []string{"repo", "read:org", "gist"},
		RequestRefreshToken: true,
	}

	accessToken, err := flow.DeviceFlow()
	if err != nil {
		panic(err)
	}

	refreshedToken, err := oauth.Refresh(oauth.RefreshOptions{
		Host:         host,
		ClientID:     flow.ClientID,
		ClientSecret: flow.ClientSecret, // only applicable to web app flow
		RefreshToken: accessToken.RefreshToken,
		HTTPClient:   http.DefaultClient,
	})
	if err != nil {
		panic(err)
	}

	// Persist the complete refreshed token because the previous token pair is no longer usable.
	fmt.Printf("Refreshed refresh token: %s\n", refreshedToken.RefreshToken)
	fmt.Printf("Refreshed access token: %s\n", refreshedToken.Token)
}

Types

type Flow

type Flow struct {
	// The hostname to authorize the app with.
	//
	// Deprecated: Use Host instead.
	Hostname string
	// Host configuration to authorize the app with.
	Host *Host
	// OAuth scopes to request from the user.
	Scopes []string
	// OAuth audience to request from the user.
	Audience string
	// OAuth application ID.
	ClientID string
	// OAuth application secret. Only applicable in web application flow.
	ClientSecret string
	// The localhost URI for web application flow callback, e.g. "http://127.0.0.1/callback".
	CallbackURI string
	// RequestRefreshToken opts this authorization into receiving an expiring access token and a
	// refresh token by requesting the "offline_access" scope.
	//
	// Servers that do not support expiring tokens may ignore this request and return a token that
	// does not expire and has no refresh token.
	RequestRefreshToken bool

	// Display a one-time code to the user. Receives the code and the browser URL as arguments. Defaults to printing the
	// code to the user on Stdout with instructions to copy the code and to press Enter to continue in their browser.
	DisplayCode func(string, string) error
	// Open a web browser at a URL. Defaults to opening the default system browser.
	BrowseURL func(string) error
	// Render an HTML page to the user upon completion of web application flow. The default is to
	// render a simple message that informs the user they can close the browser tab and return to the app.
	WriteSuccessHTML func(io.Writer)

	// The HTTP client to use for API POST requests. Defaults to http.DefaultClient.
	HTTPClient httpClient
	// The stream to listen to keyboard input on. Defaults to os.Stdin.
	Stdin io.Reader
	// The stream to print UI messages to. Defaults to os.Stdout.
	Stdout io.Writer
}

Flow facilitates a single OAuth authorization flow.

func (*Flow) DetectFlow

func (oa *Flow) DetectFlow() (*api.AccessToken, error)

DetectFlow tries to perform Device flow first and falls back to Web application flow.

Example

DetectFlow attempts to initiate OAuth Device flow with the server and falls back to OAuth Web application flow if Device flow seems unsupported. This approach isn't strictly needed for github.com, as its Device flow support is globally available, but it enables logging in to self-hosted GitHub instances as well.

package main

import (
	"fmt"
	"os"

	"github.com/cli/oauth"
)

func main() {
	host, err := oauth.NewGitHubHost("https://github.com")
	if err != nil {
		panic(err)
	}
	flow := &oauth.Flow{
		Host:         host,
		ClientID:     os.Getenv("OAUTH_CLIENT_ID"),
		ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"), // only applicable to web app flow
		CallbackURI:  "http://127.0.0.1/callback",      // only applicable to web app flow
		Scopes:       []string{"repo", "read:org", "gist"},
	}

	accessToken, err := flow.DetectFlow()
	if err != nil {
		panic(err)
	}

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

func (*Flow) DeviceFlow

func (oa *Flow) DeviceFlow() (*api.AccessToken, error)

DeviceFlow captures the full OAuth Device flow, including prompting the user to copy a one-time code and opening their web browser, and returns an access token upon completion.

func (*Flow) WebAppFlow

func (oa *Flow) WebAppFlow() (*api.AccessToken, error)

WebAppFlow starts a local HTTP server, opens the web browser to initiate the OAuth Web application flow, blocks until the user completes authorization and is redirected back, and returns the access token.

type Host

type Host struct {
	DeviceCodeURL string
	AuthorizeURL  string
	TokenURL      string
}

Host defines the endpoints used to authorize against an OAuth server.

func GitHubHost

func GitHubHost(hostURL string) *Host

GitHubHost constructs a Host from the given URL to a GitHub instance.

Deprecated: `GitHubHost` can panic with a malformed `hostURL`. Use `NewGitHubHost` instead for graceful error handling.

func NewGitHubHost

func NewGitHubHost(hostURL string) (*Host, error)

NewGitHubHost constructs a Host from the given URL to a GitHub instance.

type RefreshOptions

type RefreshOptions struct {
	// Host contains the token endpoint used for the refresh request.
	Host *Host
	// ClientID is the OAuth application ID.
	ClientID string
	// ClientSecret is the OAuth application secret. It is not required for device flow tokens.
	ClientSecret string
	// RefreshToken is the refresh token issued with the current access token.
	RefreshToken string
	// HTTPClient is the client used for the refresh request. It defaults to http.DefaultClient.
	HTTPClient httpClient
}

RefreshOptions specifies parameters for exchanging a refresh token for a new token pair.