BeamFoundry Rays Web Security

1. Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction & Architecture

Securing enterprise applications often leads to messy, scattered middleware across various routers. Rays Web Security centralizes this logic into declarative Security Filter Chains.

Core Architectural Features

Declarative Authorization: Define endpoint security rules using a highly expressive HttpSecurityBuilder rather than imperative if/else blocks inside your handlers.
Pluggable Authentication: Easily swap out how users are authenticated by implementing the AuthenticationProvider or UserDetailsService interfaces.
ThreadLocal Context: Web Security utilizes github.com/timandy/routine to store the currently authenticated user in a ThreadLocal SecurityContext. Your deeper service layers can retrieve the user without needing the HTTP request object passed down.
IoC Native Auto-Configuration: The framework provides default security implementations out of the box, which you can easily override by defining your own Beams.

📦 Package Structure & Imports

To prevent circular dependencies and maintain clean boundaries, Rays Web Security is split into distinct packages:

Basic Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Basic Authentication

For APIs and simple services without a frontend interface, you will typically use Basic Authentication (passing credentials via the HTTP Authorization header).

You can enable this by calling the Basic() method on the HttpSecurityBuilder before building the final security configuration.

package configurations

import (
 . "github.com/BeamFoundry/rays-web-security/pkg/config"
 . "github.com/BeamFoundry/rays/pkg/core"
)

type BasicSecurityConfig struct {
 Configuration
}

// The HttpSecurity Beam provider. 
func (this *BasicSecurityConfig) HttpSecurity() *HttpSecurity {
 return (&HttpSecurityBuilder{}).
 AuthorizedHTTPRequests().
 Paths("/api/public/**").PermitAll().
 AnyRequest().Authenticated().
 And().
 Basic(). // Secure all authenticated endpoints via BasicAuth
 Build()
}

var _, _ = any(&BasicSecurityConfig{}).(Stereotype)

UserDetails Interface

Mon, 01 Jan 0001 00:00:00 +0000

1. The `UserDetails` Interface

First, adapt your domain model to fulfill the framework’s UserDetails interface, located in pkg/core.

Note that the framework provides a convenient Authority string alias to easily generate GrantedAuthority slice elements.

package models

import . "github.com/BeamFoundry/rays-web-security/pkg/core"

type User struct {
 ID uint
 Email string
 PasswordHash string
 Role string
}

// Implement the UserDetails interface
func (u *User) GetUsername() string { return u.Email }
func (u *User) GetPassword() string { return u.PasswordHash }
func (u *User) GetAuthorities() []GrantedAuthority {
 return []GrantedAuthority{ Authority("ROLE_" + u.Role) }
}

// These return false when the account is active and unrestricted
func (u *User) IsExpired() bool { return false }
func (u *User) IsCredentialExpired() bool { return false }
func (u *User) IsDisabled() bool { return false }
func (u *User) IsLocked() bool { return false }

2. Quickstart & Setup

Mon, 01 Jan 0001 00:00:00 +0000

Quickstart & Setup

To secure your application, you need to construct an HttpSecurity Beam. This tells the framework which endpoints require authentication and which are public.

📦 Installation

go get github.com/BeamFoundry/rays-web-security

The Minimal Security Configuration

Here is a basic configuration that uses Basic Authentication and secures all endpoints except for the public login and health-check routes.

Note: The framework automatically provisions a default PasswordEncoder, so you don’t even need to define one to get started!

Form Login

Mon, 01 Jan 0001 00:00:00 +0000

If you are building a traditional web application with server-rendered HTML views (instead of a stateless API), you will likely want to use Form Login instead of Basic Authentication.

The FormLogin() builder exposes several methods to fully customize the authentication flow.

Configuration Defaults

If you call .FormLogin() without any additional chained configuration, the framework applies the following defaults automatically:

Method	Default Value	Description
`Username()`	“username”	The HTML form field name for the user’s username.
`Password()`	“password”	The HTML form field name for the user’s password.
`LoginPath()`	“/login”	The path where the login hook is registered.
`LogoutPath()`	“/logout”	The path where the logout hook is registered.
`ViewName()`	“login”	The template view name rendered for the login form.
`DefaultSuccessURL()`	“/”	The default URL to redirect to upon successful login.

You can selectively override any of these defaults, serve a specific login view, and optionally integrate a RememberMeService:

UserDetailsService

Mon, 01 Jan 0001 00:00:00 +0000

2. Implementing `UserDetailsService`

Next, create a Service that implements UserDetailsService. The framework will automatically detect this Beam and use it during the login process.

If the user cannot be found, you simply return nil, and the framework will handle the failed authentication safely.

package security

import (
 . "github.com/BeamFoundry/rays-web-security/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/lang"
)

type DomainUserDetailsService struct {
 Service
 userRepo *UserRepository `@:"Inject"`
}

