auth

package
v0.4.3 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package auth 提供 grpc-kit 微服务脚手架的认证授权模块

Package auth — GRN (Generic Resource Name) 实现

GRN 借鉴 AWS ARN 的 6 段固定结构:

grn:<partition>:<service>:<region>:<account-id>:<resource-type>/<resource-path>

完整规范见仓库内文档 adm/docs/spec/grn.md。本文件提供 Go 侧的解析 / 字符串化 / 通配匹配实现,与 Rego 端 `grn_match` 函数 MUST 行为一致;两侧共享同一份 table-driven 测试用例(pkg/auth/testdata/grn_match.json)。

设计要点:

  • 6 段强校验:scheme MUST 为 "grn";段数 MUST 等于 6,否则视为非法 GRN。
  • 第 6 段(resource)内部可能包含 ":"(备选形态 type:id),因此 Parse MUST 使用 SplitN(s, ":", 6) 而非 Split。
  • partition 段 MUST 严格相等:不接受 "*" / "" 通配(spec/grn.md R-PART-2)。
  • service / region / account 段 MAY 在 pattern 端为 "*"(或 ""=空 → 视为通配)。
  • resource 段含 "*" 时走 glob.match(pattern, ["/"], want) 语义。

Index

Constants

View Source
const (
	PartitionDefault = "grpc-kit"     // 默认分区
	PartitionCN      = "grpc-kit-cn"  // 中国大陆合规分区(预留)
	PartitionGov     = "grpc-kit-gov" // 政企专网分区(预留)
)

已登记的 GRN partition 枚举;新增 partition MUST 同步更新 adm/docs/spec/grn.md §6。

View Source
const DefaultPartition = "grpc-kit"

DefaultPartition 是 GRN partition 段在 Config.Partition 为空时使用的默认值。

Variables

View Source
var ErrInvalidGRN = errors.New("auth: invalid GRN")

ErrInvalidGRN 表示输入字符串不符合 GRN 6 段结构。

Functions

func EffectiveRoles added in v0.4.2

func EffectiveRoles(claims AccessTokenClaims) []string

EffectiveRoles returns the role codes used for authorization. Roles are the only authorization source. Groups describe identity membership and are never interpreted as roles, including when the roles claim is absent.

func Match added in v0.4.0

func Match(pattern, want string) bool

Match 判定 pattern 是否覆盖 want。语义与 Rego 端 `grn_match` 完全一致:

  • 两端 MUST 均为合法 6 段 GRN,scheme 严格为 "grn"。
  • partition 段 MUST 严格相等:pattern 端 "*" / "" 均**不接受**作为通配。
  • service / region / account:pattern 端 "*" 或空字符串视为通配;否则严格相等。
  • resource:pattern 含 "*" 时走 glob 匹配(分隔符 "/",与 OPA glob.match 一致), 不含 "*" 时严格相等。

want 端 MUST 是具体值(解析自请求上下文);在 want 端使用通配是调用方的逻辑错误, 本函数不为此做特殊处理(按字面量比较)。

func NormalizePartition added in v0.4.0

func NormalizePartition(p string) string

NormalizePartition 在 cfg 为空时返回默认 partition。

该函数供 input_builder / static_dict 在替换 ${partition} 占位符时使用, 确保 Config.Partition 未显式设置时仍能产生合法 GRN。

func SignAccessToken added in v0.4.2

func SignAccessToken(claims jwt.Claims, signKey string) (string, error)

SignAccessToken 以 HS256 签名生成 Access Token,使用 at+jwt 类型。 Deprecated: new issuers should use SignAccessTokenHMACKey with explicit key bytes. Passing an already-derived password hash to this string API derives it again.

func SignAccessTokenHMACKey added in v0.4.2

func SignAccessTokenHMACKey(claims jwt.Claims, signKey []byte) (string, error)

SignAccessTokenHMACKey signs an Access Token with an already-derived HMAC key. It exists for the static-user profile, whose historical key semantics use PasswordHash bytes directly.

func SignAccessTokenRSA added in v0.4.2

func SignAccessTokenRSA(claims jwt.Claims, privateKey *rsa.PrivateKey, kid string) (string, error)

SignAccessTokenRSA 以 RS256 签名生成 Access Token,kid 非空时写入 header。

func SignIDToken added in v0.4.2

func SignIDToken(claims jwt.Claims, signKey string) (string, error)

SignIDToken 以 HS256 签名生成 ID Token,使用 JWT 类型。

func SignIDTokenRSA added in v0.4.2

func SignIDTokenRSA(claims jwt.Claims, privateKey *rsa.PrivateKey, kid string) (string, error)

SignIDTokenRSA 以 RS256 签名生成 ID Token,kid 非空时写入 header。

Types

