chore: add gRPC authorization support and upgrade go-authx to v1.2.0

Author: Christian

README.md

@@ -128,6 +128,9 @@ Environment-based configuration:
 - `AUTH_INTROSPECTION_PRIVATE_KEY_FILE` - Alternative file path for `AUTH_INTROSPECTION_PRIVATE_KEY` (mutually exclusive)
 - `AUTH_INTROSPECTION_PRIVATE_KEY_JWT_KID` - Optional JWT header `kid` override for `private_key_jwt`
 - `AUTH_INTROSPECTION_PRIVATE_KEY_JWT_ALG` - Optional signing alg override (`RS256` or `ES256`)
+- `AUTHZ_REQUIRED_ROLES` / `AUTHZ_REQUIRED_SCOPES` - Optional required roles/scopes (comma-separated); enables authorization checks when set
+- `AUTHZ_ROLE_MATCH_MODE` / `AUTHZ_SCOPE_MATCH_MODE` - Matching mode for required roles/scopes (`any` or `all`; default: `any`)
+- `AUTHZ_ROLE_CLAIM_PATHS` / `AUTHZ_SCOPE_CLAIM_PATHS` - Optional claim paths (comma-separated, dot-notation supported) used for role/scope extraction
 - `TLS_ENABLED` - Enable TLS for the gRPC server (default: false)
 - `TLS_CERT_FILE` / `TLS_KEY_FILE` - Server certificate and key (required when TLS is enabled)
 - `TLS_CA_FILE` - Optional CA bundle for client cert verification (mTLS)

cmd/server/main.go

@@ -247,17 +247,59 @@ func buildUnaryInterceptors(cfg *config.Config) ([]grpc.UnaryServerInterceptor,
 		Str("introspection_auth_method", cfg.AuthIntrospectionAuthMethod).
 		Msg("gRPC authentication enabled")
 
-	authInterceptor := grpcserver.UnaryServerInterceptor(
-		validator,
+	policy := buildAuthorizationPolicy(cfg)
+	interceptorOptions := []grpcserver.InterceptorOption{
+		grpcserver.WithAuthorizationPolicy(policy),
 		grpcserver.WithExemptMethods(
 			"/grpc.health.v1.Health/Check",
 			"/grpc.health.v1.Health/Watch",
 		),
+	}
+
+	if authorizationEnabled(cfg) {
+		log.Info().
+			Strs("required_roles", cfg.AuthzRequiredRoles).
+			Strs("required_scopes", cfg.AuthzRequiredScopes).
+			Str("role_match_mode", cfg.AuthzRoleMatchMode).
+			Str("scope_match_mode", cfg.AuthzScopeMatchMode).
+			Strs("role_claim_paths", cfg.AuthzRoleClaimPaths).
+			Strs("scope_claim_paths", cfg.AuthzScopeClaimPaths).
+			Msg("gRPC authorization enabled")
+	}
+
+	authInterceptor := grpcserver.UnaryServerInterceptor(
+		validator,
+		interceptorOptions...,
 	)
 
 	return append(interceptors, authInterceptor), nil
 }
 
+func buildAuthorizationPolicy(cfg *config.Config) grpcserver.AuthorizationPolicy {
+	roleMatchMode := grpcserver.RoleMatchModeAny
+	if cfg.AuthzRoleMatchMode == "all" {
+		roleMatchMode = grpcserver.RoleMatchModeAll
+	}
+
+	scopeMatchMode := grpcserver.ScopeMatchModeAny
+	if cfg.AuthzScopeMatchMode == "all" {
+		scopeMatchMode = grpcserver.ScopeMatchModeAll
+	}
+
+	return grpcserver.AuthorizationPolicy{
+		RequiredRoles:   cfg.AuthzRequiredRoles,
+		RequiredScopes:  cfg.AuthzRequiredScopes,
+		RoleMatchMode:   roleMatchMode,
+		ScopeMatchMode:  scopeMatchMode,
+		RoleClaimPaths:  cfg.AuthzRoleClaimPaths,
+		ScopeClaimPaths: cfg.AuthzScopeClaimPaths,
+	}
+}
+
+func authorizationEnabled(cfg *config.Config) bool {
+	return len(cfg.AuthzRequiredRoles) > 0 || len(cfg.AuthzRequiredScopes) > 0
+}
+
 // buildGRPCServerOptions assembles gRPC server options from configuration. When TLS
 // is enabled, it constructs TLS credentials from the configured certificate, key,
 // optional CA file, client authentication mode, and minimum TLS version.

cmd/server/main_test.go

@@ -156,6 +156,37 @@ func TestBuildUnaryInterceptorsWithOpaqueAuthPrivateKeyJWTZitadelJSON(t *testing
 	}
 }
 
