Documentation
¶
Overview ¶
Application scenarios: - Define the business-facing JWT authentication contract used by handlers and services. - Keep JWT signing, verification, and default-claims construction provider-neutral. - Separate user/business JWT semantics from service-to-service authentication semantics.
适用场景： - 定义 handler 和 service 直接使用的业务侧 JWT 认证契约。 - 在 provider 中立的前提下统一 JWT 签发、校验和默认 claims 构建语义。 - 将用户/业务 JWT 语义与服务间身份认证语义分离开来。
Application scenarios: - Propagate JWT-derived identity information through request-scoped contexts. - Let middleware, handlers, and services share one consistent access path for claims and subject identity. - Keep security-related context keys private to avoid cross-package collisions.
适用场景： - 在请求级 context 中透传由 JWT 解析出的身份信息。 - 让 middleware、handler 和 service 共享统一的 claims 与主体身份读取路径。 - 将安全相关 context key 保持为私有，避免跨包冲突。
Application scenarios: - Define service-to-service authentication contracts used by microservice runtime flows. - Support token-based, mTLS-based, and peer-certificate-based identity verification. - Keep service-auth provider creation and config models independent from concrete implementations.
适用场景： - 定义微服务运行时流程使用的服务间身份认证契约。 - 支持基于 token、mTLS 和对端证书的身份校验方式。 - 让服务鉴权 provider 的创建和配置模型不依赖具体实现。
Application scenarios: - Propagate authenticated service identity through request-scoped contexts. - Let service-auth middleware, handlers, and downstream services share one consistent identity access path. - Keep service-identity context keys private and collision-free.
适用场景： - 在请求级 context 中透传已认证的服务身份。 - 让服务鉴权 middleware、handler 和下游 service 共享统一的身份读取路径。 - 保持服务身份相关 context key 私有且避免冲突。
Index ¶
- Constants
- func FromSubjectIDContext(ctx context.Context) (int64, bool)
- func FromSubjectTypeContext(ctx context.Context) (string, bool)
- func NewJWTClaimsContext(ctx context.Context, claims *JWTClaims) context.Context
- func NewServiceIdentityContext(ctx context.Context, identity *ServiceIdentity) context.Context
- func NewSubjectIDContext(ctx context.Context, subjectID int64) context.Context
- func NewSubjectTypeContext(ctx context.Context, subjectType string) context.Context
- type Container
- type JWTClaims
- type JWTService
- type ServiceAuthConfig
- type ServiceAuthProvider
- type ServiceAuthenticator
- type ServiceIdentity
- type ServicePeerCertificateAuthenticator
- type ServiceProvider
- type ServiceTokenIssuer
- type ServiceTokenVerifier
- type TLSCertificateLoader
Constants ¶
const ( ServiceAuthKey = "framework.service.auth" ServiceIdentityKey = "framework.service.identity" )
const ( // AuthJWTKey is the container key for the business JWT service. // // AuthJWTKey 是业务侧 JWT 服务的容器键。 AuthJWTKey = "framework.auth.jwt" )
Variables ¶
This section is empty.
Functions ¶
func FromSubjectIDContext ¶
FromSubjectIDContext reads the authenticated subject ID from the context.
FromSubjectIDContext 从 context 中读取认证主体 ID。
func FromSubjectTypeContext ¶
FromSubjectTypeContext reads the authenticated subject type from the context.
FromSubjectTypeContext 从 context 中读取认证主体类型。
func NewJWTClaimsContext ¶
NewJWTClaimsContext writes JWT claims into the context.
NewJWTClaimsContext 将 JWT claims 写入 context。
func NewServiceIdentityContext ¶
func NewServiceIdentityContext(ctx context.Context, identity *ServiceIdentity) context.Context
NewServiceIdentityContext stores service identity in context.
NewServiceIdentityContext 将服务身份写入 context。
func NewSubjectIDContext ¶
NewSubjectIDContext writes the authenticated subject ID into the context.
NewSubjectIDContext 将认证主体 ID 写入 context。
Types ¶
type Container ¶
type Container = runtimecontract.Container
Container defines the minimal container surface needed by service auth providers. Reuses the runtime contract's Container for type compatibility.
Container 定义服务鉴权 provider 所需的最小容器接口面。 复用 runtime 契约的 Container，确保类型兼容。
type JWTClaims ¶
type JWTClaims struct {
SubjectID int64
SubjectType string
SubjectName string
Roles []string
ExpiresAt int64
IssuedAt int64
Issuer string
Audience string
}
JWTClaims describes the shared business JWT claims model.
JWTClaims 描述共享的业务 JWT claims 模型。
type JWTService ¶
type JWTService interface {
// Sign signs one set of JWT claims.
//
// Sign 对一组 JWT claims 进行签发。
Sign(claims JWTClaims) (string, error)
// Verify verifies one JWT token and returns claims.
//
// Verify 校验一个 JWT token 并返回 claims。
Verify(token string) (*JWTClaims, error)
// NewClaims builds one standard JWT claims object.
//
// NewClaims 构建一份标准 JWT claims。
NewClaims(subjectID int64, subjectType, subjectName string, roles []string, ttlSeconds int64) JWTClaims
}
JWTService defines the minimal business JWT contract.
JWTService 定义最小业务 JWT 契约。
中文说明： - 这是给业务项目直接使用的最小认证能力。 - 不承载 session 存储，只负责 JWT 签发与校验。 - 它与 service_auth.go 中的“服务间身份认证”是两条独立主线。 - 可被 gin middleware、HTTP handler 和业务 service 复用。
type ServiceAuthConfig ¶
type ServiceAuthConfig struct {
Mode string
ServiceName string
Namespace string
Environment string
MTLSEnabled bool
MTLSCertFile string
MTLSKeyFile string
MTLSCAFile string
MTLSServerName string
TokenSecret string
TokenExpiry int64
TokenIssuer string
TokenAudience string
AllowedServices []string
}
ServiceAuthConfig describes service-auth configuration.
ServiceAuthConfig 描述服务鉴权配置。
type ServiceAuthProvider ¶
type ServiceAuthProvider interface {
ServiceProvider
// CreateAuthenticator creates a service authenticator from config.
//
// CreateAuthenticator 根据配置创建服务认证器。
CreateAuthenticator(cfg *ServiceAuthConfig) (ServiceAuthenticator, error)
}
ServiceAuthProvider defines the provider contract for creating service authenticators.
ServiceAuthProvider 定义创建服务认证器的 provider 契约。
type ServiceAuthenticator ¶
type ServiceAuthenticator interface {
// Authenticate authenticates the current request and returns the resolved service identity.
//
// Authenticate 认证当前请求并返回解析出的服务身份。
Authenticate(ctx context.Context) (*ServiceIdentity, error)
}
ServiceAuthenticator defines the service-identity authentication contract.
ServiceAuthenticator 定义服务身份认证契约。
type ServiceIdentity ¶
type ServiceIdentity struct {
ServiceID string
ServiceName string
Namespace string
Environment string
Metadata map[string]string
}
ServiceIdentity describes one authenticated service identity.
ServiceIdentity 描述一个已认证的服务身份。
func FromServiceIdentityContext ¶
func FromServiceIdentityContext(ctx context.Context) (*ServiceIdentity, bool)
FromServiceIdentityContext retrieves service identity from context.
FromServiceIdentityContext 从 context 中读取服务身份。
type ServicePeerCertificateAuthenticator ¶
type ServicePeerCertificateAuthenticator interface {
// AuthenticatePeerCertificate authenticates the peer certificate and returns the resolved service identity.
//
// AuthenticatePeerCertificate 校验对端证书并返回解析出的服务身份。
AuthenticatePeerCertificate(ctx context.Context, cert *x509.Certificate) (*ServiceIdentity, error)
}
ServicePeerCertificateAuthenticator defines peer-certificate authentication for service identity.
ServicePeerCertificateAuthenticator 定义基于对端证书的服务身份认证契约。
type ServiceProvider ¶
type ServiceProvider = runtimecontract.ServiceProvider
ServiceProvider defines the provider registration surface needed by service auth providers. Reuses the runtime contract's ServiceProvider to avoid duplicate, incompatible definitions.
ServiceProvider 定义服务鉴权 provider 所需的 provider 注册接口面。 复用 runtime 契约的 ServiceProvider，避免重复且不兼容的定义。
type ServiceTokenIssuer ¶
type ServiceTokenIssuer interface {
// GenerateToken generates a token for the target service.
//
// GenerateToken 为目标服务生成令牌。
GenerateToken(ctx context.Context, targetService string) (string, error)
}
ServiceTokenIssuer defines the service token issuing contract.
ServiceTokenIssuer 定义服务令牌签发契约。
type ServiceTokenVerifier ¶
type ServiceTokenVerifier interface {
// VerifyToken verifies a token and returns the resolved service identity.
//
// VerifyToken 校验令牌并返回解析出的服务身份。
VerifyToken(ctx context.Context, token string) (*ServiceIdentity, error)
}
ServiceTokenVerifier defines the service token verification contract.
ServiceTokenVerifier 定义服务令牌校验契约。
type TLSCertificateLoader ¶
type TLSCertificateLoader interface {
LoadCertificate(certFile, keyFile string) (*tls.Certificate, error)
LoadCA(caFile string) (*x509.CertPool, error)
}
TLSCertificateLoader defines the certificate-loading contract used by mTLS auth providers.
TLSCertificateLoader 定义 mTLS 鉴权 provider 使用的证书加载契约。
Source Files