oauth2

README

oauth2go

What is this?

oauth2go aims to be a basic OAuth 2.0 authorization server that implements at least some of the most basic OAuth 2.0 flows. Since the canonical import name for this package is oauth2, it also provides type aliases for exported structs and interfaces of the golang.org/x/oauth2 package, so that both OAuth 2.0 client and server structs can be accessed using an oauth2 package. Additional structs for specialized client flows or endpoints still need to be retrieved from the corresponding sub-package, such as golang.org/x/oauth2/clientcredentials.

In it's bare form, this package only contains an authorization server, which does not have any "users" or any possibility to "log in", as this is the duty of an authentication server. However, for convenience, the login package includes a very basic authentication server which implements a POST form based /login endpoint and a simple login form located in login/login.html.

Why?

This project mainly started out of the need to have a very small, embedded OAuth 2.0 authorization server, written in Go. The main use case was a "demo" or all-in-one-mode of a large micro-service application, as well as integration testing. In production deployments, this application uses a dedicated authentication server, but I wanted something for my "demo" mode. While there are some implementations out there, it was not easy to fulfill my requirements.

I wanted something small, lean and easily embedded in my Go code, not a full-blown authentication services with thousands of adapters and backends (written in Java).

I wanted something that intentionally does not support legacy flows but focuses on the newer RFCs and possibly move into the direction of OAuth 2.1.

I wanted something with zero (or almost) zero dependencies. Therefore I strictly try to only include the following dependencies: golang.org/x/oauth2, golang.org/x/crypto (which hopefully might be part of the standard library one day) and github.com/golang-jwt/jwt (which itself also has a zero dependency policy)

How to use?

A very simple OAuth 2.0 authorization server with an integrated authentication ("login") server can be created like this.

import (
    oauth2 "github.com/oxisto/oauth2go"
    "github.com/oxisto/oauth2go/login"
)

func main() {
    var srv *oauth2.AuthorizationServer

    srv = oauth2.NewServer(":8080",
        login.WithLoginPage(login.WithUser("admin", "admin")),
    )

    srv.ListenAndServe()
}

If you want to use this project as a small standalone authentication server, you can use the Docker image to spawn one. The created user and client credentials will be printed on the console.

docker run -p 8080:8080 ghcr.io/oxisto/oauth2go

A login form is available on http://localhost:8008/login.

(To be) Implemented Standards

• RFC 6749. The basics
• RFC 6750. We are exclusively using JWTs as bearer tokens
• RFC 7517. JSON Web Key

Documentation

Index

• Constants
• Variables
• func Error(w http.ResponseWriter, error string, statusCode int)
• func GenerateSecret() string
• func RedirectError(w http.ResponseWriter, r *http.Request, redirectURI string, error string)
• type AuthCodeOption
• type AuthStyle
• type AuthorizationServer
  • func NewServer(addr string, opts ...AuthorizationServerOption) *AuthorizationServer
  • func (srv *AuthorizationServer) GetClient(clientID string) (*Client, error)
  • func (srv *AuthorizationServer) IssueCode() (code string)
  • func (srv *AuthorizationServer) PublicKeys() []*ecdsa.PublicKey
  • func (srv *AuthorizationServer) ValidateCode(code string) bool
• type AuthorizationServerOption
  • func WithClient(clientID string, clientSecret string, redirectURI string) AuthorizationServerOption
• type Client
• type CodeIssuer
• type Config
• type Endpoint
• type JSONWebKey
• type JSONWebKeySet
• type Logger
• type RetrieveError
• type Token
• type TokenSource
• type Transport

Examples

• AuthorizationServer

Constants

const (
	ErrorInvalidClient = "invalid_client"
	ErrorInvalidGrant  = "invalid_grant"
)

Variables

var (
	ErrClientNotFound             = errors.New("client not found")
	ErrInvalidBasicAuthentication = errors.New("invalid or missing basic authentication")
)

Functions

func Error

func Error(w http.ResponseWriter, error string, statusCode int)

func GenerateSecret

func GenerateSecret() string