type AccessTokenClaims added in v0.4.2

type AccessTokenClaims struct {
	CommonClaims

	// ClientID 是获得该 Access Token 的 OAuth 2.0 客户端标识。
	// 按 RFC 9068 Profile 签发时必须设置。
	ClientID string `json:"client_id,omitempty"`
	// Scope 是本 Access Token 获得授权的 OAuth 2.0 scope 集合。
	// 按 RFC 9068,存在 scope 时编码为空格分隔的字符串。
	Scope string `json:"scope,omitempty"`
}

AccessTokenClaims 仅用于 OAuth 2.0 JWT Access Token。

它描述资源服务器进行 API 授权所需的客户端、授权范围、 租户、角色和用户组等声明。

参考:RFC 9068RFC 7519

func (*AccessTokenClaims) GetAccessToken added in v0.4.2

func (a *AccessTokenClaims) GetAccessToken(signKey string) (string, error)

GetAccessToken 以 HS256 签名生成 access token JWT。 Deprecated: use SignAccessTokenHMACKey with explicit key bytes for new issuers.

func (*AccessTokenClaims) GetAccessTokenRSA added in v0.4.2

func (a *AccessTokenClaims) GetAccessTokenRSA(privateKey *rsa.PrivateKey, kid string) (string, error)

GetAccessTokenRSA 以 RS256 签名生成 access token JWT,kid 非空时写入 header。

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 认证鉴权客户端

func NewClient

func NewClient(ctx context.Context, config *Config) (*Client, error)

NewClient 初始化实例

func (*Client) Allow

func (c *Client) Allow(ctx context.Context) (bool, error)

Allow 是否满足策略允许访问

func (*Client) AuthMetadata

func (c *Client) AuthMetadata(ctx context.Context, req *http.Request) context.Context

AuthMetadata 把 http 请求信息转换为 grpc 的 metadata 用于鉴权

func (*Client) Close

func (c *Client) Close(ctx context.Context)

Close 关闭释放资源

func (*Client) GetRBACData added in v0.3.8

func (c *Client) GetRBACData() *rbacv3.RBAC

func (*Client) WithLoggerOption

func (c *Client) WithLoggerOption(logger *logrus.Entry) *Client

WithLoggerOption 设置日志记录器

type CommonClaims added in v0.4.2

type CommonClaims struct {
	jwt.RegisteredClaims

	// Email 用户邮箱。
	Email string `json:"email,omitempty"`
	// EmailVerified 邮箱是否已验证。
	EmailVerified bool `json:"email_verified,omitempty"`
	// Name 用户全名,展示用。
	Name string `json:"name,omitempty"`
	// PreferredUsername OIDC 标准用户名。新 token 使用该字段,不再签发自定义 username。
	PreferredUsername string `json:"preferred_username,omitempty"`
	// Nickname 昵称。
	Nickname string `json:"nickname,omitempty"`

	// Tenant 租户标识,对应 lion_tenants 中 code 编码。
	Tenant string `json:"tenant,omitempty"`
	// Groups 是可选的用户组编码列表,对应 lion_groups.code。
	// 仅在客户端明确需要组映射时签发。
	Groups []string `json:"groups,omitempty"`
	// Roles 是用户在当前 tenant 下的可选角色编码列表,
	// 对应 lion_roles.code。
	// 仅在客户端明确需要角色映射时签发。
	Roles []string `json:"roles,omitempty"`

	// FederatedClaims 联邦身份声明,如 {"connector_id":"..."}。预留未使用。
	FederatedClaims map[string]string `json:"federated_claims,omitempty"`
	// Deprecated: 历史应用标识字段。
	// 新签发的 ID Token 使用 azp,新签发的 Access Token 使用 client_id。
	// 仅用于兼容解析旧 Token,禁止在新 Token 中签发。
	Appid string `json:"appid,omitempty"`
	// Deprecated: 历史自定义用户名字段。
	// Username 历史自定义字段,仅用于解析旧 token,禁止新 token 签发。
	Username string `json:"username,omitempty"`
}

CommonClaims 是 ID Token 和 Access Token 共用的基础声明。

func (*CommonClaims) GetMustUserID added in v0.4.2

func (c *CommonClaims) GetMustUserID() int64

func (*CommonClaims) GetPreferredUsername added in v0.4.2

func (c *CommonClaims) GetPreferredUsername() string

GetPreferredUsername 返回 OIDC 标准用户名,并兼容读取历史 username claim。

func (*CommonClaims) SetEmail added in v0.4.2

func (c *CommonClaims) SetEmail(email string) *CommonClaims

SetEmail 设置真实用户邮箱。空值保持为空,且不会生成占位邮箱。

func (*CommonClaims) SetExpiresAt added in v0.4.2