func (s *DomainUserDetailsService) LoadUserByUsername(username string) UserDetails {
 userOpt := s.userRepo.FindByEmail(username)

 // Return the user if found
 if user, ok := userOpt.Get(); ok {
 return user
 }

 // Return nil if the user does not exist
 return nil
}

Password Encoding

Mon, 01 Jan 0001 00:00:00 +0000

3. Password Encoding

Never store plain-text passwords. When you boot the application, internal/autoconfig automatically registers a highly secure, upgradeable default PasswordEncoder.

The Delegating Password Encoder

To support seamless algorithm migrations over time (a best practice from Spring Security), the default encoder is a DelegatingPasswordEncoder.

It automatically wraps a BCryptPasswordEncoder (with a cost of 10) mapped to the “bcrypt” prefix. This means your hashed passwords will automatically be formatted with a prefix, looking something like this: {bcrypt}$2a$10$wN1FzZ2...

Stateless APIs

Mon, 01 Jan 0001 00:00:00 +0000

Stateless vs. Stateful Sessions

By default, Rays Web Security assumes you are building a stateful web application (using session cookies). If you are building a modern API (e.g., React, Vue, Mobile App) that uses stateless tokens, you must tell the framework to operate in a stateless manner.

You can do this by using the Csrf().Disable() and SessionCreationPolicy() builder methods.

Session Creation Policies

The SessionCreationPolicy() builder provides several options to control when the framework provisions a session:

Custom Filters

Mon, 01 Jan 0001 00:00:00 +0000

Custom Filters

While Rays Web Security provides robust out-of-the-box mechanisms like Form Login and Basic Authentication, you may occasionally need to implement proprietary authentication flows (e.g., verifying a specific API key header, an internal SSO token, or an OAuth JWT).

You can inject your own security logic directly into the request lifecycle using the AddCustomFilter() method on the builder.

Important: Custom filters are always evaluated before global filters (like BasicAuth or FormLogin).

Remember Me

Mon, 01 Jan 0001 00:00:00 +0000

4. Remember Me Services

To keep users logged in across browser sessions without relying solely on long-lived session cookies, you can leverage the RememberMeService interface.

The framework provides a TokenBasedRememberMeService in pkg/rememberme. For a robust enterprise configuration, you should avoid hardcoding secrets and instead use Rays’ ConfigurationProperties to load your configuration from YAML.

Configuration Options & Defaults

The TokenBasedRememberMeService provides several fluent builder methods to customize its behavior:

Method	Default Value	Description
`WithParameter()`	“remember-me”	The HTML form input checked to determine if the cookie should be set.
`WithCookieName()`	“remember-me”	The name of the cookie sent to the browser.
`WithCookieDomain()`	""	The domain restriction for the cookie.
`WithCookieSecure()`	false	Whether the secure (HTTPS-only) bit should be set on the cookie.
`WithValidity()`	1209600 (14 days)	How long, in seconds, the cookie will be valid.

Example: Externalized Configuration

First, define your YAML configuration. We explicitly provide the default values here for reference:

5. Security Context

Mon, 01 Jan 0001 00:00:00 +0000

The Security Context

One of the biggest challenges in Go web development is accessing the authenticated user deep within your service layer. Often, developers resort to passing the user object or the HTTP Request context through dozens of function calls.

Rays Web Security solves this using github.com/timandy/routine to establish a ThreadLocal SecurityContext within its internal implementations.

Accessing the Authenticated User

Whenever an authenticated request is being processed, the framework automatically binds the Authentication object to the current goroutine.

6. Testing

Mon, 01 Jan 0001 00:00:00 +0000

Testing

Testing secured applications often requires mocking the user database so you don’t have to spin up a real database just to test authorization logic. To complement the core Rays testing framework, Rays Web Security provides a pkg/testing package containing in-memory implementations.

The InMemoryUserDetailsManager

The InMemoryUserDetailsManager allows you to rapidly configure a UserDetailsService populated with test users. It automatically encodes the plaintext passwords you provide using the injected PasswordEncoder.

These users are stored as InMemoryUser structs, which fully implement the UserDetails interface.

BeamFoundry Rays Web Security

1. Introduction

Introduction & Architecture

Core Architectural Features

📦 Package Structure & Imports

Basic Authentication

Basic Authentication

UserDetails Interface

1. The UserDetails Interface

2. Quickstart & Setup

Quickstart & Setup

📦 Installation

The Minimal Security Configuration

Form Login

Form Login & Remember Me

Configuration Defaults

UserDetailsService

2. Implementing UserDetailsService

Password Encoding

3. Password Encoding

The Delegating Password Encoder

Stateless APIs

Stateless vs. Stateful Sessions

Session Creation Policies

Custom Filters

Custom Filters

Remember Me

4. Remember Me Services

Configuration Options & Defaults

Example: Externalized Configuration

5. Security Context

The Security Context

Accessing the Authenticated User

6. Testing

Testing

The InMemoryUserDetailsManager

1. The `UserDetails` Interface

2. Implementing `UserDetailsService`