An OpenID Connect Core 1.0 provider written in Go, focused on authorization and token issuance.

Asteroid is composed of small, independent components that work together loosely — much like a cluster of asteroids forming a stable system.

This design aligns with the UNIX philosophy: each unit does one thing well, keeping the whole system simple, transparent, and easy to understand.

Asteroid needs only a compiler; Go 1.24+ is sufficient.
The recommended setup is the reproducible Nix development shell:

nix develop

Inside the Nix shell, Redis is available by default.

1. Build the server:

go mod tidy
go build -o bin/asteroid ./cmd/server

2. Start the server:

./bin/asteroid

The server will start on port 8880 by default and automatically generate signing keys as needed.

Asteroid is configured using environment variables:

For production deployments, be sure to read the Security Note below.

For detailed flow diagrams and architecture documentation, see docs/architecture.md.

GET /.well-known/openid-configuration

Returns the OpenID Connect provider metadata used by clients for discovery.

GET /authorize

Implements the authorization code flow for a pre-seeded test user.

POST /token

Exchanges authorization codes for access and refresh tokens, or refreshes existing tokens.

GET /jwks.json

Public JWK used by clients and resource servers to validate tokens.

Asteroid does not perform user authentication itself.
The authenticated user is provided by the upstream layer via:

X-Authenticated-User: <subject>

Asteroid resolves user information on demand through a pluggable provider:

// Development
userinfoProvider := source.NewYAMLProvider("./data/users.yaml")

// Production
userinfoProvider := source.NewHTTPProvider(apiURL, httpClient)

The provider acts as the trust boundary:

• If the user no longer exists - token issuance is denied
• No user data is stored or cached inside Asteroid
• Any identity backend can be integrated by implementing the interface

This keeps OIDC authorization pure, independent, and decoupled from your authentication system.

Asteroid includes an in-memory store by default.
If you want to use Redis, build with:

go build -tags redis -o bin/asteroid ./cmd/server

Redis is recommended for production-grade authorization code and token storage.

Asteroid is not dockerized by default — it runs as a small, self-contained Go binary.

For developers who use Redis as storage backend, minimal Docker Compose examples are available under the examples/ directory.

The examples contain only the essentials.

Asteroid automatically generates signing keys at startup and handles key rotation transparently. Keys are never stored in version control and are managed entirely through the built-in key management system.

In development environments, generated keys are persisted to local files for convenience. For production deployments, we highly recommend configuring a Key Management Service (KMS) through the persister interface for secure key storage and rotation.

In addition, Asteroid should not be exposed directly to the public internet.
We recommend placing it behind a reverse proxy:

• Nginx (via unix domain socket)
  Provides optimal isolation, no TCP surface, and keeps TLS termination outside the Asteroid process.

• AWS ALB (directly in front of Asteroid)
  A clean, minimal setup where TLS termination and access control are fully handled by ALB, keeping Asteroid isolated from direct exposure and free from transport-layer concerns.

By delegating TLS termination, rate limiting, and access policies to the upstream layer, the Asteroid binary can remain small, simple, and secure—consistent with its UNIX-inspired design philosophy.

Asteroid speaks HTTP internally. In production, clients must access the issuer over HTTPS, with TLS termination handled entirely by the upstream proxy (nginx, Envoy, ALB, etc.). This keeps Asteroid transport-layer agnostic while remaining compliant with OIDC.

A well-engineered Linux or BSD system remains one of the most robust and predictable foundations available.

Running Asteroid directly as a native binary on a POSIX system provides full control over the kernel, filesystem, resource limits, and networking behavior — a level of transparency that containerized or serverless runtimes cannot offer.

In production, Asteroid is designed to run behind a reverse proxy such as Nginx, ALB, or Envoy, with TLS termination handled upstream. Communication between the proxy and Asteroid is typically done via a UNIX domain socket for minimal overhead and clear responsibility boundaries.

This approach offers:

• strict separation of concerns (TLS, routing, and access control handled outside Asteroid)
• predictable performance without container abstraction
• minimal operational complexity
• suitability for EC2, on-premise Linux, or any POSIX-compliant system

Docker support is provided only for local development and testing.
For production deployments, running Asteroid directly on Linux with a reverse proxy is the recommended configuration.

Copyright KEI SAWAMURA 2025 (a.k.a keix)
Asteroid is licensed under the MIT License. Copying and modifying is encouraged and appreciated.