goic

README

adhocore/goic

GOIC, Go Open ID Connect, is OpenID connect client library for Golang. It supports the Authorization Code Flow of OpenID Connect specification. It doesn't yet support refresh_token grant type and that will be added later.

It is a weekend hack project and is work in progress and not production ready yet.

Installation

go get github.com/adhocore/goic

Usage

Decide an endpoint (aka URI) in your server where you would like goic to intercept and add OpenID Connect flow. Let's say /auth/o8. Then the provider name follows it. All the OpenID providers that your server should support will need a unique name and each of the providers get a URI like so /auth/o8/<name>. Example:

Provider	Name	OpenID URI	Demo URL
Google	google	/auth/o8/google	urlssh.xyz/auth/o8/google
Microsoft	microsoft	/auth/o8/microsoft	urlssh.xyz/auth/o8/microsoft
Yahoo	yahoo	/auth/o8/yahoo	urlssh.xyz/auth/o8/yahoo

On successful verification your information is echoed back to you as JSON but not saved in server (pinky promise).

Important: All the providers must provide .well-known configurations for OpenID auto discovery.

Get ready with OpenID provider credentials (client id and secret). For Google, check this. To use the example below you need to export GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET env vars.

You also need to configure application domain and redirect URI in the Provider console/dashboard. (redirect URI is same as OpenID URI in above table).

Below is an example for authorization code flow but instead of copy/pasting it entirely you can use it for reference.

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/adhocore/goic"
)

func main() {
	// Init GOIC with a root uri and verbose mode (=true)
	g := goic.New("/auth/o8", true)

	// Register Google provider with name google and its auth URI
	// It will preemptively load well-known config and jwks keys
	p := g.NewProvider("google", "https://accounts.google.com")

	// Configure credentials for Google provider
	p.WithCredential(os.Getenv("GOOGLE_CLIENT_ID"), os.Getenv("GOOGLE_CLIENT_SECRET"))

	// Configure scope
	p.WithScope("openid email profile")

	// Define a callback that will receive token and user info on successful verification
	g.UserCallback(func(t *goic.Token, u *goic.User, w http.ResponseWriter, r *http.Request) {
		// Persist token and user info as you wish! Be sure to check for error in `u.Error` first
		// Use the available `w` and `r` params to show some nice page with message to your user
		// OR redirect them to homepage/dashboard etc

		// However, for the example, here I just dump it in backend console
		log.Println("token: ", t)
		log.Println("user: ", u)

		// and tell the user it is all good:
		_, _ = w.Write([]byte("All good, check backend console"))
	})

	// Listen address for server, 443 for https as OpenID connect mandates it!
	addr := "localhost:443"
	// You need to find a way to run your localhost in HTTPS as well.
	// You may also alias it something like `goic.lvh.me` (lvh is local virtual host)
	// *.lvh.me is automatically mapped to 127.0.0.1 in unix systems.

	// A catch-all dummy handler
	handler := func(w http.ResponseWriter, r *http.Request) {
		_, _ = w.Write([]byte(r.Method + " " + r.URL.Path))
	}

	log.Println("Server running on https://localhost")
	log.Println("            Visit https://localhost/auth/o8/google")

	// This is just example (don't copy it)
	useMux := os.Getenv("GOIC_HTTP_MUX") == "1"
	if useMux {
		mux := http.NewServeMux()
		// If you use http mux, wrap your handler with g.MiddlewareHandler
		mux.Handle("/", g.MiddlewareHandler(http.HandlerFunc(handler)))
		server := &http.Server{Addr: addr, Handler: mux}
		log.Fatal(server.ListenAndServeTLS("server.crt", "server.key"))
	} else {
		// If you just use plain simple handler func,
		// wrap your handler with g.MiddlewareFunc
		http.HandleFunc("/", g.MiddlewareFunc(handler))
		log.Fatal(http.ListenAndServeTLS(addr, "server.crt", "server.key", nil))
	}
}

// OR, you can use shorthand syntax to register providers:

g := goic.New("/auth/o8", false)
g.AddProvider(goic.Google.WithCredential(os.Getenv("GOOGLE_CLIENT_ID"), os.Getenv("GOOGLE_CLIENT_SECRET")))
g.AddProvider(goic.Microsoft.WithCredential(os.Getenv("MICROSOFT_CLIENT_ID"), os.Getenv("MICROSOFT_CLIENT_SECRET")))
g.AddProvider(goic.Yahoo.WithCredential(os.Getenv("YAHOO_CLIENT_ID"), os.Getenv("YAHOO_CLIENT_SECRET")))

