TwigBush Docs
Getting Started

Introduction

Get started with TwigBush - an open source GNAP Authorization Server for modern access control

What is TwigBush?

TwigBush is an early open source implementation of the Grant Negotiation and Authorization Protocol (GNAP, RFC 9635) written in Go. It provides the foundation for a GNAP Authorization Server (AS) and supporting libraries for Resource Servers (RS), enabling modern, key-bound access control for both human users and AI agents. We’re building this project in the open to grow a community around secure, next-generation authorization.

Why GNAP?

GNAP represents the next evolution in authorization protocols, designed to address limitations in OAuth 2.0 and provide:

  • Key-Bound Tokens: Every access token is cryptographically bound to the client's key
  • Proof-of-Possession: Prevents token replay attacks with DPoP, mTLS, or HTTP Message Signatures
  • No Client Pre-Registration: Dynamic client instances without pre-shared secrets
  • Fine-Grained Control: Request specific resources with precise constraints
  • Machine-Friendly: Native support for non-browser, automated clients

Core Features

Authorization Server

  • Complete implementation of GNAP core endpoints
  • /grant - Initiate authorization requests
  • /continue - Handle interaction continuation
  • /introspect - Token validation for resource servers
  • /.well-known/jwks.json - Public key discovery

Security Features

  • Proof Methods: Detached JWS, HTTP Message Signatures, DPoP, mTLS
  • Short-Lived Tokens: Configurable TTL with automatic expiration
  • Key Rotation: Built-in support for key lifecycle management
  • Audit Logging: Comprehensive security event tracking

Integration Options

  • Policy Engines: OpenFGA adapter for Zanzibar-style authorization
  • Resource Servers: Example implementations and client libraries
  • Storage Backends: PostgreSQL with migration support
  • Monitoring: Prometheus metrics and health endpoints

Project Structure

TwigBush/
├── cmd/
│   ├── as/          # GNAP Authorization Server binary
│   └── rs-demo/     # Example Resource Server
├── internal/        # Core engine implementation
│   ├── tokens/      # Token generation and validation
│   ├── signing/     # Cryptographic operations
│   ├── policy/      # Authorization policy integration
│   └── storage/     # Persistence layer
└── pkg/            # Importable client libraries
    ├── client/     # GNAP client implementation
    └── rs/         # Resource server utilities

Quick Start

Prerequisites

  • Go 1.22 or later
  • Docker (for PostgreSQL and OpenFGA)
  • Git

Installation

Clone the repository and install dependencies:

git clone https://github.com/TwigBush/TwigBush.git
cd TwigBush
go mod download

Running the Authorization Server

Start the AS with default configuration:

go run ./cmd/as

The server starts on port 8085 by default. Verify it's running:

curl http://localhost:8085/.well-known/jwks.json

Next Steps

Contributing

We welcome contributions! See our Contributing Guide for details.

License

TwigBush is released under the Apache License 2.0.

GNAP Protocol

Understanding the Grant Negotiation and Authorization Protocol (RFC 9635)