oauth2cli

README

oauth2cli

This is a Go package for OAuth 2.0 authorization in a command line interface (CLI) tool. You can create a CLI tool with the simple authorization flow for better UX.

Take a look at the screencast of the example application.

Purpose

When we create a CLI tool which accesses an API with OAuth, it needs the complicated flow such as copy/paste of a URL and code, as follows:

1. User runs the command.
2. Command shows the URL for authorization.
3. User opens the browser, logs in to the server and approves the authorization.
4. Server shows an authorization code.
5. User copies the code and pastes into the command.
6. Command accesses the API with the token.

You can make it simple by using oauth2cli as follows:

1. User runs the command.
2. Command opens the browser.
3. User logs in to the server and approves the authorization.
4. Command gets a token and access the API with the token.

How it works

oauth2cli starts the local server and initiates the flow of OAuth 2.0 Authorization Code Grant.

Take a look at the sequence diagram:

Contributions

This is an open source software licensed under Apache 2.0. Feel free to open issues and pull requests.

Documentation

Overview

Package oauth2cli provides better user experience on OAuth 2.0 and OpenID Connect (OIDC) on CLI. It allows simple and easy user interaction with Authorization Code Grant Flow and a local server.

Index

• Constants
• func GetToken(ctx context.Context, c Config) (*oauth2.Token, error)
• type Config

Constants

const DefaultLocalServerSuccessHTML = `` /* 474-byte string literal not displayed */

DefaultLocalServerSuccessHTML is a default response body on authorization success.

Functions

func GetToken

func GetToken(ctx context.Context, c Config) (*oauth2.Token, error)

GetToken performs the Authorization Code Grant Flow and returns a token received from the provider. See https://tools.ietf.org/html/rfc6749#section-4.1

This performs the following steps:

1. Start a local server at the port.
2. Open a browser and navigate it to the local server.
3. Wait for the user authorization.
4. Receive a code via an authorization response (HTTP redirect).
5. Exchange the code and a token.
6. Return the code.

Types

type Config

type Config struct {
	// OAuth2 config.
	// RedirectURL will be automatically set to the local server.
	OAuth2Config oauth2.Config
	// Hostname of the redirect URL.
	// You can set this if your provider does not accept localhost.
	// Default to localhost.
	RedirectURLHostname string
	// Options for an authorization request.
	// You can set oauth2.AccessTypeOffline and the PKCE options here.
	AuthCodeOptions []oauth2.AuthCodeOption
	// Options for a token request.
	// You can set the PKCE options here.
	TokenRequestOptions []oauth2.AuthCodeOption
	// State parameter in the authorization request.
	// Default to a string of random 32 bytes.
	State string

	// Candidates of hostname and port which the local server binds to.
	// You can set port number to 0 to allocate a free port.
	// If multiple addresses are given, it will try the ports in order.
	// If nil or an empty slice is given, it defaults to "127.0.0.1:0" i.e. a free port.
	LocalServerBindAddress []string

	// A PEM-encoded certificate, and possibly the complete certificate chain.
	// When set, the server will serve TLS traffic using the specified
	// certificates. It's recommended that the public key's SANs contain
	// the loopback addresses - 'localhost', '127.0.0.1' and '::1'
	LocalServerCertFile string
	// A PEM-encoded private key for the certificate.
	// This is required when LocalServerCertFile is set.
	LocalServerKeyFile string

	// Response HTML body on authorization completed.
	// Default to DefaultLocalServerSuccessHTML.
	LocalServerSuccessHTML string
	// Middleware for the local server. Default to none.
	LocalServerMiddleware func(h http.Handler) http.Handler
	// A channel to send its URL when the local server is ready. Default to none.
	LocalServerReadyChan chan<- string

	// Logger function for debug.
	Logf func(format string, args ...interface{})

	// DEPRECATED: this will be removed in the future release.
	// Use LocalServerBindAddress instead.
	// Address which the local server binds to.
	// Default to "127.0.0.1".
	LocalServerAddress string
	// DEPRECATED: this will be removed in the future release.
	// Use LocalServerBindAddress instead.
	// Candidates of a port which the local server binds to.
	// If nil or an empty slice is given, LocalServerAddress is ignored and allocate a free port.
	// If multiple ports are given, they are appended to LocalServerBindAddress.
	LocalServerPort []int
}

Config represents a config for GetToken.