// ...

After having code like that, build the binary (go build) and run server program (./<binary>).

You need to point Sign in with <provider> button to https://localhost/auth/o8/<provider> for your end user. For example:

<a href="https://localhost/auth/o8/google">Sign in with Google</a>
<a href="https://localhost/auth/o8/microsoft">Sign in with Microsoft</a>
<a href="https://localhost/auth/o8/yahoo">Sign in with Yahoo</a>

The complete flow is managed and handled by GOIC for you and on successful verification, You will be able to receive user and token info in your callback via g.UserCallback! That is where you persist the user data, set some cookie etc.

Check examples directory later for more, as it will be updated when GOIC has new features.

The example and discussion here assume localhost domain so adjust that accordingly for your domains.

Signing out

For signing out you need to manually invoke g.SignOut() from within http context. See the API below. There is also a working example. Note that not all Providers support signing out.

---

GOIC API

GOIC supports full end-to-end for Authorization Code Flow, however if you want to manually interact, here's summary of API:

Supports

Use it to check if a provider is supported.

g := goic.New("/auth/o8", false)
g.NewProvider("abc", "...").WithCredential("...", "...")

g.Supports("abc") // true
g.Supports("xyz") // false

RefreshToken

Use it to request Access token by using refresh token.

g := goic.New("/auth/o8", false)
// ... add providers
t := &goic.Token{RefreshToken: "your refresh token", Provider: goic.Microsoft.Name}
tok, err := g.RefreshToken(t)
// Do something with tok.AccessToken

RequestAuth

Manually request authentication from OpenID Provider. Must be called from within http context.

g := goic.New("/auth/o8", false)
p := g.NewProvider("abc", "...").WithCredential("...", "...")

// Generate random unique state and nonce
state, nonce := goic.RandomString(24), goic.RandomString(24)
// You must save them to cookie/session, so it can be retrieved later for crosscheck

// redir is the redirect url in your host for provider of interest
redir := "https://localhost/auth/o8/" + p.Name

// Redirects to provider first and then back to above redir url
// res = http.ResponseWriter, req = *http.Request
err := g.RequestAuth(p, state, nonce, redir, res, req)

Authenticate

Manually attempt to authenticate after the request comes back from OpenID Provider.

g := goic.New("/auth/o8", false)
p := g.NewProvider("abc", "...").WithCredential("...", "...")

// Read openid provider code from query param, and nonce from cookie/session etc
// PS: Validate that the nonce is relevant to the state sent by openid provider
code, nonce := "", ""

// redir is the redirect url in your host for provider of interest
redir := "https://localhost/auth/o8/" + p.Name

tok, err := g.Authenticate(p, code, nonce, redir)

Userinfo

Manually request Userinfo by using the token returned by Authentication above.

g := goic.New("/auth/o8", false)
p := g.NewProvider("abc", "...").WithCredential("...", "...")
// ...
tok, err := g.Authenticate(p, code, nonce, redir)
user := g.UserInfo(tok)
err := user.Error

SignOut

Use it to sign out the user from OpenID Provider. Must be called from within http context. Ideally, you would clear the session and logout user from your own system first and then invoke SignOut.

g := goic.New("/auth/o8", false)
p := g.NewProvider("abc", "...").WithCredential("...", "...")
// ...
tok := &goic.Token{AccessToken: "current session token", Provider: p.Name}
err := g.SignOut(tok, "http://some/preconfigured/redir/uri", res, req)
// redir uri is optional
err := g.SignOut(tok, "", res, req)

---

Demo

GOIC has been implemented in opensource project adhocore/urlsh:

Provider	Name	Demo URL
Google	google	urlssh.xyz/auth/o8/google
Microsoft	microsoft	urlssh.xyz/auth/o8/microsoft
Yahoo	yahoo	urlssh.xyz/auth/o8/yahoo

On successful verification your information is echoed back to you as JSON but not saved in server (pinky promise).

---

TODO

• Support refresh token grant_type Check #2
• Tests and more tests
• Release stable version
• Support OpenID Implicit Flow Check #3

License

© MIT | 2021-2099, Jitendra Adhikari

Credits

Release managed by please.

---

Other projects

My other golang projects you might find interesting and useful:

