oauth2cli

README

oauth2cli

A Go library for 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.

See GoDoc.

TL;DR

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)
}

Why

Typical OAuth 2.0 Authorization Code Grant implementation 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 will be 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 browser and navigate to the local server.
3. Wait for 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 // Options passed to AuthCodeURL().
	LocalServerPort int                     // Local server port. Default to a random port.
	SkipOpenBrowser bool                    // Skip opening browser if it is true.

	ShowLocalServerURL func(url string) // Called when the local server is started. Default to show a message via the logger.
}

AuthCodeFlow provides 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 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 browser and navigate to the local server. 3. Wait for 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.