webapp

Documentation

Overview

Package webapp implements the OAuth Web Application authorization flow for client applications by starting a server at localhost to receive the web redirect after the user has authorized the application.

Index

• type BrowserParams
• type CodeResponse
• type Flow
  • func InitFlow() (*Flow, error)
  • func (flow *Flow) AccessToken(c httpClient, tokenURL, clientSecret string) (*api.AccessToken, error)
  • func (flow *Flow) BrowserURL(baseURL string, params BrowserParams) (string, error)
  • func (flow *Flow) StartServer(writeSuccess func(io.Writer)) error
  • func (flow *Flow) Wait(ctx context.Context, c httpClient, tokenURL string, opts WaitOptions) (*api.AccessToken, error)
• type WaitOptions

Examples

• InitFlow

Types

type BrowserParams

type BrowserParams struct {
	ClientID    string
	RedirectURI string
	Scopes      []string
	Audience    string
	LoginHandle string
	AllowSignup bool
}

BrowserParams are GET query parameters for initiating the web flow.

type CodeResponse

type CodeResponse struct {
	Code  string
	State string
}

CodeResponse represents the code received by the local server's callback handler.

type Flow

type Flow struct {
	// contains filtered or unexported fields
}

Flow holds the state for the steps of OAuth Web Application flow.

func InitFlow

func InitFlow() (*Flow, error)

InitFlow creates a new Flow instance by detecting a locally available port number.

Example

Initiate the OAuth App Authorization Flow for GitHub.com.

package main

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

	"github.com/cli/browser"
	"github.com/cli/oauth/webapp"
)

func main() {
	clientID := os.Getenv("OAUTH_CLIENT_ID")
	clientSecret := os.Getenv("OAUTH_CLIENT_SECRET")
	callbackURL := "http://127.0.0.1/callback"

	flow, err := webapp.InitFlow()
	if err != nil {
		panic(err)
	}

	params := webapp.BrowserParams{
		ClientID:    clientID,
		RedirectURI: callbackURL,
		Scopes:      []string{"repo", "read:org"},
		AllowSignup: true,
	}
	browserURL, err := flow.BrowserURL("https://github.com/login/oauth/authorize", params)
	if err != nil {
		panic(err)
	}

	// A localhost server on a random available port will receive the web redirect.
	go func() {
		_ = flow.StartServer(nil)
	}()

	// Note: the user's web browser must run on the same device as the running app.
	err = browser.OpenURL(browserURL)
	if err != nil {
		panic(err)
	}

	httpClient := http.DefaultClient
	accessToken, err := flow.Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", webapp.WaitOptions{
		ClientSecret: clientSecret,
	})
	if err != nil {
		panic(err)
	}

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

func (*Flow) AccessToken

func (flow *Flow) AccessToken(c httpClient, tokenURL, clientSecret string) (*api.AccessToken, error)

AccessToken blocks until the browser flow has completed and returns the access token.

Deprecated: use Wait.

func (*Flow) BrowserURL

func (flow *Flow) BrowserURL(baseURL string, params BrowserParams) (string, error)

BrowserURL appends GET query parameters to baseURL and returns the url that the user should navigate to in their web browser.

func (*Flow) StartServer

func (flow *Flow) StartServer(writeSuccess func(io.Writer)) error

StartServer starts the localhost server and blocks until it has received the web redirect. The writeSuccess function can be used to render a HTML page to the user upon completion.

func (*Flow) Wait

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

Wait blocks until the browser flow has completed and returns the access token.

type WaitOptions

type WaitOptions struct {
	// ClientSecret is the app client secret value.
	ClientSecret string
}

WaitOptions specifies parameters to exchange the access token for.