Documentation
¶
Overview ¶
Package rbacconnect provides a flexible, declarative Role-Based Access Control (RBAC) system for connect-go RPC services.
Overview ¶
rbacconnect enables fine-grained authorization for connect-go services through a declarative policy builder. It supports multiple levels of selectors (procedure, service, package, default), super-roles, allow/deny rules, and atomic policy updates.
Quick Start ¶
Define a policy:
policy := rbacconnect.NewPolicyBuilder().
WithSuperRoles("root").
WithDefaultAllow(false).
When(rbacconnect.Proc("/api.UserService/GetUser")).
Allow("admin", "user").
When(rbacconnect.Svc("api.AdminService")).
Allow("admin").
Build()
Create an interceptor:
provider := rbacconnect.NewProvider(policy)
interceptor := rbacconnect.NewInterceptor(provider, rbacconnect.Options{})
Add to your connect-go server:
mux.Handle(yourservice.NewHandler(
&yourServer{},
connect.WithInterceptors(interceptor),
))
Policy Structure ¶
Policies are built using a fluent API with the following components:
- Super-Roles: Roles that bypass all rules (e.g., "root", "superadmin")
- Selectors: Define the scope of rules (Procedure, Service, Package, or Default)
- Rules: Allow or Deny specific roles (Deny takes precedence)
- Default Behavior: What happens when no rules match
Rule Evaluation Order ¶
Rules are evaluated in order of specificity:
- Super-Roles (always allowed)
- Procedure-level rules (most specific)
- Service-level rules
- Package-level rules
- Default rule
- Fallback to WithDefaultAllow setting
Within each level, Deny takes precedence over Allow.
Selectors ¶
Four types of selectors are available:
- Proc(procedure): Match exact procedure like "/api.UserService/GetUser"
- Svc(service): Match all procedures in a service like "api.UserService"
- Pkg(package): Match all procedures in a package like "api"
- Any(): Match everything (default rule)
Hot Reloading ¶
Policies can be updated atomically without service restart:
newPolicy := rbacconnect.NewPolicyBuilder().
WithSuperRoles("root", "admin").
Build()
provider.Update(newPolicy)
Custom Role Extraction ¶
Implement RoleExtractor to customize how roles are extracted from context:
interceptor := rbacconnect.NewInterceptor(provider, rbacconnect.Options{
RoleExtractor: rbacconnect.RoleExtractorFunc(func(ctx context.Context) ([]rbacconnect.Role, error) {
// Extract roles from JWT, session, etc.
return extractRolesFromJWT(ctx)
}),
})
Thread Safety ¶
All components are thread-safe. The Provider uses atomic operations for policy updates, ensuring no race conditions during hot-reloads.
Best Practices ¶
- Use WithDefaultAllow(false) for fail-closed security
- Grant minimum necessary permissions (principle of least privilege)
- Use explicit Deny for critical restrictions
- Test policies thoroughly with unit tests
- Log authorization decisions for security auditing
- Version control your policies
File Organization ¶
The package is organized into logical files:
- rbacconnect.go: Core types (Role, Selector, Rule, Policy)
- builder.go: PolicyBuilder and fluent API
- interceptor.go: Connect-go integration
- context.go: Context helpers and role extraction
- provider.go: Atomic policy provider
- helpers.go: Utility functions for common patterns
- utils.go: Internal utilities
For more examples and detailed documentation, see the README.md file.
Package rbacconnect provides a flexible, declarative Role-Based Access Control (RBAC) system for connect-go RPC services. It allows you to define fine-grained authorization rules based on procedures, services, packages, or default policies, with support for super-roles and dynamic policy updates.
Key Features:
- Declarative policy builder with fluent API
- Multiple selector levels: Procedure > Service > Package > Default
- Super-roles that bypass all rules
- Allow/Deny rules with deny precedence
- Thread-safe atomic policy updates
- Connect-go interceptor integration
Example usage:
policy := rbacconnect.NewPolicyBuilder().
WithSuperRoles("root").
WithDefaultAllow(false).
When(rbacconnect.Proc("/api.UserService/GetUser")).
Allow("admin", "user").
When(rbacconnect.Svc("api.AdminService")).
Allow("admin").
When(rbacconnect.Pkg("api")).
Deny("guest").
Build()
provider := rbacconnect.NewProvider(policy)
interceptor := rbacconnect.NewInterceptor(provider, rbacconnect.Options{})
Index ¶
- func AllowPackages(b *PolicyBuilder, role Role, packages ...string)
- func AllowProcs(b *PolicyBuilder, role Role, procs ...string)
- func AllowServices(b *PolicyBuilder, role Role, services ...string)
- func DenyPackages(b *PolicyBuilder, role Role, packages ...string)
- func DenyProcs(b *PolicyBuilder, role Role, procs ...string)
- func DenyServices(b *PolicyBuilder, role Role, services ...string)
- func SplitProc(proc string) (svc string, pkg string)
- func WithRoles(ctx context.Context, roles ...Role) context.Context
- type Decision
- type Err
- type Interceptor
- type Options
- type Policy
- type PolicyBuilder
- type Provider
- type Role
- type RoleExtractor
- type RoleExtractorFunc
- type RoleSet
- type Rule
- type Selector
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllowPackages ¶
func AllowPackages(b *PolicyBuilder, role Role, packages ...string)
AllowPackages adds allow rules for all procedures of the specified packages and role.
func AllowProcs ¶
func AllowProcs(b *PolicyBuilder, role Role, procs ...string)
AllowProcs adds allow rules for the specified procedures and role.
func AllowServices ¶
func AllowServices(b *PolicyBuilder, role Role, services ...string)
AllowServices adds allow rules for all procedures of the specified services and role.
func DenyPackages ¶
func DenyPackages(b *PolicyBuilder, role Role, packages ...string)
DenyPackages adds deny rules for all procedures of the specified packages and role.
func DenyProcs ¶
func DenyProcs(b *PolicyBuilder, role Role, procs ...string)
DenyProcs adds deny rules for the specified procedures and role.
func DenyServices ¶
func DenyServices(b *PolicyBuilder, role Role, services ...string)
DenyServices adds deny rules for all procedures of the specified services and role.
func WithRoles ¶
WithRoles adds roles to the context.
Example ¶
Example 6: Using context helpers
ctx := context.Background()
// Add roles to context
ctx = WithRoles(ctx, "admin", "user")
// Extract roles from context
roles, ok := RolesFromContext(ctx)
if ok {
println("Roles:", roles) // ["admin", "user"]
}
Types ¶
type Decision ¶
type Decision struct {
Allowed bool
Selector string // which level matched: "procedure"|"service"|"package"|"default"|"none"
Matched string // which name matched
Reason string // description for logging
}
Decision represents the result of an authorization check.
type Interceptor ¶
type Interceptor struct {
// contains filtered or unexported fields
}
Interceptor is a connect-go interceptor that enforces RBAC policies.
Example (WithConnectService) ¶
Example 8: Integration with connect-go service
// Create policy
policy := NewPolicyBuilder().
WithSuperRoles("root").
WithDefaultAllow(false).
When(Pkg("greet.v1")).
Allow("user").
Build()
provider := NewProvider(policy)
_ = NewInterceptor(provider, Options{})
// Create HTTP handler with interceptor
mux := http.NewServeMux()
// In real code, use your actual service handler:
// mux.Handle(greetv1connect.NewGreetServiceHandler(
// &greetServer{},
// connect.WithInterceptors(interceptor),
// ))
// Start server
_ = httptest.NewServer(mux)
func NewInterceptor ¶
func NewInterceptor(provider *Provider, opts Options) *Interceptor
NewInterceptor creates a new RBAC interceptor with the given provider and options. If options are not provided, sensible defaults are used.
Example (CustomErrorFactory) ¶
Example 10: Custom error factory
policy := NewPolicyBuilder().
WithDefaultAllow(false).
Build()
provider := NewProvider(policy)
interceptor := NewInterceptor(provider, Options{
ErrorFactory: func(code connect.Code, msg string) error {
// Custom error with additional context
return connect.NewError(code, errors.New(msg+" - contact support"))
},
})
_ = interceptor
Example (CustomRoleExtractor) ¶
Example 5: Custom role extractor
policy := NewPolicyBuilder().
WithDefaultAllow(false).
When(Any()).
Allow("admin").
Build()
provider := NewProvider(policy)
// Custom role extractor from HTTP headers
extractorFromHeader := RoleExtractorFunc(func(ctx context.Context) ([]Role, error) {
// In real scenario, extract from actual context
header := ctx.Value("X-User-Roles")
if header == nil {
return nil, errors.New("no roles header")
}
// Parse roles from header
rolesStr, ok := header.(string)
if !ok {
return nil, errors.New("invalid roles")
}
return []string{rolesStr}, nil
})
_ = NewInterceptor(provider, Options{
RoleExtractor: extractorFromHeader,
})
func (*Interceptor) WrapStreamingClient ¶
func (i *Interceptor) WrapStreamingClient(next connect.StreamingClientFunc) connect.StreamingClientFunc
WrapStreamingClient wraps client-side streaming calls. By default, client streams are not restricted.
func (*Interceptor) WrapStreamingHandler ¶
func (i *Interceptor) WrapStreamingHandler(next connect.StreamingHandlerFunc) connect.StreamingHandlerFunc
WrapStreamingHandler wraps server-side streaming calls with RBAC authorization.
type Options ¶
type Options struct {
// RoleExtractor extracts roles from the request context.
RoleExtractor RoleExtractor
// SpecSplitter parses connect.Spec into (proc, svc, pkg).
// Default implementation parses "/pkg.Service/Method" format.
SpecSplitter func(spec connect.Spec) (proc string, svc string, pkg string)
// ErrorFactory creates custom errors (PermissionDenied/Unauthenticated).
ErrorFactory func(code connect.Code, msg string) error
}
Options configures the Interceptor behavior.
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy is a set of RBAC rules. Can be updated atomically.
type PolicyBuilder ¶
type PolicyBuilder struct {
// contains filtered or unexported fields
}
PolicyBuilder is a convenient builder for declarative policies.
Example (Basic) ¶
Example 1: Basic policy with super-roles
policy := NewPolicyBuilder().
WithSuperRoles("root").
WithDefaultAllow(false).
When(Proc("/api.UserService/GetUser")).
Allow("admin", "user").
Build()
// Evaluate for admin role
decision := policy.Evaluate("/api.UserService/GetUser", "api.UserService", "api", []string{"admin"})
println(decision.Allowed) // true
Example (DenyRules) ¶
Example 3: Package-level with deny rules
policy := NewPolicyBuilder().
WithDefaultAllow(false).
// Allow users to access the package
When(Pkg("api")).
Allow("user", "admin").
// But deny users from specific dangerous operations
When(Proc("/api.UserService/DeleteUser")).
Deny("user").
Build()
// User can read
decision := policy.Evaluate("/api.UserService/GetUser", "api.UserService", "api", []string{"user"})
println(decision.Allowed) // true
// User cannot delete (deny takes precedence)
decision = policy.Evaluate("/api.UserService/DeleteUser", "api.UserService", "api", []string{"user"})
println(decision.Allowed) // false
Example (MultiLevel) ¶
Example 9: Multi-level authorization
policy := NewPolicyBuilder().
WithDefaultAllow(false).
// Package level - all users can access public APIs
When(Pkg("api.public")).
Allow("guest", "user", "admin").
// Service level - only registered users for private APIs
When(Svc("api.private.UserService")).
Allow("user", "admin").
// Procedure level - only admins for dangerous operations
When(Proc("/api.private.UserService/DeleteAll")).
Allow("admin").
// Default - admins get everything else
When(Any()).
Allow("admin").
Build()
// Guest can access public
d := policy.Evaluate("/api.public.InfoService/GetInfo", "api.public.InfoService", "api.public", []string{"guest"})
println("Guest public:", d.Allowed) // true
// Guest cannot access private
d = policy.Evaluate("/api.private.UserService/GetProfile", "api.private.UserService", "api.private", []string{"guest"})
println("Guest private:", d.Allowed) // false
// User can access private
d = policy.Evaluate("/api.private.UserService/GetProfile", "api.private.UserService", "api.private", []string{"user"})
println("User private:", d.Allowed) // true
// User cannot delete all
d = policy.Evaluate("/api.private.UserService/DeleteAll", "api.private.UserService", "api.private", []string{"user"})
println("User delete:", d.Allowed) // false
// Admin can delete all
d = policy.Evaluate("/api.private.UserService/DeleteAll", "api.private.UserService", "api.private", []string{"admin"})
println("Admin delete:", d.Allowed) // true
Example (Service) ¶
Example 2: Service-level authorization
policy := NewPolicyBuilder().
WithDefaultAllow(false).
When(Svc("api.UserService")).
Allow("user").
When(Svc("api.AdminService")).
Allow("admin").
Build()
// User can access UserService
decision := policy.Evaluate("/api.UserService/GetUser", "api.UserService", "api", []string{"user"})
println(decision.Allowed) // true
// User cannot access AdminService
decision = policy.Evaluate("/api.AdminService/DeleteUser", "api.AdminService", "api", []string{"user"})
println(decision.Allowed) // false
func NewPolicyBuilder ¶
func NewPolicyBuilder() *PolicyBuilder
NewPolicyBuilder creates a new policy builder with empty rules.
func (*PolicyBuilder) Build ¶
func (b *PolicyBuilder) Build() *Policy
Build finalizes the policy construction and returns the immutable Policy.
func (*PolicyBuilder) When ¶
func (b *PolicyBuilder) When(s Selector) *clause
When starts a new rule clause for the given selector. Returns a clause that can be chained with Allow() and Deny() calls.
func (*PolicyBuilder) WithDefaultAllow ¶
func (b *PolicyBuilder) WithDefaultAllow(v bool) *PolicyBuilder
WithDefaultAllow sets the default behavior when no rules match. If true, access is allowed by default. If false, access is denied by default.
func (*PolicyBuilder) WithSuperRoles ¶
func (b *PolicyBuilder) WithSuperRoles(roles ...Role) *PolicyBuilder
WithSuperRoles adds super-roles that bypass all authorization rules. Super-roles are always granted access regardless of any rules.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is a thread-safe atomic policy provider for "hot" updates. It allows updating the policy without restarting the service.
Example (Update) ¶
Example 4: Hot-reloading policies
// Initial policy
initialPolicy := NewPolicyBuilder().
WithDefaultAllow(false).
When(Any()).
Allow("admin").
Build()
provider := NewProvider(initialPolicy)
// Check with initial policy
policy := provider.Get()
decision := policy.Evaluate("/any/Procedure", "any.Service", "any", []string{"user"})
println(decision.Allowed) // false
// Update policy
newPolicy := NewPolicyBuilder().
WithDefaultAllow(false).
When(Any()).
Allow("admin", "user"). // now users are allowed
Build()
provider.Update(newPolicy)
// Check with new policy
policy = provider.Get()
decision = policy.Evaluate("/any/Procedure", "any.Service", "any", []string{"user"})
println(decision.Allowed) // true
func NewProvider ¶
NewProvider creates a new Provider with the given initial policy.
type Role ¶
type Role = string
Role represents a user role as a string. Roles are used to determine access permissions in the RBAC system.
type RoleExtractor ¶
RoleExtractor defines how to extract roles from a context. Users can provide their own implementation.
type RoleExtractorFunc ¶
RoleExtractorFunc is a function adapter for RoleExtractor interface.
func (RoleExtractorFunc) ExtractRoles ¶
func (f RoleExtractorFunc) ExtractRoles(ctx context.Context) ([]Role, error)
ExtractRoles implements the RoleExtractor interface.
type RoleSet ¶
type RoleSet map[Role]struct{}
RoleSet is a set of roles implemented as a map for efficient lookup.
func NewRoleSet ¶
NewRoleSet creates a new RoleSet from the provided roles.
type Rule ¶
Rule represents allow/deny permissions for roles. If a role is in Deny, it takes precedence over Allow.
type Selector ¶
type Selector struct {
// Procedure is the full procedure name like "/pkg.Service/Method".
Procedure string
// Service is the service name like "pkg.Service".
Service string
// Package is the package name like "pkg".
Package string
// Default indicates a default rule (when nothing else matches).
Default bool
}
Selector defines the scope of a rule application. Specificity order: Procedure > Service > Package > Default.