claimrolemapping

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

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

Examples

Constants

View Source
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL