认证鉴权后端【免费下载链接】hydraInternet-scale OpenID Certified™ OpenID Connect and OAuth2.1 provider that integrates with your user management through headless APIs. Solve OIDC/OAuth2 user cases over night. Consume as a service on Ory Network or self-host. Trusted by OpenAI and many others for scale and security. Written in Go.项目地址https://gitcode.com/gh_mirrors/hydra2/hydra点击查看免费下载本文以 Ory Hydrahydra2/hydra仓库内 OpenAPI 生成的 SDK 模型文档 internal/httpclient/docs/JsonWebKey.md 为主体结合 internal/httpclient/model_json_web_key.go 的源码实现与jwk/包的服务端代码系统讲解JsonWebKey模型的全部字段、构造函数与访问方法并延伸到它在下游的 JWK Set、Admin 密钥管理 API、密钥轮换与.well-known/jwks.json发现端点中的真实用法。读完本文你将能够读懂并正确构造 Hydra 的 JWK 数据结构并通过 API 或 CLI 完成密钥生成、导入、轮换与删除的完整操作。JsonWebKey 在 Ory Hydra 中的角色JsonWebKeyJSON Web Key简称 JWK是 Ory Hydra 中表示单个加密密钥的标准 JSON 数据结构。Hydra 不仅用它来管理 OpenID Connect ID Token、OAuth 2.0 JWT Access Token 的签名密钥也允许用户通过 Admin API 保存自定义密钥。与之配套的JsonWebKeySet则是一组 JWK 的集合一个密钥由集合名set 密钥 IDkid二元组唯一标识。Hydra 的服务端公开了三个与密钥相关的公开/管理路由见 jwk/handler.go/.well-known/jwks.json公开用于令牌验签的密钥发现/admin/keys/{set}与/admin/keys/{set}/{kid}管理端完整的 CRUD而JsonWebKey模型正是这些端点请求与响应体中承载密钥数据的核心结构。模型属性全解析根据 internal/httpclient/docs/JsonWebKey.md 的属性表JsonWebKey共包含 17 个字段。其中4 个必填alg、kid、kty、use其余 13 个均为可选OpenAPI 语义中的[optional]。属性名类型必填说明algstring是密钥使用的算法标识。取值应注册于 IANA JSON Web Signature and Encryption AlgorithmsJWA注册表或使用防碰撞名称。kidstring是密钥 ID用于在 JWK Set 中匹配具体密钥例如密钥轮换时选择密钥。区分大小写同一 Set 内不同密钥应使用不同的kid值。ktystring是密钥类型标识密码算法家族如RSA、EC。取值应注册于 IANA JSON Web Key Types 注册表区分大小写。usestring是公钥用途public key usesig表示用于验签enc表示用于加密。crv*string否椭圆曲线名称EC 密钥专用。x/y*string否EC 公钥点的坐标EC 密钥专用。n*string否RSA 模数RSA 公钥。e*string否RSA 公钥指数RSA 公钥。d*string否RSA 私钥指数 / EC 私钥标量仅私钥包含。p/q*string否RSA 私钥的中国剩余定理CRT素数。dp/dq/qi*string否RSA 私钥的 CRT 系数。k*string否对称密钥的密钥材料oct类型专用。x5c*[]string否X.509 证书链一个或多个 PKIX 证书RFC 5280。每个字符串是base64 编码RFC 4648 Section 4即标准 base64 而非 base64url的 DER 证书值包含密钥本身的 PKIX 证书必须排在数组首位。这些字段与 Go 源码中的结构体定义一一对应。在 internal/httpclient/model_json_web_key.go 中可选字段全部声明为指针类型*string、*[]string并使用json:crv,omitempty标签从而在序列化时区分字段未设置与字段为零值两种状态。不同密钥类型使用哪些字段理解字段组合关系是正确构造JsonWebKey的关键可以按kty归纳如下RSA 密钥kty: RSA公钥需要n、e私钥额外包含d、p、q、dp、dq、qi。椭圆曲线密钥kty: EC需要crv指定曲线如P-256配合坐标x、y与私钥标量d。对称密钥kty: oct直接以k存放对称密钥材料典型用于 HS256/HS512 签名。证书绑定密钥任何类型都可以附加x5c证书链便于下游直接使用公钥证书。Hydra 内部通过 jwk/generate.go 的GenerateJWK生成新密钥时正是按算法族填充这些字段RSA 系列RS256/RS384/RS512使用4096 位密钥若未指定kid则自动生成 UUID v4若未指定use则默认sig。必填字段的服务端校验虽然模型层允许构造出只含必填字段的对象但服务端在解析请求体时会严格执行必填校验。在 internal/httpclient/model_json_web_key.go 的UnmarshalJSON实现中代码先将 JSON 反序列化为通用 map逐项检查alg、kid、kty、use四个键是否存在缺失即返回no value given for required property xxx错误随后使用DisallowUnknownFields()拒绝未知字段。因此无论通过 HTTP 直接提交还是使用 SDK构造一个合法的最小JsonWebKey至少需要同时给出这四个字段{ alg: RS256, kid: 1603dfe0af8f4596, kty: RSA, use: sig }构造函数与访问方法OpenAPI 生成代码的标准模式文档的 Methods 部分完整罗列了该模型在 Go SDK 中的 API 面见 internal/httpclient/docs/JsonWebKey.md可分为三类1. 构造函数2 个func NewJsonWebKey(alg string, kid string, kty string, use string) *JsonWebKey func NewJsonWebKeyWithDefaults() *JsonWebKeyNewJsonWebKey按四个必填参数实例化对象并完成赋值源码见 model_json_web_key.go保证满足 API 的必填要求NewJsonWebKeyWithDefaults仅创建空对象只赋默认值不保证必填字段已设置model_json_web_key.go。2. 每个字段的 Getter/Setter每个字段 3 个方法对每个属性SDK 统一生成GetXxx、GetXxxOk、SetXxx三个方法对可选字段额外生成HasXxx方法。以crv为例func (o *JsonWebKey) GetCrv() string // 返回字段值nil 时返回零值 func (o *JsonWebKey) GetCrvOk() (*string, bool) // 返回 (字段指针, 是否已设置) func (o *JsonWebKey) SetCrv(v string) // 取地址并赋值给指针字段 func (o *JsonWebKey) HasCrv() bool // 返回字段是否已设置这种模式贯穿整个 SDKGetAlg/GetAlgOk/SetAlg必填字段无HasXxx以及GetD/GetDOk/SetD/HasD、GetX5c/GetX5cOk/SetX5c/HasX5c等全部字段。必填字段的 getter 直接返回结构体字段nil 时返回零值可选字段的 getter 则先判断指针是否为 nil。使用建议判断请求方是否显式提供了某可选字段时使用HasXxx或GetXxxOk避免把未设置误当成空字符串修改字段时优先使用SetXxx避免手动取地址构造用于 API 请求的最小对象时使用NewJsonWebKey(...)。3. 序列化控制MarshalJSON通过ToMap()组装输出model_json_web_key.go必填字段无条件写入可选字段仅在非 nil 时写入从而保证省略可选字段时不会产生多余的空字符串键。与相关模型的关系JsonWebKey通常不单独出现而是作为更大结构的一部分JsonWebKeySet包含一个可选的keys字段[]JsonWebKey。文档明确指出数组内密钥的排列顺序默认不代表优先级除非应用自行赋予顺序含义。它是 Admin API 增删改查的响应载体。CreateJsonWebKeySetPOST /admin/keys/{set}的请求体包含alg、kid、use三个必填字段用于指示 Hydra自动生成密钥而不是由调用方提供密钥材料。支持RS256、ES256、ES512、HS512、HS256等算法。三者关系可概括为调用方用CreateJsonWebKeySet请求 Hydra 生成密钥 → Hydra 生成并持久化一个或多个JsonWebKey→ 以JsonWebKeySet形式返回给调用方并通过公开端点向验签方发布公钥。通过 Admin API 管理密钥JsonWebKey的服务端管理入口是JwkAPI见 internal/httpclient/docs/JwkAPI.md 与实现 internal/httpclient/api_jwk.go共 7 个端点路由注册见 jwk/handler.go方法HTTP 请求说明CreateJsonWebKeySetPOST /admin/keys/{set}创建 JSON Web Key自动生成DeleteJsonWebKeyDELETE /admin/keys/{set}/{kid}删除单个 JSON Web KeyDeleteJsonWebKeySetDELETE /admin/keys/{set}删除整个 JSON Web Key SetGetJsonWebKeyGET /admin/keys/{set}/{kid}获取 Set 中的单个 JSON Web KeyGetJsonWebKeySetGET /admin/keys/{set}获取整个 JSON Web Key SetSetJsonWebKeyPUT /admin/keys/{set}/{kid}写入导入自己的 JSON Web KeySetJsonWebKeySetPUT /admin/keys/{set}整体替换 JSON Web Key Set其中两个端点与JsonWebKey模型直接相关SetJsonWebKey导入自己的密钥jsonWebKey : *openapiclient.NewJsonWebKey(RS256, 1603dfe0af8f4596, RSA, sig) resp, r, err : apiClient.JwkAPI.SetJsonWebKey(context.Background(), set, kid). JsonWebKey(jsonWebKey).Execute()需要特别注意文档中的警告密钥实际以请求体中的kid为准创建或更新路径参数{kid}仅出于历史原因保留会被忽略且不与请求体校验。这一行为在服务端 jwk/handler.go 的adminUpdateJsonWebKey中有明确注释佐证。CreateJsonWebKeySet自动生成的语义同样值得关注见 internal/httpclient/api_jwk.go 与 jwk/handler.go若指定 Set 不存在则创建它若 Set 已存在新生成的密钥追加到 Set 中、保留全部旧密钥——这正是密钥轮换的基础用旧密钥签发的令牌在轮换后仍可验证例外配置了硬件安全模块HSM时生成操作会替换整个 Set仅保留新密钥若想整体替换 Set应改用PUT /admin/keys/{set}SetJsonWebKeySet未包含在请求体中的旧密钥会被删除。服务端实现生成、加密存储与公钥发现密钥生成GenerateJWKjwk/generate.go是服务端生成的核心函数根据alg决定位数与算法族RSA 系列 4096 位通过josex.NewSigningKey生成公私钥填充Algorithm、Use、KeyID等字段后组装成jose.JSONWebKeySet返回。加密存储所有密钥落库前都会被加密。Manager接口jwk/manager.go定义了GenerateAndPersistKeySet、AddKey、UpdateKey、GetKey、DeleteKey等全套操作存储行SQLDatajwk/manager.go落在hydra_jwk表中包含sidSet 名、kid、keydata等列。读取时通过aead.AESGCM解密密钥数据后再反序列化为 JWKSQLDataRows.ToJWK确保私钥材料在数据库中以密文形式存在。公钥发现与广播Hydra 通过/.well-known/jwks.json向验签方发布公钥。discoverJsonWebKeysjwk/handler.go读取配置项webfinger.jwks.broadcast_keys源码键定义见 driver/config/provider.go读取逻辑见同文件WellKnownKeysprovider.go并并发拉取各 Set若某个 Set 尚不存在会自动以 RS256/sig即时生成随后通过ExcludePrivateKeys剔除私钥字段后返回。这意味着你创建的包含私钥的JsonWebKey永远不会通过该公开端点泄露只会广播公钥部分。如果需要将自定义密钥集广播到该公开端点流程是先通过createJsonWebKeySet创建密钥集再将该 Set 的名称加入webfinger.jwks.broadcast_keys配置。使用 CLI 快速创建密钥集不写代码也能完成密钥创建。Hydra CLI 提供了hydra create jwk命令cmd/cmd_create_jwks.gohydra create jwk my-jwk-set --alg RS256 --use sig常用参数参数默认值说明set-id—必填JSON Web Key Set ID第一个位置参数[key-id]随机 UUID可选的密钥 ID第二个位置参数--algRS256生成算法支持RS256、RS512、ES256、ES512、EdDSA--usesig密钥用途支持sig、enc--publicfalse仅返回公钥该命令内部正是调用JwkAPI.CreateJsonWebKeySet请求体使用CreateJsonWebKeySet{Alg, Kid, Use}与本文介绍的模型链路完全一致--public标志则通过jwk.OnlyPublicSDKKeys过滤响应中的私钥字段。常见问题与安全建议kid不一致调用PUT /admin/keys/{set}/{kid}时路径中的kid会被忽略务必以请求体JsonWebKey.kid为准避免误以为路径参数能控制密钥 ID。轮换后旧令牌失效轮换应使用POST /admin/keys/{set}追加新密钥、保留旧密钥而非PUT /admin/keys/{set}整体替换否则旧密钥签发的令牌将无法验签。私钥泄露GET /admin/keys/{set}等管理端点会剔除不透明私钥ExcludeOpaquePrivateKeys公开的/.well-known/jwks.json更只会广播公钥但管理端点本身仍需置于可信网络与强认证之后因为密钥的持久化形态虽经 AESGCM 加密管理面仍然是私钥的合法出口。必填字段缺失提交不含alg/kid/kty/use的 JWK 会被服务端拒绝SDK 中应优先使用NewJsonWebKey(alg, kid, kty, use)构造对象。算法选择RSA 系列在 Hydra 中默认生成 4096 位密钥jwk/generate.goHS 系列属于对称密钥k字段承载密钥材料分发与管理对称密钥时需格外谨慎。如需继续深入可依次阅读仓库中的相关文件JsonWebKey 模型文档、模型源码、JwkAPI 文档、JsonWebKeySet 文档、服务端 jwk/handler.go、jwk/manager.go 与 jwk/generate.go以及 CLI 实现 cmd/cmd_create_jwks.go。赞分享认证鉴权后端【免费下载链接】hydraInternet-scale OpenID Certified™ OpenID Connect and OAuth2.1 provider that integrates with your user management through headless APIs. Solve OIDC/OAuth2 user cases over night. Consume as a service on Ory Network or self-host. Trusted by OpenAI and many others for scale and security. Written in Go.项目地址https://gitcode.com/gh_mirrors/hydra2/hydra点击查看免费下载相关推荐Ory Hydra OAuth2 错误响应模型 ErrorOAuth2 深度解析字段语义、Go SDK 用法与排查实战Ory Hydra OAuth2 错误响应模型 ErrorOAuth2 深度解析字段语义、Go SDK 用法与排查实战 Ory Hydra 作为一款面向互联网认证鉴权后端Ory Hydra Go SDK 通用错误模型 GenericError 全解析字段语义、序列化规则与异常处理实战Ory Hydra Go SDK 通用错误模型 GenericError 全解析字段语义、序列化规则与异常处理实战 GenericError 是 Ory Hy认证鉴权后端Ory Hydra AcceptOAuth2ConsentRequest 模型解析从字段语义到 Consent 接受流程的完整实战指南Ory Hydra AcceptOAuth2ConsentRequest 模型解析从字段语义到 Consent 接受流程的完整实战指南 导读 AcceptOA认证鉴权后端上一篇u-dma-buf vs udmabuf为什么这个Linux驱动改了名字深度对比下一篇X-TRACK轨迹记录功能详解如何导出标准GPX格式文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考