• gronx - Lightweight, fast and dependency-free Cron expression parser (due checker), task scheduler and/or daemon for Golang (tested on v1.13 and above) and standalone usage.
• urlsh - URL shortener and bookmarker service with UI, API, Cache, Hits Counter and forwarder using postgres and redis in backend, bulma in frontend; has web and cli client
• fast - Check your internet speed with ease and comfort right from the terminal

Documentation

Index

• Variables
• func Base64UrlDecode(s string) ([]byte, error)
• func GetCurve(s string) elliptic.Curve
• func ParseExponent(es string) int
• func ParseModulo(ns string) *big.Int
• func RandomString(len int) string
• type Goic
  • func New(uri string, verbose bool) *Goic
  • func (g *Goic) AddProvider(p *Provider) *Provider
  • func (g *Goic) Authenticate(p *Provider, code, nonce, redir string) (*Token, error)
  • func (g *Goic) MiddlewareFunc(next http.HandlerFunc) http.HandlerFunc
  • func (g *Goic) MiddlewareHandler(next http.Handler) http.Handler
  • func (g *Goic) NewProvider(name, uri string) *Provider
  • func (g *Goic) RefreshToken(tok *Token) (*Token, error)
  • func (g *Goic) RequestAuth(p *Provider, state, nonce, redir string, res http.ResponseWriter, ...) error
  • func (g *Goic) SignOut(tok *Token, redir string, res http.ResponseWriter, req *http.Request) error
  • func (g *Goic) Supports(name string) bool
  • func (g *Goic) UnsetState(s string)
  • func (g *Goic) UserCallback(cb UserCallback) *Goic
  • func (g *Goic) UserInfo(tok *Token) *User
• type Provider
  • func (p *Provider) WithCredential(id, secret string) *Provider
  • func (p *Provider) WithScope(s string) *Provider
• type Token
• type User
• type UserCallback
• type WellKnown

Variables

var (
	// ErrProviderState is error for invalid request state
	ErrProviderState = errors.New("goic provider: invalid request state")

	// ErrProviderSupport is error for unsupported provider
	ErrProviderSupport = errors.New("goic provider: unsupported provider")

	// ErrTokenEmpty is error for empty token
	ErrTokenEmpty = errors.New("goic id_token: empty token")

	// ErrTokenInvalid is error for invalid token
	ErrTokenInvalid = errors.New("goic id_token: invalid id_token")

	// ErrRefreshTokenInvalid is error for invalid token
	ErrRefreshTokenInvalid = errors.New("goic id_token: invalid refresh_token")

	// ErrTokenClaims is error for invalid token claims
	ErrTokenClaims = errors.New("goic id_token: invalid id_token claims")

	// ErrTokenNonce is error for invalid noce
	ErrTokenNonce = errors.New("goic id_token: invalid nonce")

	// ErrTokenAud is error for invalid audience
	ErrTokenAud = errors.New("goic id_token: invalid audience")

	// ErrTokenAlgo is error for unsupported signing algo
	ErrTokenAlgo = errors.New("goic id_token: unsupported signing algo")

	// ErrTokenKey is error for undetermined signing key
	ErrTokenKey = errors.New("goic id_token: can't determine signing key")

	// ErrTokenAccessKey is error for invalid access_token
	ErrTokenAccessKey = errors.New("goic id_token: invalid access_token")

	// ErrSignOutRedir is error for invalid post sign-out redirect uri
	ErrSignOutRedir = errors.New("goic sign-out: post redirect uri is invalid")
)

var Google = &Provider{
	Name:  "google",
	URL:   "https://accounts.google.com",
	Scope: "openid email profile",
}

Google is ready to use Provider instance

var Microsoft = &Provider{
	Name:  "microsoft",
	URL:   "https://login.microsoftonline.com/common/v2.0",
	Scope: "openid email profile offline_access",
}

Microsoft is ready to use Provider instance

var Yahoo = &Provider{
	Name:  "yahoo",
	URL:   "https://login.yahoo.com",
	Scope: "openid openid2 email profile",
}

Functions

func Base64UrlDecode

func Base64UrlDecode(s string) ([]byte, error)

Base64UrlDecode decodes JWT segments with base64 accounting for URL chars

func GetCurve

func GetCurve(s string) elliptic.Curve

GetCurve gets the elliptic.Curve from last 3 chars of string s

func ParseExponent

func ParseExponent(es string) int

ParseExponent ParseModulo parses the "e" value of jwks key

