AuthBricks

AuthBricks is a Go library for building Identity and Access Management solutions. It aims to provide simple primitives and APIs that comply with the best practices in the industry, while remaining flexible enough to be used in a wide range of use cases.

At the moment it implements the following RFCs (planning to get to full OIDC compliance):

OAuth 2.0 Authorization Code Grant (RFC 6749)
OAuth 2.0 Client Credentials Grant (RFC 6749)
OAuth 2.0 Refresh Token Grant (RFC 6749)
OIDC Hybrid Flow (OIDC Core 1.0)
PKCE Support (RFC 7636)
JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens (RFC 9068)

Get Started

Basic Setup

First, you need to set up the database and API server. Then you can use the client to manage your services and applications.

package main

import (
	"context"
	
	"go.authbricks.com/bricks/api"
	"go.authbricks.com/bricks/client"
	"go.authbricks.com/bricks/database"
)

func main() {
	// 1. Create database connection
	db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
	if err != nil {
		panic(err)
	}
	
	// 2. Create API server
	a, err := api.New(db)
	if err != nil {
		panic(err)
	}
	
	// 3. Create client
	c := client.New(db)
	
	// Now you can use the client to manage your services and applications
	// See the Services section for examples
}

Custom Routes

You can add custom routes to the API server using the WithRoutes option. This allows you to extend the API with your own endpoints and middleware.

package main

