oauth2cli

README

oauth2cli

This is a Go package for better user experience with OAuth 2.0 or OpenID Connect (OIDC) on command line interface. It allows simple and easy user interaction with the Authorization Code Grant Flow using a local server.

See GoDoc.

Why

Typical implementation of the OAuth 2.0 Authorization Code Grant requires complicated user interaction, for example:

1. User runs the command on a terminal.
2. User opens the URL shown on the command.
3. User logs in to the provider.
4. User copies the code shown on the browser.
5. User pastes the code on the terminal.
6. User can access to the API using the token.

By using oauth2cli, user interaction becomes simple and easy as follows:

1. User runs the command on a terminal.
2. oauth2cli opens the browser automatically.
3. User logs in to the provider.
4. oauth2cli gets a token from the provider.
5. User can access to the API using the token.

How it works

oauth2cli 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.

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

• type AuthCodeFlow
  • func (f *AuthCodeFlow) GetToken(ctx context.Context) (*oauth2.Token, error)

Examples

• AuthCodeFlow

Types

type AuthCodeFlow

type AuthCodeFlow struct {
	Config          oauth2.Config           // OAuth2 config.
	AuthCodeOptions []oauth2.AuthCodeOption // OAuth2 options.
	LocalServerPort int                     // Local server port. Default to a random port.
	SkipOpenBrowser bool                    // If set, skip opening browser.

	// Called when the local server is started. Default to none.
	ShowLocalServerURL func(url string)

	// Middleware for the local server. Default to none.
	LocalServerMiddleware func(h http.Handler) http.Handler
}

AuthCodeFlow provides the flow with OAuth 2.0 Authorization Code Grant. See https://tools.ietf.org/html/rfc6749#section-4.1

Example

package main

import (
	"context"
	"log"

	"github.com/int128/oauth2cli"
	"golang.org/x/oauth2"
)

var endpoint = oauth2.Endpoint{
	AuthURL:  "https://example.com/oauth2/auth",
	TokenURL: "https://example.com/oauth2/token",
}

func main() {
	ctx := context.Background()
	flow := oauth2cli.AuthCodeFlow{
		Config: oauth2.Config{
			ClientID:     "YOUR_CLIENT_ID",
			ClientSecret: "YOUR_CLIENT_SECRET",
			Endpoint:     endpoint,
			Scopes:       []string{"email"},
		},
	}
	token, err := flow.GetToken(ctx)
	if err != nil {
		log.Fatalf("Could not get a token: %s", err)
	}
	log.Printf("Got a token: %+v", token)
}

func (*AuthCodeFlow) GetToken

func (f *AuthCodeFlow) GetToken(ctx context.Context) (*oauth2.Token, error)

GetToken performs the Authorization Grant Flow and returns a token got from the provider.

This does 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.

Note that this will change Config.RedirectURL to "http://localhost:port" if it is empty.