castle

README

castle-go

castle-go is a Go library wrapping the https://castle.io API.

Note: This library is currently a prototype. To see fully supported SDKs, please refer to https://docs.castle.io/baseline/

Install

go get github.com/utilitywarehouse/castle-go

Usage

Providing own http client

castle.NewWithHTTPClient("secret-api-key", &http.Client{Timeout: time.Second * 2})

Tracking properties and traits

castle.Track(
  castle.EventLoginSucceeded,
  "user-123",
  map[string]string{"prop1": "propValue1"},
  map[string]string{"trait1": "traitValue1"},
  castle.ContextFromRequest(req),
)

Tracking custom events

castle.Track(
  castle.Event("custom-event"),
  "user-123",
  map[string]string{"prop1": "propValue1"},
  map[string]string{"trait1": "traitValue1"},
  castle.ContextFromRequest(req),
)

Adaptive authentication

decision, err := castle.Authenticate(
  castle.EventLoginSucceeded,
  "md-1",
  map[string]string{"prop1": "propValue1"},
  map[string]string{"trait1": "traitValue1"},
  castle.ContextFromRequest(req),
)

Example

package main

import (
  "log"
  "net/http"

  "github.com/utilitywarehouse/castle-go"
)

func main() {

	cstl, err := castle.New("secret-api-key")

	if err != nil {
		log.Fatal(err)
	}

	http.ListenAndServe(":8080", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

		// authenticate user then track with castle

		decision, err := castle.AuthenticateSimple(
			castle.EventLoginSucceeded,
			"user-123",
			castle.ContextFromRequest(r),
		)

		if err != nil {
			log.Println(err)
		}

		if decision == castle.RecommendedActionChallenge {
			// challenge with MFA and track with castle

			err := cstl.TrackSimple(
				castle.EventChallengeRequested,
				"user-123",
				castle.ContextFromRequest(r),
			)

			if err != nil {
				log.Println(err)
			}

			// trigger off MFA path
		}

		w.WriteHeader(http.StatusNoContent)
	}))

}

Documentation

Index

• Constants
• Variables
• type AuthenticationRecommendedAction
• type Castle
  • func New(secret string) (*Castle, error)
  • func NewWithHTTPClient(secret string, client *http.Client) (*Castle, error)
  • func (c *Castle) Filter(context *Context, event Event, user User, properties map[string]string) error
  • func (c *Castle) Risk(context *Context, event Event, user User, properties map[string]string) (AuthenticationRecommendedAction, error)
  • func (c *Castle) SendFilterCall(e *castleAPIRequest) error
  • func (c *Castle) SendRiskCall(e *castleAPIRequest) (AuthenticationRecommendedAction, error)
• type Context
  • func ContextFromRequest(r *http.Request) *Context
• type Event
• type EventStatus
• type EventType
• type User
• type WebhookBody

Constants

const VERSION = "0.2.0"

VERSION - current package version

Variables

var FilterEndpoint = "https://api.castle.io/v1/filter"

FilterEndpoint defines the filter URL castle.io side

var HeaderAllowList = []string{
	"Accept",
	"Accept-Charset",
	"Accept-Datetime",
	"Accept-Encoding",
	"Accept-Language",
	"Cache-Control",
	"Connection",
	"Content-Length",
	"Content-Type",
	"Dnt",
	"Host",
	"Origin",
	"Pragma",
	"Referer",
	"Sec-Fetch-Dest",
	"Sec-Fetch-Mode",
	"Sec-Fetch-Site",
	"Sec-Fetch-User",
	"Te",
	"Upgrade-Insecure-Requests",
	"User-Agent",
	"X-Castle-Request-Token",
}

HeaderAllowList keeps a list of headers that will be forwarded to castle

var RiskEndpoint = "https://api.castle.io/v1/risk"

RiskEndpoint defines the risk URL castle.io side

Types

type AuthenticationRecommendedAction

type AuthenticationRecommendedAction string

AuthenticationRecommendedAction encapsulates the 3 possible responses from auth call (allow, challenge, deny)

const (
	RecommendedActionNone      AuthenticationRecommendedAction = ""
	RecommendedActionAllow     AuthenticationRecommendedAction = "allow"
	RecommendedActionChallenge AuthenticationRecommendedAction = "challenge"
	RecommendedActionDeny      AuthenticationRecommendedAction = "deny"
)

See https://castle.io/docs/authentication

type Castle

type Castle struct {
	// contains filtered or unexported fields
}

Castle encapsulates http client

func New

func New(secret string) (*Castle, error)

New creates a new castle client

func NewWithHTTPClient

func NewWithHTTPClient(secret string, client *http.Client) (*Castle, error)

NewWithHTTPClient same as New but allows passing of http.Client with custom config

func (*Castle) Filter

func (c *Castle) Filter(context *Context, event Event, user User, properties map[string]string) error

Filter sends a filter request to castle.io see https://reference.castle.io/#operation/filter for details

func (*Castle) Risk

func (c *Castle) Risk(
	context *Context,
	event Event,
	user User,
	properties map[string]string,
) (AuthenticationRecommendedAction, error)

Risk sends a risk request to castle.io see https://reference.castle.io/#operation/risk for details

func (*Castle) SendFilterCall

func (c *Castle) SendFilterCall(e *castleAPIRequest) error

SendFilterCall is a plumbing method constructing the HTTP req/res and interpreting results

func (*Castle) SendRiskCall

func (c *Castle) SendRiskCall(e *castleAPIRequest) (AuthenticationRecommendedAction, error)

SendRiskCall is a plumbing method constructing the HTTP req/res and interpreting results

type Context

type Context struct {
	IP           string            `json:"ip"`
	Headers      map[string]string `json:"headers"`
	RequestToken string            `json:"request_token"`
}

Context captures data from HTTP request

func ContextFromRequest

func ContextFromRequest(r *http.Request) *Context

ContextFromRequest builds castle context from current http.Request

type Event

type Event struct {
	EventType   EventType
	EventStatus EventStatus
}

type EventStatus

type EventStatus string

EventStatus is an enum defining the statuses for a given event.

const (
	EventStatusAttempted EventStatus = "$attempted"
	EventStatusSucceeded EventStatus = "$succeeded"
	EventStatusFailed    EventStatus = "$failed"
	EventStatusRequested EventStatus = "$requested"
)

See https://docs.castle.io/docs/events

type EventType

type EventType string

EventType is an enum defining types of event castle tracks

const (
	EventTypeLogin                EventType = "$login"
	EventTypeRegistration         EventType = "$registration"
	EventTypeProfileUpdate        EventType = "$profile_update"
	EventTypeProfileReset         EventType = "$profile_reset"
	EventTypePasswordResetRequest EventType = "$password_reset_request"
	EventTypeChallenge            EventType = "$challenge"
)

See https://docs.castle.io/docs/events

type User

type User struct {
	ID           string            `json:"id"`
	Email        string            `json:"email"`
	Phone        string            `json:"phone"`
	Name         string            `json:"name"`
	RegisteredAt string            `json:"registered_at"`
	Traits       map[string]string `json:"traits"`
}

type WebhookBody

type WebhookBody struct{}

WebhookBody encapsulates body of webhook notificationc coming from castle.io see https://castle.io/docs/webhooks