Documentation
¶
Overview ¶
Package claimrolemapping provides shared configuration types and constructor functions for building a PrincipalExtractor from claim-based role mapping rules. Services embed ExtractorConfig in their own config struct to share a consistent auth configuration surface.
Index ¶
- Constants
- func BuildExtractorConfig(mappings []ClaimRoleMappingConfig, logger zerolog.Logger) auth.DefaultExtractorConfig
- func BuildPrincipalExtractor(config ExtractorConfig, logger zerolog.Logger) auth.PrincipalExtractor
- func ValidateRoleMappings(mappings []ClaimRoleMappingConfig, knownRoles []string) []string
- type ClaimRoleMappingConfig
- type ExtractorConfig
Examples ¶
- BuildExtractorConfig
- BuildExtractorConfig (ArrayClaim)
- BuildExtractorConfig (FlyioEnvironment)
- BuildExtractorConfig (GithubActionsWorkflow)
- BuildExtractorConfig (MultipleRoles)
- BuildExtractorConfig (NoMatch)
- BuildExtractorConfig (SourceFiltering)
- BuildExtractorConfig (WildcardMatching)
- BuildPrincipalExtractor
- BuildPrincipalExtractor (AllowUnauthenticated)
- ValidateRoleMappings
Constants ¶
const ( SourceFlyio = "flyio" SourceGithubActions = "githubactions" SourceAWS = "aws" SourceOIDC = "oidc" SourceJWT = "jwt" )
Source name constants for use in ClaimRoleMappingConfig.Source.
Variables ¶
This section is empty.
Functions ¶
func BuildExtractorConfig ¶
func BuildExtractorConfig(mappings []ClaimRoleMappingConfig, logger zerolog.Logger) auth.DefaultExtractorConfig
BuildExtractorConfig constructs a per-source DefaultExtractorConfig from claim-role mapping rules. It emits Info-level startup logs for each configured source and a Warn when any rule has Debug enabled.
Example ¶
ExampleBuildExtractorConfig maps an AWS account to a role. AWS tokens expose the account as the claim "aws_account".
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{
Source: claimrolemapping.SourceAWS,
Claims: map[string]string{"aws_account": "123456789012"},
Role: "aws-prod",
},
}, zerolog.Nop())
roles := extractor.AWSMapper.MapRoles(map[string]any{
"aws_account": "123456789012",
"aws_principal_id": "AIDAJ12345EXAMPLE",
})
fmt.Println(roles)
}
Output: [aws-prod]
Example (ArrayClaim) ¶
ExampleBuildExtractorConfig_arrayClaim shows matching against an array claim such as a Keycloak "groups" claim: the rule matches when any element equals the required value.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{Claims: map[string]string{"groups": "platform-admins"}, Role: "admin"},
}, zerolog.Nop())
member := map[string]any{"groups": []any{"everyone", "platform-admins"}}
outsider := map[string]any{"groups": []any{"everyone"}}
fmt.Println("member:", extractor.OIDCMapper.MapRoles(member))
fmt.Println("outsider:", extractor.OIDCMapper.MapRoles(outsider))
}
Output: member: [admin] outsider: []
Example (FlyioEnvironment) ¶
ExampleBuildExtractorConfig_flyioEnvironment grants a role to every app in a Fly.io environment. The wildcard "*" accepts any non-empty value, so the rule also requires the claim to be present.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{
Source: claimrolemapping.SourceFlyio,
Claims: map[string]string{"environment": "production", "app_name": "*"},
Role: "prod-agent",
},
}, zerolog.Nop())
roles := extractor.FlyioMapper.MapRoles(map[string]any{
"environment": "production",
"app_name": "connect-server",
})
fmt.Println(roles)
}
Output: [prod-agent]
Example (GithubActionsWorkflow) ¶
ExampleBuildExtractorConfig_githubActionsWorkflow grants a deploy role to one repository's main branch. A rule with several claims needs all of them to match.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{
Source: claimrolemapping.SourceGithubActions,
Claims: map[string]string{"repository": "myorg/infrastructure", "ref": "refs/heads/main"},
Role: "deployer",
},
}, zerolog.Nop())
main := map[string]any{"repository": "myorg/infrastructure", "ref": "refs/heads/main"}
branch := map[string]any{"repository": "myorg/infrastructure", "ref": "refs/heads/feature"}
fmt.Println("main:", extractor.GithubActionsMapper.MapRoles(main))
fmt.Println("feature branch:", extractor.GithubActionsMapper.MapRoles(branch))
}
Output: main: [deployer] feature branch: []
Example (MultipleRoles) ¶
ExampleBuildExtractorConfig_multipleRoles shows that every rule is checked on its own: a token receives the role of each rule it satisfies.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{Claims: map[string]string{"environment": "production"}, Role: "prod"},
{Claims: map[string]string{"team": "*"}, Role: "team-member"},
}, zerolog.Nop())
roles := extractor.OIDCMapper.MapRoles(map[string]any{
"environment": "production",
"team": "backend",
})
fmt.Println(roles)
}
Output: [prod team-member]
Example (NoMatch) ¶
ExampleBuildExtractorConfig_noMatch shows that a token no rule matches gets no roles. It is not an error: the authorizer decides what no roles may do.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{Claims: map[string]string{"environment": "production"}, Role: "prod"},
}, zerolog.Nop())
roles := extractor.OIDCMapper.MapRoles(map[string]any{"environment": "development"})
fmt.Println(roles)
}
Output: []
Example (SourceFiltering) ¶
ExampleBuildExtractorConfig_sourceFiltering shows that a rule with a Source applies to that source only, so one claim name can mean different things for different providers. A rule with no Source applies to every source.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{Source: claimrolemapping.SourceFlyio, Claims: map[string]string{"environment": "production"}, Role: "prod"},
{Source: claimrolemapping.SourceAWS, Claims: map[string]string{"environment": "production"}, Role: "aws-prod"},
}, zerolog.Nop())
claims := map[string]any{"environment": "production"}
fmt.Println("Fly.io:", extractor.FlyioMapper.MapRoles(claims))
fmt.Println("AWS:", extractor.AWSMapper.MapRoles(claims))
fmt.Println("GitHub Actions:", extractor.GithubActionsMapper == nil)
}
Output: Fly.io: [prod] AWS: [aws-prod] GitHub Actions: true
Example (WildcardMatching) ¶
ExampleBuildExtractorConfig_wildcardMatching shows what "*" matches: any non-empty value, but not an absent claim.
package main
import (
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
extractor := claimrolemapping.BuildExtractorConfig([]claimrolemapping.ClaimRoleMappingConfig{
{Claims: map[string]string{"username": "deploy-sa", "team": "*"}, Role: "service-account"},
}, zerolog.Nop())
fmt.Println("exact user, any team:", extractor.OIDCMapper.MapRoles(map[string]any{"username": "deploy-sa", "team": "platform"}))
fmt.Println("other user:", extractor.OIDCMapper.MapRoles(map[string]any{"username": "deploy", "team": "platform"}))
fmt.Println("no team:", extractor.OIDCMapper.MapRoles(map[string]any{"username": "deploy-sa"}))
}
Output: exact user, any team: [service-account] other user: [] no team: []
func BuildPrincipalExtractor ¶
func BuildPrincipalExtractor(config ExtractorConfig, logger zerolog.Logger) auth.PrincipalExtractor
BuildPrincipalExtractor constructs a PrincipalExtractor from config. When AllowUnauthenticated is true it returns an allow-all extractor suitable for development. Otherwise it builds a proper extractor with per-source claim-to-role mapping.
Example ¶
ExampleBuildPrincipalExtractor is the production setup: claim-role mapping rules from configuration become a PrincipalExtractor. Here a Fly.io token that the JWT middleware validated has been stored in the context.
package main
import (
"context"
"fmt"
"github.com/auth0/go-jwt-middleware/v3/core"
jwtvalidator "github.com/auth0/go-jwt-middleware/v3/validator"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
"github.com/dioad/auth/oidc/flyio"
)
func main() {
extractor := claimrolemapping.BuildPrincipalExtractor(claimrolemapping.ExtractorConfig{
ClaimRoleMappings: []claimrolemapping.ClaimRoleMappingConfig{
{Source: claimrolemapping.SourceFlyio, Claims: map[string]string{"app_name": "connect-server"}, Role: "prod-agent"},
{Source: claimrolemapping.SourceAWS, Claims: map[string]string{"aws_account": "123456789012"}, Role: "aws-prod"},
},
}, zerolog.Nop())
ctx := core.SetClaims(context.Background(), &jwtvalidator.ValidatedClaims{
RegisteredClaims: jwtvalidator.RegisteredClaims{Subject: "machine-123"},
CustomClaims: &flyio.Claims{
AppID: "app-1",
AppName: "connect-server",
MachineID: "machine-123"},
})
principal, err := extractor.ExtractPrincipal(ctx)
if err != nil {
fmt.Println(err)
return
}
fmt.Println("principal:", principal.ID)
fmt.Println("source:", principal.Source)
fmt.Println("roles:", principal.Roles)
fmt.Println("service:", principal.IsService)
}
Output: principal: machine-123 source: flyio roles: [prod-agent] service: true
Example (AllowUnauthenticated) ¶
ExampleBuildPrincipalExtractor_allowUnauthenticated shows the development switch. It makes every request the anonymous principal, so it must never be set in production.
package main
import (
"context"
"fmt"
"github.com/rs/zerolog"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
allow := true
extractor := claimrolemapping.BuildPrincipalExtractor(claimrolemapping.ExtractorConfig{
AllowUnauthenticated: &allow,
}, zerolog.Nop())
principal, _ := extractor.ExtractPrincipal(context.Background())
fmt.Println(principal.ID, principal.IsAllowAll())
}
Output: unauthenticated true
func ValidateRoleMappings ¶ added in v0.7.0
func ValidateRoleMappings(mappings []ClaimRoleMappingConfig, knownRoles []string) []string
ValidateRoleMappings returns a warning string for each role name in mappings that does not appear in knownRoles. Call at application startup and log the results at Warn level to surface misconfigured claim-role mappings early.
knownRoles should include both canonical role names and alias names from the authoriser's PolicyMetadata (convert RoleCapabilities keys and RoleAliases keys to []string before calling).
Example ¶
ExampleValidateRoleMappings catches a rule that names a role the authorizer does not know, which would silently grant nothing.
package main
import (
"fmt"
"github.com/dioad/auth/claimrolemapping"
)
func main() {
warnings := claimrolemapping.ValidateRoleMappings([]claimrolemapping.ClaimRoleMappingConfig{
{Claims: map[string]string{"team": "*"}, Role: "team-member"},
{Claims: map[string]string{"team": "ops"}, Role: "operator"},
}, []string{"team-member", "admin"})
for _, w := range warnings {
fmt.Println(w)
}
}
Output: claim-role-mapping: unknown role operator — principals with this role may be denied; check your configuration
Types ¶
type ClaimRoleMappingConfig ¶
type ClaimRoleMappingConfig struct {
// Source restricts this mapping to a named PrincipalSource (e.g. "flyio",
// "aws"). Empty means match any source.
Source string `mapstructure:"source"`
// Claims maps claim keys to required values. A value of "*" matches any
// non-empty string.
Claims map[string]string `mapstructure:"claims"`
// Role is the internal role granted when all claim predicates match.
Role string `mapstructure:"role"`
// Debug enables per-request structured debug logging for this rule.
// Do not enable in production — evaluated claim values appear in the log output.
Debug bool `mapstructure:"debug"`
}
ClaimRoleMappingConfig maps a set of JWT claim predicates to an internal role, optionally restricted to a specific PrincipalSource. An empty Source matches any source.
type ExtractorConfig ¶
type ExtractorConfig struct {
// AllowUnauthenticated is a *bool, not a bool, so callers merging this
// config against a layered default (e.g. connect's per-service overrides)
// can tell "not set at this level" (nil) apart from an explicit false -
// a plain bool can't distinguish the two, which would let a true default
// silently override a service's explicit false.
AllowUnauthenticated *bool `mapstructure:"allow-unauthenticated"`
ClaimRoleMappings []ClaimRoleMappingConfig `mapstructure:"claim-role-mappings"`
}
ExtractorConfig is the common auth configuration for services that need JWT-based principal extraction with claim-to-role mapping. Embed this in a service config with the mapstructure ",squash" tag to preserve the flat YAML key structure.