func ParseModulo

func ParseModulo(ns string) *big.Int

ParseModulo parses the "n" value of jwks key

func RandomString

func RandomString(len int) string

RandomString generates random string of given length It sets rand seed on each call and returns generated string.

Types

type Goic

type Goic struct {
	URIPrefix string
	// contains filtered or unexported fields
}

Goic is the main program

func New

func New(uri string, verbose bool) *Goic

New gives new GOIC instance

func (*Goic) AddProvider

func (g *Goic) AddProvider(p *Provider) *Provider

func (*Goic) Authenticate

func (g *Goic) Authenticate(p *Provider, code, nonce, redir string) (*Token, error)

Authenticate tries to authenticate a user by given code and nonce It is where token is requested and validated

func (*Goic) MiddlewareFunc

func (g *Goic) MiddlewareFunc(next http.HandlerFunc) http.HandlerFunc

MiddlewareFunc is wrapper for http.HandlerFunc that adds OpenID support

func (*Goic) MiddlewareHandler

func (g *Goic) MiddlewareHandler(next http.Handler) http.Handler

MiddlewareHandler is wrapper for http.Handler that adds OpenID support

func (*Goic) NewProvider

func (g *Goic) NewProvider(name, uri string) *Provider

NewProvider adds a new OpenID provider by name It also preloads the well known config and jwks keys

func (*Goic) RefreshToken

func (g *Goic) RefreshToken(tok *Token) (*Token, error)

RefreshToken gets new access token using the refresh token

func (*Goic) RequestAuth

func (g *Goic) RequestAuth(p *Provider, state, nonce, redir string, res http.ResponseWriter, req *http.Request) error

RequestAuth is the starting point of OpenID flow

func (*Goic) SignOut

func (g *Goic) SignOut(tok *Token, redir string, res http.ResponseWriter, req *http.Request) error

SignOut signs out the Token from OpenID Provider and then redirects to given URI Redirect URI must be preconfigured in OpenID Provider already

func (*Goic) Supports

func (g *Goic) Supports(name string) bool

Supports checks if a given provider name is supported

func (*Goic) UnsetState

func (g *Goic) UnsetState(s string)

func (*Goic) UserCallback

func (g *Goic) UserCallback(cb UserCallback) *Goic

UserCallback sets a callback for post user verification

func (*Goic) UserInfo

func (g *Goic) UserInfo(tok *Token) *User

UserInfo loads user info when given a Token Error if any is embedded inside User.Error

type Provider

type Provider struct {
	Name  string
	URL   string
	Scope string
	// contains filtered or unexported fields
}

Provider represents OpenID Connect provider

func (*Provider) WithCredential

func (p *Provider) WithCredential(id, secret string) *Provider

WithCredential sets client id and secret for a Provider

func (*Provider) WithScope

func (p *Provider) WithScope(s string) *Provider

WithScope sets scope for a Provider

type Token

type Token struct {
	Err          string `json:"error,omitempty"`
	ErrDesc      string `json:"error_description,omitempty"`
	IDToken      string `json:"id_token"`
	AccessToken  string `json:"access_token,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Provider     string `json:"provider,omitempty"`
}

Token represents token structure from well known token endpoint

type User

type User struct {
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified,omitempty"`
	FamilyName    string `json:"family_name,omitempty"`
	GivenName     string `json:"given_name,omitempty"`
	Locale        string `json:"locale,omitempty"`
	Name          string `json:"name"`
	Picture       string `json:"picture,omitempty"`
	Subject       string `json:"sub,omitempty"`
	Error         error  `json:"-"`
}

User represents user from well known user info endpoint

type UserCallback

type UserCallback func(t *Token, u *User, w http.ResponseWriter, r *http.Request)

UserCallback defines signature for post user verification callback

type WellKnown

type WellKnown struct {
	Issuer      string   `json:"issuer"`
	KeysURI     string   `json:"jwks_uri"`
	AuthURI     string   `json:"authorization_endpoint"`
	TokenURI    string   `json:"token_endpoint"`
	UserInfoURI string   `json:"userinfo_endpoint"`
	SignOutURI  string   `json:"end_session_endpoint,omitempty"`
	RevokeURI   string   `json:"revocation_endpoint,omitempty"`
	AlgoSupport []string `json:"id_token_signing_alg_values_supported"`
	// contains filtered or unexported fields
}

WellKnown represents OpenID Connect well-known config