oauthserver

README

togo-framework/oauth-server

OAuth2 / OIDC authorization server for togo — be an identity provider, not just a consumer.

Install

togo install togo-framework/oauth-server

The togo answer to Laravel Passport / Doorkeeper / django-oauth-toolkit: issue OAuth2 tokens to client apps. Where auth and auth-oauth let togo consume identity, oauth-server lets togo be the identity provider.

Grants & endpoints

• authorization_code (with PKCE S256) · client_credentials · refresh_token (rotated)
• Access tokens are signed JWT (HS256); refresh tokens are opaque + single-use
• GET /oauth/authorize · POST /oauth/token · POST /oauth/introspect · POST /oauth/revoke · GET /oauth/userinfo
• GET /.well-known/openid-configuration · GET /.well-known/jwks.json
• POST /api/oauth/clients (register a client)

Configuration

Env	Description
OAUTH_SECRET	HS256 signing secret for access tokens (set in production)
OAUTH_ISSUER	issuer URL (e.g. https://id.example.com)

Usage

srv, _ := oauthserver.FromKernel(k)

// Register a client (public/PKCE → no secret; confidential → secret returned once).
client, _ := srv.RegisterClient("My SPA", []string{"https://app.example.com/callback"},
    []string{"openid", "profile"}, []string{"authorization_code", "refresh_token"}, false)

// Authorization code + PKCE (after the user authorizes at /oauth/authorize):
code, _ := srv.IssueCode(client.ID, userID, "openid profile", redirectURI, codeChallenge, "S256")
tokens, _ := srv.ExchangeCode(code, codeVerifier, redirectURI, client.ID, "")
// tokens.AccessToken (JWT) · tokens.RefreshToken

// Verify a token (resource server):
info := srv.Introspect(tokens.AccessToken)   // {Active, Sub, Scope, ClientID, Exp}
srv.Revoke(tokens.AccessToken)

Other grants

srv.ClientCredentials(clientID, clientSecret, "api")   // machine-to-machine
srv.RefreshExchange(refreshToken, clientID, secret)    // rotate

Tokens are HS256 (symmetric), so resource servers verify via /oauth/introspect (or the shared secret). The JWKS endpoint returns an empty key set; RS256 with published keys is a planned option.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package oauthserver turns a togo app into an OAuth2 / OIDC authorization server — an identity provider that issues tokens to client apps (the togo answer to Laravel Passport / Doorkeeper / django-oauth-toolkit).

Supported grants: authorization_code (with PKCE S256), client_credentials, and refresh_token. Access tokens are signed JWTs (HS256); refresh tokens are opaque + rotated. Endpoints: /oauth/authorize, /oauth/token, /oauth/introspect, /oauth/revoke, /oauth/userinfo, /.well-known/{openid-configuration,jwks.json}.

Index

• type Client
• type Introspection
• type Server
  • func FromKernel(k *togo.Kernel) (*Server, bool)
  • func New() *Server
  • func (s *Server) Client(id string) (*Client, bool)
  • func (s *Server) ClientCredentials(clientID, clientSecret, scope string) (*Tokens, error)
  • func (s *Server) ExchangeCode(code, verifier, redirectURI, clientID, clientSecret string) (*Tokens, error)
  • func (s *Server) Introspect(token string) Introspection
  • func (s *Server) IssueCode(clientID, userID, scope, redirectURI, challenge, method string) (string, error)
  • func (s *Server) RefreshExchange(refreshTok, clientID, clientSecret string) (*Tokens, error)
  • func (s *Server) RegisterClient(name string, redirectURIs, scopes, grants []string, confidential bool) (*Client, string)
  • func (s *Server) Revoke(token string)
• type Tokens

Types

type Client

type Client struct {
	ID           string   `json:"client_id"`
	SecretHash   string   `json:"-"` // sha256-hex of the secret ("" = public client)
	Name         string   `json:"name"`
	RedirectURIs []string `json:"redirect_uris"`
	Scopes       []string `json:"scopes"`
	Grants       []string `json:"grants"`
}

Client is a registered OAuth2 client application.

type Introspection

type Introspection struct {
	Active    bool   `json:"active"`
	Scope     string `json:"scope,omitempty"`
	ClientID  string `json:"client_id,omitempty"`
	Sub       string `json:"sub,omitempty"`
	Exp       int64  `json:"exp,omitempty"`
	TokenType string `json:"token_type,omitempty"`
}

Introspection is the RFC 7662 token-introspection response.

type Server

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

Server is the OAuth2 authorization server stored on the kernel.

func FromKernel

func FromKernel(k *togo.Kernel) (*Server, bool)

FromKernel returns the OAuth Server registered on the kernel.

func New

func New() *Server

New builds a Server from env (OAUTH_SECRET, OAUTH_ISSUER).

func (*Server) Client

func (s *Server) Client(id string) (*Client, bool)

Client returns a registered client.

func (*Server) ClientCredentials

func (s *Server) ClientCredentials(clientID, clientSecret, scope string) (*Tokens, error)

ClientCredentials runs the client_credentials grant.

func (*Server) ExchangeCode

func (s *Server) ExchangeCode(code, verifier, redirectURI, clientID, clientSecret string) (*Tokens, error)

ExchangeCode runs the authorization_code grant (with PKCE if a challenge was set).

func (*Server) Introspect

func (s *Server) Introspect(token string) Introspection

Introspect reports whether a token (access JWT or refresh) is active.

func (*Server) IssueCode

func (s *Server) IssueCode(clientID, userID, scope, redirectURI, challenge, method string) (string, error)

IssueCode issues an authorization code after the resource owner authorizes.

func (*Server) RefreshExchange

func (s *Server) RefreshExchange(refreshTok, clientID, clientSecret string) (*Tokens, error)

RefreshExchange runs the refresh_token grant (rotating the refresh token).

func (*Server) RegisterClient

func (s *Server) RegisterClient(name string, redirectURIs, scopes, grants []string, confidential bool) (*Client, string)

RegisterClient registers a client; the plaintext secret is returned once for confidential clients (empty for public/PKCE clients).

func (*Server) Revoke

func (s *Server) Revoke(token string)

Revoke invalidates an access (by jti) or refresh token.

type Tokens

type Tokens struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
}

Tokens is the token endpoint response.