func RedirectError

func RedirectError(w http.ResponseWriter, r *http.Request, redirectURI string, error string)

Types

type AuthCodeOption

type AuthCodeOption = oauth2.AuthCodeOption

AuthCodeOption is a type alias for https://pkg.go.dev/golang.org/x/oauth2#AuthCodeOption.

type AuthStyle

type AuthStyle = oauth2.AuthStyle

AuthStyle is a type alias for https://pkg.go.dev/golang.org/x/oauth2#AuthStyle.

type AuthorizationServer

type AuthorizationServer struct {
	http.Server
	// contains filtered or unexported fields
}

AuthorizationServer is an OAuth 2.0 authorization server

Example

ExampleLoginPage sets up an OAuth 2.0 authorization server with an integrated login page (acting as an authentication server).

package main

import (
	"fmt"

	oauth2 "github.com/oxisto/oauth2go"
	"github.com/oxisto/oauth2go/login"
)

func main() {
	var srv *oauth2.AuthorizationServer
	var port = 8080

	srv = oauth2.NewServer(fmt.Sprintf(":%d", port),
		login.WithLoginPage(login.WithUser("admin", "admin")),
	)

	fmt.Printf("Creating new OAuth 2.0 server on %d", port)

	go srv.ListenAndServe()
	defer srv.Close()
}

Output:

Creating new OAuth 2.0 server on 8080

func NewServer

func NewServer(addr string, opts ...AuthorizationServerOption) *AuthorizationServer

func (*AuthorizationServer) GetClient

func (srv *AuthorizationServer) GetClient(clientID string) (*Client, error)

GetClient returns the client for the given ID or ErrClientNotFound.

func (*AuthorizationServer) IssueCode

func (srv *AuthorizationServer) IssueCode() (code string)

IssueCode implements CodeIssuer.

func (*AuthorizationServer) PublicKeys

func (srv *AuthorizationServer) PublicKeys() []*ecdsa.PublicKey

PublicKey returns the public keys of the signing key of this authorization server.

func (*AuthorizationServer) ValidateCode

func (srv *AuthorizationServer) ValidateCode(code string) bool

ValidateCode implements CodeIssuer. It checks if the code exists and is not expired. If the code exists, it will be invalidated after this call.

type AuthorizationServerOption

type AuthorizationServerOption func(srv *AuthorizationServer)

func WithClient

func WithClient(
	clientID string,
	clientSecret string,
	redirectURI string,
) AuthorizationServerOption

type Client

type Client struct {
	ClientID string

	ClientSecret string

	RedirectURI string
}

type CodeIssuer

type CodeIssuer interface {
	IssueCode() string
	ValidateCode(code string) bool
}

type Config

type Config = oauth2.Config

Config is a type alias for https://pkg.go.dev/golang.org/x/oauth2#Config.

type Endpoint

type Endpoint = oauth2.Endpoint

Endpoint is a type alias for https://pkg.go.dev/golang.org/x/oauth2#Endpoint.

type JSONWebKey

type JSONWebKey struct {
	Kid string `json:"kid"`

	Kty string `json:"kty"`

	X string `json:"x"`

	Y string `json:"y"`
}

JSONWebKey is a JSON Web Key that only supports elliptic curve keys for now.

type JSONWebKeySet

type JSONWebKeySet struct {
	Keys []JSONWebKey `json:"keys"`
}

JSONWebKeySet is a JSON Web Key Set.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

type RetrieveError

type RetrieveError = oauth2.RetrieveError

RetrieveError is a type alias for https://pkg.go.dev/golang.org/x/oauth2#RetrieveError.

type Token

type Token = oauth2.Token

Token is a type alias for https://pkg.go.dev/golang.org/x/oauth2#Token.

type TokenSource

type TokenSource = oauth2.TokenSource

TokenSource is a type alias for https://pkg.go.dev/golang.org/x/oauth2#TokenSource.

type Transport

type Transport = oauth2.Transport

Transport is a type alias for https://pkg.go.dev/golang.org/x/oauth2#Transport.