func (c *CommonClaims) SetExpiresAt(expiresIn int64) *CommonClaims

func (*CommonClaims) SetGroups added in v0.4.2

func (c *CommonClaims) SetGroups(groups []string) *CommonClaims

func (*CommonClaims) SetRoles added in v0.4.2

func (c *CommonClaims) SetRoles(roles []string) *CommonClaims

func (*CommonClaims) SetSubject added in v0.4.2

func (c *CommonClaims) SetSubject(subject string) *CommonClaims

type Config

type Config struct {
	PackageName string
	Partition   string // GRN partition 段,默认 "grpc-kit"(详见 docs/spec/grn.md)
	OPASDK      *OPASDKConfig
	OPARego     *OPARegoConfig
	OPAEnvoy    *OPAEnvoyPluginConfig
}

Config xx

type GRN added in v0.4.0

type GRN struct {
	Partition string
	Service   string
	Region    string
	Account   string
	Resource  string
}

GRN 表示一个解析后的 GRN(6 段)。

字段顺序与 spec/grn.md §2 的段位顺序严格一致:

grn:<Partition>:<Service>:<Region>:<Account>:<Resource>

Resource 段保留完整字符串(含 type/path 或 type:id 形态),具体子结构由调用方解析。

func Parse added in v0.4.0

func Parse(s string) (*GRN, error)

Parse 解析一个 GRN 字符串;不合法时返回 ErrInvalidGRN 的包装错误。

注意:第 6 段可能包含 ":"(例如 `type:id` 形态),因此使用 SplitN 切分。

func (*GRN) String added in v0.4.0

func (g *GRN) String() string

String 将 GRN 序列化回字符串形态(6 段)。

type IDTokenClaims added in v0.4.0

type IDTokenClaims struct {
	CommonClaims

	// Nonce 防重放随机值,由客户端在认证请求中下发并回显。
	Nonce string `json:"nonce,omitempty"`
	// AuthorizedParty 授权方 client_id,语义等价于 Appid。
	AuthorizedParty string `json:"azp,omitempty"`
	// 用户原始认证发生时间。
	AuthTime *jwt.NumericDate `json:"auth_time,omitempty"`
	// ACR 认证上下文等级(Authentication Context Class Reference)。
	ACR string `json:"acr,omitempty"`
	// AMR 认证方式列表(Authentication Methods References),如 ["pwd","otp"]。
	AMR []string `json:"amr,omitempty"`
	// AtHash Access Token 哈希,用于与 access_token 绑定校验。
	AtHash string `json:"at_hash,omitempty"`
	// CHash Authorization Code 哈希,用于与 code 绑定校验。
	CHash string `json:"c_hash,omitempty"`
}

IDTokenClaims 仅描述 OIDC ID Token 声明。 当前 social_users.go 使用本结构体承载已由 OIDC verifier 验证的外部 Provider id_token; 框架 access token 使用 AccessTokenClaims。 参考:OIDC Core §2 / §5.1,RFC 7519 §4.1。

func ParseIDTokenClaims added in v0.4.0

func ParseIDTokenClaims(token string) (*IDTokenClaims, error)

ParseIDTokenClaims 解析 token 载荷到 IDTokenClaims,不校验签名。 适用于读取已信任来源的 token 声明;如需校验签名请使用 cfg.SecurityConfig.verifyBearerToken。 [未使用] 当前无调用方;OIDC 流程使用内联 jwt.ParseWithClaims。

func (*IDTokenClaims) GetAccessToken added in v0.4.0

func (i *IDTokenClaims) GetAccessToken(signKey string) (string, error)

GetAccessToken 以 HS256 签名生成 access token JWT。 Deprecated: IDTokenClaims 不应用于新 access token;仅为兼容旧调用保留。

func (*IDTokenClaims) GetAccessTokenRSA added in v0.4.0

func (i *IDTokenClaims) GetAccessTokenRSA(privateKey *rsa.PrivateKey, kid string) (string, error)

GetAccessTokenRSA 以 RS256 签名生成 access token JWT,kid 非空时写入 header。 Deprecated: IDTokenClaims 不应用于新 access token;仅为兼容旧调用保留。

type OPAEnvoyPluginConfig

type OPAEnvoyPluginConfig struct {
	GRPCAddress string
}

type OPARegoConfig

type OPARegoConfig struct {
	RegoBody []byte
	DataBody []byte
	// DataProviderFunc 动态数据提供函数,优先级高于 DataBody。
	// 若函数返回空或错误,则降级到 DataBody;DataBody 也为空时使用框架内置默认规则。
	DataProviderFunc func(ctx context.Context) ([]byte, error)
}

type OPASDKConfig

type OPASDKConfig struct {
	Config string
}

Jump to

Keyboard shortcuts

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