Gated Security

Gated security is the first step up from open access. It protects inbound sentinel endpoints with OAuth2-based authentication, validating bearer tokens before granting access to the fabric.

Overview

In gated security mode, the sentinel validates JWT bearer tokens issued by an OAuth2/OIDC provider before allowing nodes to attach. This provides:

• Admission control: Only authenticated clients and agents can join
• Standard OAuth2/OIDC: Works with any provider (Auth0, Okta, Keycloak, etc.)
• No code changes: Enable by setting environment variables

What gated security provides:

Architecture

Flow:

1. Client/Agent requests a token from the OAuth2 server (client credentials flow)
2. Caddy terminates TLS and forwards the connection
3. Sentinel validates the JWT bearer token against the OAuth2 server’s JWKS
4. On success, the node is allowed to attach to the fabric

Configuration

Enable gated security by setting these environment variables:

Sentinel Configuration

# Security profile
FAME_SECURITY_PROFILE=gated
 
# JWT validation settings
FAME_JWT_TRUSTED_ISSUER=https://your-oauth2-server.com
FAME_JWT_AUDIENCE=fame.fabric
FAME_JWT_JWKS_URL=https://your-oauth2-server.com/.well-known/jwks.json

Agent/Client Configuration

# Admission profile
FAME_ADMISSION_PROFILE=direct
 
# OAuth2 client credentials
FAME_ADMISSION_TOKEN_URL=https://your-oauth2-server.com/oauth/token
FAME_ADMISSION_CLIENT_ID=your-client-id
FAME_ADMISSION_CLIENT_SECRET=your-client-secret
 
# Where to connect
FAME_DIRECT_ADMISSION_URL=wss://your-sentinel.com/fame/v1/attach/ws/downstream

OAuth2 Providers

Gated security works with any OAuth2/OIDC provider that supports:

• Client credentials flow (for machine-to-machine)
• JWKS endpoint (for token validation)
• Standard JWT claims (iss, aud, exp)

Provider Examples

Browser Clients (PKCE)

For browser-based clients, use the PKCE flow instead of client credentials:

// Browser client uses PKCE for OAuth2
const authConfig = {
  authority: 'https://your-oauth2-server.com',
  clientId: 'your-spa-client-id',
  redirectUri: window.location.origin + '/callback',
  scope: 'openid profile',
};

The security examples include a complete browser client demonstrating PKCE authentication.

What Gated Security Does NOT Provide

Gated security focuses on admission control only. It does not provide:

When to Use Gated Security

Good fit:

• Simple authentication requirements
• Single-tenant deployments
• Development and staging environments
• When TLS is sufficient for your threat model

Consider alternatives when:

• You need to verify message origin (use Overlay)
• You need audit trails with cryptographic proof (use Overlay)
• You need end-to-end encryption (use Advanced)
• You have multi-tenant or zero-trust requirements (use Advanced)

Running the Example

Complete runnable examples are available in both repositories:

# TypeScript
cd naylence-examples-ts/examples/security/gated
make start    # Start all services
make run      # Run the client
 
# Python
cd naylence-examples-python/examples/security/gated
make start    # Start all services
make run      # Run the client

What the Example Includes

• Caddy: TLS reverse proxy with automatic certificates
• OAuth2 Server: Development-only token issuer (do NOT use in production)
• Sentinel: Configured with FAME_SECURITY_PROFILE=gated
• Math Agent: Connects using OAuth2 client credentials
• Client: Fetches token and makes RPC calls

Example Output

7
42
0 1 1 2 3 5 8 13 21 34

Next Steps

• Need message integrity? → Overlay Security
• Need cryptographic identity? → Advanced Security
• Back to overview → Security