bulwark-auth-guard

Go client library for bulwark-auth authentication service.

Installation

go get github.com/latebit-io/bulwark-auth-guard

Usage

Creating a Client

import (
    "net/http"
    bulwark "github.com/latebit-io/bulwark-auth-guard"
)

client := &http.Client{}
guard := bulwark.NewGuard("http://localhost:8080", client)

Multi-Tenancy

All operations require a tenantID as the first parameter after context.Context. This enables the library to support multi-tenant authentication systems where users and sessions are isolated by tenant.

tenantID := "my-organization-id"

Account Management

Create Account

ctx := context.Background()
tenantID := "my-organization-id"
email := "user@example.com"
password := "securePassword123!"

err := guard.Account.Create(ctx, tenantID, email, password)
if err != nil {
    log.Fatal(err)
}
// User receives verification email

Verify Account

verificationToken := "token-from-email"
err := guard.Account.Verify(ctx, tenantID, email, verificationToken)
if err != nil {
    log.Fatal(err)
}

Change Password

err := guard.Account.ChangePassword(ctx, tenantID, email, "newPassword123!", accessToken)
if err != nil {
    log.Fatal(err)
}

Authentication

Password Authentication

clientID := "my-app-device-id"
authenticated, err := guard.Authenticate.Password(ctx, tenantID, email, password, clientID)
if err != nil {
    log.Fatal(err)
}

// Important: Must acknowledge after authentication
err = guard.Authenticate.Acknowledge(ctx, tenantID, authenticated)
if err != nil {
    log.Fatal(err)
}

// Access tokens
fmt.Println(authenticated.AccessToken)
fmt.Println(authenticated.RefreshToken)

Magic Code (Passwordless) Authentication

// Request magic code
err := guard.Authenticate.RequestMagicCode(ctx, tenantID, email)
if err != nil {
    log.Fatal(err)
}
// User receives email with magic code

// Authenticate with code
magicCode := "code-from-email"
authenticated, err := guard.Authenticate.MagicCode(ctx, tenantID, email, magicCode, clientID)
if err != nil {
    log.Fatal(err)
}

// Important: Must acknowledge after authentication
err = guard.Authenticate.Acknowledge(ctx, tenantID, authenticated)
if err != nil {
    log.Fatal(err)
}

Token Management

Validate Access Token

claims, err := guard.Authenticate.ValidateAccessToken(ctx, tenantID, authenticated.AccessToken)
if err != nil {
    log.Fatal(err)
}

fmt.Println(claims.TenantID)  // Tenant identifier
fmt.Println(claims.Subject)   // User email
fmt.Println(claims.Roles)     // User roles
fmt.Println(claims.ExpiresAt) // Token expiration
fmt.Println(claims.ClientID)  // Client identifier

Renew Access Token

newAuth, err := guard.Authenticate.Renew(ctx, tenantID, email, authenticated.RefreshToken)
if err != nil {
    log.Fatal(err)
}

fmt.Println(newAuth.AccessToken)
fmt.Println(newAuth.RefreshToken)

Revoke Session

err := guard.Authenticate.Revoke(ctx, tenantID, email, authenticated.AccessToken, clientID)
if err != nil {
    log.Fatal(err)
}

Testing

Tests require running services:

• bulwark-auth server at http://localhost:8080
• MailHog at http://localhost:8025

go test -v

License

MIT License - See LICENSE file for details