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
}
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 |