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
- Variables
- func EffectiveRoles(claims AccessTokenClaims) []string
- func Match(pattern, want string) bool
- func NormalizePartition(p string) string
- func SignAccessToken(claims jwt.Claims, signKey string) (string, error)
- func SignAccessTokenHMACKey(claims jwt.Claims, signKey []byte) (string, error)
- func SignAccessTokenRSA(claims jwt.Claims, privateKey *rsa.PrivateKey, kid string) (string, error)
- func SignIDToken(claims jwt.Claims, signKey string) (string, error)
- func SignIDTokenRSA(claims jwt.Claims, privateKey *rsa.PrivateKey, kid string) (string, error)
- type AccessTokenClaims
- type Client
- type CommonClaims
- func (c *CommonClaims) GetMustUserID() int64
- func (c *CommonClaims) GetPreferredUsername() string
- func (c *CommonClaims) SetEmail(email string) *CommonClaims
- func (c *CommonClaims) SetExpiresAt(expiresIn int64) *CommonClaims
- func (c *CommonClaims) SetGroups(groups []string) *CommonClaims
- func (c *CommonClaims) SetRoles(roles []string) *CommonClaims
- func (c *CommonClaims) SetSubject(subject string) *CommonClaims
- type Config
- type GRN
- type IDTokenClaims
- type OPAEnvoyPluginConfig
- type OPARegoConfig
- type OPASDKConfig
Constants ¶
const ( PartitionDefault = "grpc-kit" // 默认分区 PartitionCN = "grpc-kit-cn" // 中国大陆合规分区(预留) PartitionGov = "grpc-kit-gov" // 政企专网分区(预留) )
已登记的 GRN partition 枚举;新增 partition MUST 同步更新 adm/docs/spec/grn.md §6。
const DefaultPartition = "grpc-kit"
DefaultPartition 是 GRN partition 段在 Config.Partition 为空时使用的默认值。
Variables ¶
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
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
NormalizePartition 在 cfg 为空时返回默认 partition。
该函数供 input_builder / static_dict 在替换 ${partition} 占位符时使用, 确保 Config.Partition 未显式设置时仍能产生合法 GRN。
func SignAccessToken ¶ added in v0.4.2
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
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
SignAccessTokenRSA 以 RS256 签名生成 Access Token,kid 非空时写入 header。
func SignIDToken ¶ added in v0.4.2
SignIDToken 以 HS256 签名生成 ID Token,使用 JWT 类型。
func SignIDTokenRSA ¶ added in v0.4.2
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 授权所需的客户端、授权范围、 租户、角色和用户组等声明。
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 (*Client) AuthMetadata ¶
AuthMetadata 把 http 请求信息转换为 grpc 的 metadata 用于鉴权
func (*Client) GetRBACData ¶ added in v0.3.8
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
GRN 表示一个解析后的 GRN(6 段)。
字段顺序与 spec/grn.md §2 的段位顺序严格一致:
grn:<Partition>:<Service>:<Region>:<Account>:<Resource>
Resource 段保留完整字符串(含 type/path 或 type:id 形态),具体子结构由调用方解析。
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 OPASDKConfig ¶
type OPASDKConfig struct {
Config string
}