+func TestBuildAuthorizationPolicy(t *testing.T) {
+	cfg := &config.Config{
+		AuthzRequiredRoles:   []string{"NIST_ROLE"},
+		AuthzRequiredScopes:  []string{"openid", "profile"},
+		AuthzRoleMatchMode:   "all",
+		AuthzScopeMatchMode:  "any",
+		AuthzRoleClaimPaths:  []string{"roles", "realm_access.roles"},
+		AuthzScopeClaimPaths: []string{"scope", "scp"},
+	}
+
+	policy := buildAuthorizationPolicy(cfg)
+	if len(policy.RequiredRoles) != 1 || policy.RequiredRoles[0] != "NIST_ROLE" {
+		t.Fatalf("unexpected policy required roles: %#v", policy.RequiredRoles)
+	}
+	if len(policy.RequiredScopes) != 2 || policy.RequiredScopes[0] != "openid" || policy.RequiredScopes[1] != "profile" {
+		t.Fatalf("unexpected policy required scopes: %#v", policy.RequiredScopes)
+	}
+	if policy.RoleMatchMode != "all" {
+		t.Fatalf("unexpected role match mode: %s", policy.RoleMatchMode)
+	}
+	if policy.ScopeMatchMode != "any" {
+		t.Fatalf("unexpected scope match mode: %s", policy.ScopeMatchMode)
+	}
+	if len(policy.RoleClaimPaths) != 2 || policy.RoleClaimPaths[1] != "realm_access.roles" {
+		t.Fatalf("unexpected policy role claim paths: %#v", policy.RoleClaimPaths)
+	}
+	if len(policy.ScopeClaimPaths) != 2 || policy.ScopeClaimPaths[1] != "scp" {
+		t.Fatalf("unexpected policy scope claim paths: %#v", policy.ScopeClaimPaths)
+	}
+}
+
 func TestStartMetricsServer(t *testing.T) {
 	ln := mustListen(t)
 	// No defer ln.Close() here, server will close it

go.mod

@@ -3,7 +3,7 @@ module github.com/AmmannChristian/nist-sp800-22-rev1a
 go 1.25.7
 
 require (
-	github.com/AmmannChristian/go-authx v1.1.0
+	github.com/AmmannChristian/go-authx v1.2.0
 	github.com/golangci/golangci-lint v1.64.8
 	github.com/google/uuid v1.6.0
 	github.com/prometheus/client_golang v1.23.2

go.sum

@@ -12,8 +12,8 @@ github.com/4meepo/tagalign v1.4.2 h1:0hcLHPGMjDyM1gHG58cS73aQF8J4TdVR96TZViorO9E
 github.com/4meepo/tagalign v1.4.2/go.mod h1:+p4aMyFM+ra7nb41CnFG6aSDXqRxU/w1VQqScKqDARI=
 github.com/Abirdcfly/dupword v0.1.3 h1:9Pa1NuAsZvpFPi9Pqkd93I7LIYRURj+A//dFd5tgBeE=
 github.com/Abirdcfly/dupword v0.1.3/go.mod h1:8VbB2t7e10KRNdwTVoxdBaxla6avbhGzb8sCTygUMhw=
-github.com/AmmannChristian/go-authx v1.1.0 h1:ExytDcxQj+435vbYm/HtNJ7sz5csYLLHb/NyXD+j9is=
-github.com/AmmannChristian/go-authx v1.1.0/go.mod h1:eRp0jNgv25ARPG/dcakOPaU/a5UmqXphngCb0OnjtJg=
+github.com/AmmannChristian/go-authx v1.2.0 h1:ETNvuugwVfztHRFGA+/slV7Jwz7Dr//cEe74FhXPCbY=
+github.com/AmmannChristian/go-authx v1.2.0/go.mod h1:eRp0jNgv25ARPG/dcakOPaU/a5UmqXphngCb0OnjtJg=
 github.com/Antonboom/errname v1.0.0 h1:oJOOWR07vS1kRusl6YRSlat7HFnb3mSfMl6sDMRoTBA=
 github.com/Antonboom/errname v1.0.0/go.mod h1:gMOBFzK/vrTiXN9Oh+HFs+e6Ndl0eTFbtsRTSRdXyGI=
 github.com/Antonboom/nilnil v1.0.1 h1:C3Tkm0KUxgfO4Duk3PM+ztPncTFlOf0b2qadmS0s4xs=

internal/config/config.go

@@ -45,6 +45,12 @@ type Config struct {
 	AuthIntrospectionPrivateKeyFile         string
 	AuthIntrospectionPrivateKeyJWTKeyID     string
 	AuthIntrospectionPrivateKeyJWTAlgorithm string
+	AuthzRequiredRoles                      []string
+	AuthzRequiredScopes                     []string
+	AuthzRoleMatchMode                      string
+	AuthzScopeMatchMode                     string
+	AuthzRoleClaimPaths                     []string
+	AuthzScopeClaimPaths                    []string
 }
 
 // Load reads configuration from environment variables with sensible defaults
@@ -74,6 +80,12 @@ func Load() (*Config, error) {
 		AuthIntrospectionPrivateKeyFile:         getEnvString("AUTH_INTROSPECTION_PRIVATE_KEY_FILE", ""),
 		AuthIntrospectionPrivateKeyJWTKeyID:     getEnvString("AUTH_INTROSPECTION_PRIVATE_KEY_JWT_KID", ""),
 		AuthIntrospectionPrivateKeyJWTAlgorithm: getEnvString("AUTH_INTROSPECTION_PRIVATE_KEY_JWT_ALG", ""),
+		AuthzRequiredRoles:                      parseCSV(getEnvString("AUTHZ_REQUIRED_ROLES", "")),
+		AuthzRequiredScopes:                     parseCSV(getEnvString("AUTHZ_REQUIRED_SCOPES", "")),
+		AuthzRoleMatchMode:                      getEnvString("AUTHZ_ROLE_MATCH_MODE", "any"),
+		AuthzScopeMatchMode:                     getEnvString("AUTHZ_SCOPE_MATCH_MODE", "any"),
+		AuthzRoleClaimPaths:                     parseCSV(getEnvString("AUTHZ_ROLE_CLAIM_PATHS", "")),
+		AuthzScopeClaimPaths:                    parseCSV(getEnvString("AUTHZ_SCOPE_CLAIM_PATHS", "")),
 	}
 
 	if err := cfg.Validate(); err != nil {
@@ -106,6 +118,23 @@ func (c *Config) Validate() error {
 		return fmt.Errorf("invalid LOG_LEVEL: %s (must be debug/info/warn/error)", c.LogLevel)
 	}
 
+	roleMatchMode, err := parseAuthzMatchMode(c.AuthzRoleMatchMode, "AUTHZ_ROLE_MATCH_MODE")
+	if err != nil {
+		return err
+	}
+	c.AuthzRoleMatchMode = roleMatchMode
+
+	scopeMatchMode, err := parseAuthzMatchMode(c.AuthzScopeMatchMode, "AUTHZ_SCOPE_MATCH_MODE")
+	if err != nil {
+		return err
+	}
+	c.AuthzScopeMatchMode = scopeMatchMode
+
+	c.AuthzRequiredRoles = normalizeCSVValues(c.AuthzRequiredRoles)
+	c.AuthzRequiredScopes = normalizeCSVValues(c.AuthzRequiredScopes)
+	c.AuthzRoleClaimPaths = normalizeCSVValues(c.AuthzRoleClaimPaths)
+	c.AuthzScopeClaimPaths = normalizeCSVValues(c.AuthzScopeClaimPaths)
+
 	if c.AuthEnabled {
 		if c.AuthIssuer == "" {
 			return fmt.Errorf("invalid AUTH_ISSUER: required when AUTH_ENABLED=true")
@@ -259,6 +288,42 @@ func parseAuthIntrospectionPrivateKeyJWTAlgorithm(algorithm string) (string, err
 	}
 }
 
+func parseAuthzMatchMode(mode string, envName string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case "", "any":
+		return "any", nil
+	case "all":
+		return "all", nil
+	default:
+		return "", fmt.Errorf("invalid %s: %s (use any or all)", envName, mode)
+	}
+}
+
+func parseCSV(value string) []string {
+	return normalizeCSVValues(strings.Split(value, ","))
+}
+
+func normalizeCSVValues(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+
+	normalizedValues := make([]string, 0, len(values))
+	for _, value := range values {
+		normalizedValue := strings.TrimSpace(value)
+		if normalizedValue == "" {
+			continue
+		}
+		normalizedValues = append(normalizedValues, normalizedValue)
+	}
+
+	if len(normalizedValues) == 0 {
+		return nil
+	}
+
+	return normalizedValues
+}
+
 // getEnvString reads a string from environment variable or returns default
 func getEnvString(key, defaultValue string) string {
 	if value := os.Getenv(key); value != "" {

internal/config/config_test.go

@@ -14,6 +14,12 @@ func TestLoadWithEnvOverrides(t *testing.T) {
 	t.Setenv("AUTH_AUDIENCE", "nist-api")
 	t.Setenv("AUTH_JWKS_URL", "https://issuer.example.com/jwks.json")
 	t.Setenv("AUTH_TOKEN_TYPE", "jwt")
+	t.Setenv("AUTHZ_REQUIRED_ROLES", "NIST_ROLE, entropy-admin ")
+	t.Setenv("AUTHZ_REQUIRED_SCOPES", "openid, profile")
+	t.Setenv("AUTHZ_ROLE_MATCH_MODE", "all")
+	t.Setenv("AUTHZ_SCOPE_MATCH_MODE", "any")
+	t.Setenv("AUTHZ_ROLE_CLAIM_PATHS", "roles,urn:zitadel:iam:org:project:roles")
+	t.Setenv("AUTHZ_SCOPE_CLAIM_PATHS", "scope,scp")
 	t.Setenv("TLS_ENABLED", "true")
 	t.Setenv("TLS_CERT_FILE", "/tmp/cert.pem")
 	t.Setenv("TLS_KEY_FILE", "/tmp/key.pem")
@@ -47,6 +53,24 @@ func TestLoadWithEnvOverrides(t *testing.T) {
 	if cfg.AuthTokenType != "jwt" {
 		t.Fatalf("unexpected auth token type: %s", cfg.AuthTokenType)
 	}
+	if len(cfg.AuthzRequiredRoles) != 2 || cfg.AuthzRequiredRoles[0] != "NIST_ROLE" || cfg.AuthzRequiredRoles[1] != "entropy-admin" {
+		t.Fatalf("unexpected authz required roles: %#v", cfg.AuthzRequiredRoles)
+	}
+	if len(cfg.AuthzRequiredScopes) != 2 || cfg.AuthzRequiredScopes[0] != "openid" || cfg.AuthzRequiredScopes[1] != "profile" {
+		t.Fatalf("unexpected authz required scopes: %#v", cfg.AuthzRequiredScopes)
+	}
+	if cfg.AuthzRoleMatchMode != "all" {
+		t.Fatalf("unexpected authz role match mode: %s", cfg.AuthzRoleMatchMode)
+	}
+	if cfg.AuthzScopeMatchMode != "any" {
+		t.Fatalf("unexpected authz scope match mode: %s", cfg.AuthzScopeMatchMode)
+	}
+	if len(cfg.AuthzRoleClaimPaths) != 2 || cfg.AuthzRoleClaimPaths[0] != "roles" || cfg.AuthzRoleClaimPaths[1] != "urn:zitadel:iam:org:project:roles" {
+		t.Fatalf("unexpected authz role claim paths: %#v", cfg.AuthzRoleClaimPaths)
+	}
+	if len(cfg.AuthzScopeClaimPaths) != 2 || cfg.AuthzScopeClaimPaths[0] != "scope" || cfg.AuthzScopeClaimPaths[1] != "scp" {
+		t.Fatalf("unexpected authz scope claim paths: %#v", cfg.AuthzScopeClaimPaths)
+	}
 	if !cfg.TLSEnabled {
 		t.Fatalf("expected TLSEnabled to be true")
 	}
@@ -196,6 +220,8 @@ func TestValidateFailures(t *testing.T) {
 		{"auth opaque private key jwt missing private key", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", AuthEnabled: true, AuthIssuer: "https://issuer.example.com", AuthAudience: "api", AuthTokenType: "opaque", AuthIntrospectionURL: "https://issuer.example.com/oauth2/introspect", AuthIntrospectionAuthMethod: "private_key_jwt"}},
 		{"auth opaque private key jwt both inline and file set", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", AuthEnabled: true, AuthIssuer: "https://issuer.example.com", AuthAudience: "api", AuthTokenType: "opaque", AuthIntrospectionURL: "https://issuer.example.com/oauth2/introspect", AuthIntrospectionAuthMethod: "private_key_jwt", AuthIntrospectionPrivateKey: "PEM", AuthIntrospectionPrivateKeyFile: "/tmp/key.json"}},
 		{"auth opaque private key jwt invalid algorithm", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", AuthEnabled: true, AuthIssuer: "https://issuer.example.com", AuthAudience: "api", AuthTokenType: "opaque", AuthIntrospectionURL: "https://issuer.example.com/oauth2/introspect", AuthIntrospectionAuthMethod: "private_key_jwt", AuthIntrospectionPrivateKey: "PEM", AuthIntrospectionPrivateKeyJWTAlgorithm: "PS256"}},
+		{"authz invalid role match mode", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", AuthzRoleMatchMode: "one"}},
+		{"authz invalid scope match mode", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", AuthzScopeMatchMode: "one"}},
 		{"tls enabled missing cert", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", TLSEnabled: true, TLSKeyFile: "/tmp/key.pem"}},
 		{"tls enabled missing key", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", TLSEnabled: true, TLSCertFile: "/tmp/cert.pem"}},
 		{"tls enabled invalid client auth", Config{GRPCPort: 9000, MetricsPort: 9001, LogLevel: "info", TLSEnabled: true, TLSCertFile: "/tmp/cert.pem", TLSKeyFile: "/tmp/key.pem", TLSClientAuth: "invalid"}},
@@ -269,6 +295,8 @@ func TestLoadDefaults(t *testing.T) {
 		"AUTH_INTROSPECTION_URL", "AUTH_INTROSPECTION_AUTH_METHOD", "AUTH_INTROSPECTION_CLIENT_ID", "AUTH_INTROSPECTION_CLIENT_SECRET",
 		"AUTH_INTROSPECTION_PRIVATE_KEY", "AUTH_INTROSPECTION_PRIVATE_KEY_FILE",
 		"AUTH_INTROSPECTION_PRIVATE_KEY_JWT_KID", "AUTH_INTROSPECTION_PRIVATE_KEY_JWT_ALG",
+		"AUTHZ_REQUIRED_ROLES", "AUTHZ_REQUIRED_SCOPES", "AUTHZ_ROLE_MATCH_MODE", "AUTHZ_SCOPE_MATCH_MODE",
+		"AUTHZ_ROLE_CLAIM_PATHS", "AUTHZ_SCOPE_CLAIM_PATHS",
 		"TLS_ENABLED", "TLS_CERT_FILE", "TLS_KEY_FILE", "TLS_CA_FILE", "TLS_CLIENT_AUTH", "TLS_MIN_VERSION",
 	} {
 		t.Setenv(key, "")
@@ -295,6 +323,15 @@ func TestLoadDefaults(t *testing.T) {
 	if cfg.AuthIssuer != "" || cfg.AuthAudience != "" || cfg.AuthJWKSURL != "" || cfg.AuthIntrospectionURL != "" || cfg.AuthIntrospectionClientID != "" || cfg.AuthIntrospectionClientSecret != "" || cfg.AuthIntrospectionPrivateKey != "" || cfg.AuthIntrospectionPrivateKeyFile != "" || cfg.AuthIntrospectionPrivateKeyJWTKeyID != "" || cfg.AuthIntrospectionPrivateKeyJWTAlgorithm != "" {
 		t.Errorf("expected auth config defaults to be empty, got %+v", cfg)
 	}
+	if len(cfg.AuthzRequiredRoles) != 0 || len(cfg.AuthzRequiredScopes) != 0 || len(cfg.AuthzRoleClaimPaths) != 0 || len(cfg.AuthzScopeClaimPaths) != 0 {
+		t.Errorf("expected authz list defaults to be empty, got %+v", cfg)
+	}
+	if cfg.AuthzRoleMatchMode != "any" {
+		t.Errorf("expected AuthzRoleMatchMode to default to 'any', got %s", cfg.AuthzRoleMatchMode)
+	}
+	if cfg.AuthzScopeMatchMode != "any" {
+		t.Errorf("expected AuthzScopeMatchMode to default to 'any', got %s", cfg.AuthzScopeMatchMode)
+	}
 	if cfg.AuthTokenType != "jwt" {
 		t.Errorf("expected AuthTokenType to default to 'jwt', got %s", cfg.AuthTokenType)
 	}