oauth2

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(":8000",
        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 8000:8000 ghcr.io/oxisto/oauth2go

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

Custom claims

oauth2go supports custom access-token claims through WithTokenClaimsFunc.

• The callback receives clientID and userID.
• userID is set for the authorization code flow (when the login integration is used).
• userID is an empty string for client credentials.

Current built-in user claims behavior:

• If userID is present, access token sub is set to the user and preferred_username is included.
• If userID is empty, sub is set to the client ID.
• Refresh tokens keep sub as the client ID and include preferred_username when a user is present.

Example:

srv := oauth2.NewServer(
    ":8000",
    oauth2.WithClient("client", "secret", "http://localhost/callback"),
    login.WithLoginPage(login.WithUser("admin", "admin")),
    oauth2.WithTokenClaimsFunc(func(clientID string, userID string) map[string]interface{} {
        claims := map[string]any{
            "tenant": "default",
        }

        if userID == "admin" {
            claims["role"] = "admin"
        }

        return claims
    }),
)

Reserved claims (sub, exp, preferred_username, nbf, iat, iss, aud, jti) are controlled by the server and ignored if returned by the custom claims callback.

(To be) Implemented Standards

• RFC 6749. The OAuth 2.0 Authorization Framework
• RFC 6750. The OAuth 2.0 Authorization Framework: Bearer Token Usage
• RFC 7517. JSON Web Key (JWK)
• RFC 7636. Proof Key for Code Exchange by OAuth Public Clients
• RFC 8414. OAuth 2.0 Authorization Server Metadata