import (
	"context"
	"net/http"
	
	"go.authbricks.com/bricks/api"
	"go.authbricks.com/bricks/database"
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

func main() {
	db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
	if err != nil {
		panic(err)
	}
	
	// Define custom routes
	routes := []api.Route{
		{
			Method: http.MethodGet,
			Path:   "/custom",
			Handler: echo.HandlerFunc(func(c echo.Context) error {
				return c.JSON(http.StatusTeapot, "custom route")
			}),
			Middlewares: []echo.MiddlewareFunc{},
		},
		{
			Method: http.MethodGet,
			Path:   "/custom/with/middleware",
			Handler: echo.HandlerFunc(func(c echo.Context) error {
				return c.JSON(http.StatusTeapot, "custom route with middleware")
			}),
			Middlewares: []echo.MiddlewareFunc{
				middleware.BasicAuth(func(username, password string, c echo.Context) (bool, error) {
					if username == "toni" && password == "hunter2" {
						return true, nil
					}
					return false, nil
				}),
			},
		},
	}
	
	// Create API server with custom routes
	a, err := api.New(db, ":8080",
		api.WithRoutes(routes),
	)
	if err != nil {
		panic(err)
	}
	
	a.ListenAndServe()
}

Each route can specify:

Method: The HTTP method (GET, POST, etc.)
Path: The URL path for the route
Handler: The Echo handler function that processes the request
Middlewares: Optional middleware functions to apply to the route

Postgres

Connect to a local postgres database, and start the API server on port 8080.

package main

import (
	"context"
	
	"go.authbricks.com/bricks/api"
	"go.authbricks.com/bricks/database"
)

func main() {
	db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
	if err != nil {
		panic(err)
	}
	
	a, err := api.New(db)
	if err != nil {
		panic(err)
	}
	
	a.ListenAndServe(":8080")
}

MySQL

Connect to a local MySQL database, and start the API server on port 8080.

package main

import (
	"context"
	
	"go.authbricks.com/bricks/api"
	"go.authbricks.com/bricks/database"
)

func main() {
	db, err := database.NewMySQL(context.Background(), "user:password@tcp(localhost:3306)/db")
	if err != nil {
		panic(err)
	}
	
	a, err := api.New(db)
	if err != nil {
		panic(err)
	}
	
	a.ListenAndServe(":8080")
}

SQLite

Connect to a SQLite database, and start the API server on port 8080.

package main 

import (
	"context"
	
	"go.authbricks.com/bricks/api"
	"go.authbricks.com/bricks/database"
)

func main() {
	db, err := database.NewSQLite(context.Background(), "file:file.db?_fk=1")
	if err != nil {
		panic(err)
	}
	
	a, err := api.New(db)
	if err != nil {
		panic(err)
	}
	
	a.ListenAndServe(":8080")
}

Define a new Service

All the examples so far have simply started the API server on port 8080. The server does not actually have any endpoints yet. In this section, we will define a new service.

In terms of OAuth / OIDC specifications, you can think of a service as your Authorization server. For example, if your business needs to authenticate both your customers and your employees, you could define two different services called customers and employees.

package main

import (
    "context"
    "crypto/rsa"
    "crypto/rand"
    
    "go.authbricks.com/bricks/api"
    "go.authbricks.com/bricks/client"
    "go.authbricks.com/bricks/config"
    "go.authbricks.com/bricks/database"
)

func main() {
    // 1. Create database connection
    db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
    if err != nil {
        panic(err)
    }
    
    // 2. Create API server
    a, err := api.New(db)
    if err != nil {
        panic(err)
    }
    
    // 3. Create client
    c := client.New(db)
    
    // 4. Generate RSA key for signing
    privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
    if err != nil {
        panic(err)
    }
    
    // 5. Create service configuration
    serviceConfig := config.Service{
        Name: "customers",
        Identifier: "customers",
        Description: "Service for authenticating customers",
        ServiceMetadata: config.ServiceMetadata{
            "version": "1.0.0",
            "environment": "production",
        },
        AllowedClientMetadata: []string{"logo_uri", "client_uri", "policy_uri"},
        Scopes: []string{"openid", "profile", "email", "read", "write"},
        GrantTypes: []string{
            config.GrantTypeAuthorizationCode,
            config.GrantTypeClientCredentials,
            config.GrantTypeRefreshToken,
        },
        ResponseTypes: []string{
            config.ResponseTypeCode,
            config.ResponseTypeIDToken,
            config.ResponseTypeCodeIDToken,
        },
        AuthorizationEndpoint: config.AuthorizationEndpoint{
            Enabled: true,
        },
        TokenEndpoint: config.TokenEndpoint{
            Enabled: true,
        },
        UserInfoEndpoint: config.UserInfoEndpoint{
            Enabled: true,
        },
        JWKSEndpoint: config.JWKSEndpoint{
            Enabled: true,
        },
        WellKnownEndpoint: config.WellKnownEndpoint{
            Enabled: true,
        },
        LoginEndpoint: config.LoginEndpoint{
            Enabled: true,
        },
        Connection: config.Connection{
            EmailPassword: &config.EmailPasswordConnection{
                Enabled: true,
            },
            OIDC: []config.OIDCConnection{
                {
                    Name: "google",
                    Enabled: true,
                    ClientID: "your-google-client-id",
                    ClientSecret: "your-google-client-secret",
                    Scopes: []string{"openid", "profile", "email"},
                    RedirectURI: "http://localhost:8080/callback",
                    WellKnownEndpoint: "https://accounts.google.com/.well-known/openid-configuration",
                },
                {
                    Name: "github",
                    Enabled: true,
                    ClientID: "your-github-client-id",
                    ClientSecret: "your-github-client-secret",
                    Scopes: []string{"read:user", "user:email"},
                    RedirectURI: "http://localhost:8080/callback",
                    WellKnownEndpoint: "https://github.com/.well-known/openid-configuration",
                },
            },
        },
        Keys: []crypto.PrivateKey{privateKey},
    }
    
    // 6. Create service using the client
    svc, err := c.CreateOrUpdateService(context.Background(), serviceConfig)
    if err != nil {
        panic(err)
    }
    
    // 7. Start the API server
    a.ListenAndServe(":8080")
}

Define an Application

Once you have defined a service, you can create a new application (also known as OAuth Client) for that service.

package main

import (
    "context"
    
    "go.authbricks.com/bricks/api"
    "go.authbricks.com/bricks/client"
    "go.authbricks.com/bricks/config"
    "go.authbricks.com/bricks/database"
)

func main() {
    // 1. Create database connection
    db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
    if err != nil {
        panic(err)
    }
    
    // 2. Create API server
    a, err := api.New(db)
    if err != nil {
        panic(err)
    }
    
    // 3. Create client
    c := client.New(db)
    
    // 4. Get service
    svc, err := c.GetService(context.Background(), "customers")
    if err != nil {
        panic(err)
    }
    
    // 5. Create application configuration
    appConfig := config.Application{
        Name: "myapp",
        Service: "customers",
        Description: "My OAuth2/OIDC Application",
        Public: false,
        RedirectURIs: []string{
            "http://localhost:8080/callback",
            "https://myapp.com/callback",
        },
        ResponseTypes: []string{
            config.ResponseTypeCode,
            config.ResponseTypeIDToken,
            config.ResponseTypeCodeIDToken,
        },
        GrantTypes: []string{
            config.GrantTypeAuthorizationCode,
            config.GrantTypeRefreshToken,
        },
        PKCERequired: true,
        S256CodeChallengeMethodRequired: true,
        AllowedAuthenticationMethods: []string{"client_secret_basic", "client_secret_post"},
        Scopes: []string{"openid", "profile", "email", "read", "write"},
    }
    
    // 6. Create application using the client
    app, err := c.CreateOrUpdateApplication(context.Background(), appConfig)
    if err != nil {
        panic(err)
    }
    
    // 7. Start the API server
    a.ListenAndServe(":8080")
}

Credentials

Once you have created an application, you can generate credentials for it.

package main

import (
    "context"
    
    "go.authbricks.com/bricks/api"
    "go.authbricks.com/bricks/client"
    "go.authbricks.com/bricks/config"
    "go.authbricks.com/bricks/database"
    "go.authbricks.com/bricks/crypto"
)

func main() {
    // 1. Create database connection
    db, err := database.NewPostgres(context.Background(), "postgres://user:password@localhost:5432/db")
    if err != nil {
        panic(err)
    }
    
    // 2. Create API server
    a, err := api.New(db)
    if err != nil {
        panic(err)
    }
    
    // 3. Create client
    c := client.New(db)
    
    // 4. Get application
    app, err := c.GetApplication(context.Background(), "myapp")
    if err != nil {
        panic(err)
    }
    
    // 5. Create credentials configuration
    credentialsConfig := config.Credentials{
        ClientID: crypto.GenerateClientID(),
        ClientSecret: crypto.GenerateClientSecret(),
    }
    
    // 6. Create credentials using the client
    creds, err := c.CreateOrUpdateCredentials(context.Background(), credentialsConfig)
    if err != nil {
        panic(err)
    }
    
    // 7. Start the API server
    a.ListenAndServe(":8080")
}

Errors

The AuthBricks API uses the following error codes:

4xx

Error Code	Meaning
400	Bad Request – The request was malformed or contained invalid parameters
401	Unauthorized – The request requires authentication
403	Forbidden – The authenticated user does not have permission to access the requested resource
404	Not Found – The requested resource could not be found
405	Method Not Allowed – The HTTP method is not supported for the requested resource
406	Not Acceptable – The requested response format is not supported
409	Conflict – The request conflicts with the current state of the resource
415	Unsupported Media Type – The request media type is not supported
429	Too Many Requests – The request rate limit has been exceeded

5xx

Error Code	Meaning
500	Internal Server Error – An unexpected error occurred on the server
503	Service Unavailable – The service is temporarily unavailable