4. Security Chains on BeamFoundry Rays Web Security

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)

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:

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).

4. Security Chains on BeamFoundry Rays Web Security

Basic Authentication

Basic Authentication

Form Login

Form Login & Remember Me

Configuration Defaults

Stateless APIs

Stateless vs. Stateful Sessions

Session Creation Policies

Custom Filters

Custom Filters