sgcAuth 功能矩阵
sgcAuth 的全部能力，对应到两个客户端组件、它们实现的授权模式和声明，以及本包与 sgcCustomIndy 搭配解锁的 WebAuthn 能力。每项能力在 Delphi 和 C++ Builder 中的表现完全一致，每份授权都提供完整源代码。
sgcAuth 的全部能力，对应到两个客户端组件、它们实现的授权模式和声明，以及本包与 sgcCustomIndy 搭配解锁的 WebAuthn 能力。每项能力在 Delphi 和 C++ Builder 中的表现完全一致，每份授权都提供完整源代码。
sgcAuth 是自包含的。它内置了 sgcWebSockets Core 运行时，因此对于 OAuth2 和 JWT 客户端而言，它不是附加组件。
同时内置于 sgcWebSockets。OAuth2 客户端和 JWT 客户端自 Standard 版本起也随 sgcWebSockets 提供。All-Access 包含全部内容。sgcAuth 是面向只需要这些身份验证客户端的团队的独立产品包。
同一个问题的两个方面，注册在 SGC Auth 面板页上。
| 组件 | 类 | 作用 | 描述 |
|---|---|---|---|
| OAuth2 客户端 | TsgcHTTP_OAuth2_Client | 获取令牌 | 面向任意 OAuth2/OIDC 提供商的 Authorization Code、PKCE、Client Credentials、Resource Owner Password 和 Device Code 授权模式，内置本地重定向服务器。 |
| JWT 客户端 | TsgcHTTP_JWT_Client | 签名令牌 | 构建、签名和验证 JSON Web Token，既可独立使用，也可作为 TsgcWebSocketClient、TsgcHTTP1Client 和 TsgcHTTP2Client 的 Bearer 令牌来源。 |
TsgcHTTP_OAuth2_Client 端到端覆盖 OAuth 2.0（RFC 6749）：启动流程、捕获重定向、用授权码换取令牌，并在此后管理该令牌。
| 能力 | API | 说明 |
|---|---|---|
| Authorization Code | OAuth2Options.GrantType := auth2Code | 适用于可以保存客户端密钥的可信服务端 Web 应用的标准流程。 |
| Authorization Code + PKCE | auth2CodePKCE（RFC 7636） | 带授权码交换证明密钥（PKCE）的同一流程，适用于无法保存密钥的原生、移动端和单页应用。 |
| Client Credentials | auth2ClientCredentials | 无需用户参与的服务器到服务器调用：守护进程和服务账号。 |
| Resource Owner Password | auth2ResourceOwnerPassword | 应用程序直接收集用户密码，并用其换取令牌。 |
| Device Code | auth2DeviceCode（RFC 8628） | 面向输入受限设备、智能电视、游戏主机、物联网设备：显示一个用户代码，由用户在第二台设备上输入。 |
| 客户端身份 | OAuth2Options.ClientId、ClientSecret、Username、Password | 根据您提供商的 API 规范设置；Username/Password 用于覆盖在令牌端点要求 Basic 身份验证的提供商。 |
| 提供商端点 | AuthorizationServerOptions.AuthURL、TokenURL、Scope、RevocationURL、IntrospectionURL | 您提供商 OAuth2/OIDC 文档中公布的 URL 和范围列表。 |
| 社交预设 | TsgcHTTP_OAuth2_Client_Google、TsgcHTTP_OAuth2_Client_Microsoft | 预先配置好 Google 和 Microsoft 端点及范围的现成派生类。 |
| 本地重定向监听器 | LocalServerOptions.IP、Port、RedirectURL | 组件启动的小型 HTTP 服务器，用于接收授权码重定向；默认端口为 8080，桌面应用可设为 0 以随机选择端口。 |
| 运行流程 | Start、Stop | Start 打开系统浏览器（或签发设备代码）并开始配置好的授权流程；Stop 中止流程并关闭本地监听器。 |
| 刷新 | Refresh | 用刷新令牌换取新的访问令牌，无需再次跳转浏览器。 |
| 吊销与自省 | Revoke（RFC 7009）、Introspect（RFC 7662） | 使某个令牌失效，或在提供商处查询其状态和元数据。 |
| DPoP | DPoPOptions、GenerateDPoPKeyPair、OnDPoPSign | 持有证明（Demonstrating Proof-of-Possession，RFC 9449）的密钥材料与签名，适用于将令牌绑定到密钥对的提供商。 |
| HTTP 传输 | HTTPClientOptions | 用于向令牌、吊销和自省端点发起 POST 请求的内部 HTTP 客户端的 TLS 与日志配置。 |
| 生命周期事件 | OnBeforeAuthorizeCode、OnAfterAuthorizeCode、OnBeforeAccessToken、OnAfterAccessToken、OnBeforeRefreshToken、OnAfterRefreshToken | 流程每一步前后成对出现的事件。 |
| 错误事件 | OnErrorAccessToken、OnErrorAuthorizeCode、OnErrorRefreshToken、OnErrorRevokeToken、OnErrorIntrospectToken | 流程中每个失败点各对应一个事件，均携带提供商返回的错误、描述和 URI。 |
| Device Code 事件 | OnDeviceCode、OnDeviceCodeExpired | 送达需要显示的用户代码和验证 URI；如果用户未能及时完成授权，则触发失效事件。 |
TsgcHTTP_JWT_Client 通过一个 JWTOptions 属性实现 RFC 7519（JSON Web Token）、RFC 7515（JWS）和 RFC 7516（JWE）。
| 能力 | API | 说明 |
|---|---|---|
| Header | JWTOptions.Header.alg、typ、kid | JOSE 头部。alg 用于选择 jwtHS256/384/512、jwtRS256/384/512 或 jwtES256/384/512；额外字段通过 Header.AddKeyValue 添加。 |
| Payload / 声明 | JWTOptions.Payload.iss、sub、aud、exp、nbf、iat、jti | RFC 7519 中已注册的声明；自定义声明通过 Payload.AddKeyValue 添加。 |
| 签名密钥材料 | JWTOptions.Algorithms.HS.Secret、RS.PrivateKey、ES.PrivateKey | HMAC 使用共享密钥，RSA 或 ECDSA 使用 PEM 编码的私钥，由 Header.alg 决定使用哪一种。 |
| 自动刷新 | JWTOptions.RefreshTokenAfter | 大于零时，Sign 会自动刷新 iat 并重新计算 exp；为 0 时则每次请求都重新生成令牌。 |
| 独立签名 | Sign | 构建、签名并以单个字符串形式返回编码后的令牌（header.payload.signature），无需 HTTP 或 WebSocket 客户端。 |
| 接入客户端 | Start、Client.Authentication.Token.JWT | Start 对配置好的 JWT 签名，并将其作为 Bearer 令牌交给宿主组件；只需在 Authentication.Token.JWT 上设置一次，之后每个请求都会带着签名发出。 |
| 适用对象 | TsgcWebSocketClient、TsgcHTTP1Client、TsgcHTTP2Client | 三者均可通过 Authentication.Token 接受一个 TsgcHTTP_JWT_Client 作为其 Bearer 令牌来源。 |
| OpenSSL 配置 | JWTOptions.OpenSSL_Options | RS 和 ES 算法所使用的 API 版本与库路径（APIVersion、LibPath、LibPathCustom、UnixSymLinks）。 |
WebAuthn 是 sgcAuth 的一部分，但它并不是本包中注册的第三个组件，而是由 sgcWebSockets 的 WebAuthn 服务器提供，并且底层需要 sgcCustomIndy。
| 方面 | 细节 |
|---|---|
| 是什么 | W3C Web Authentication Level 2（WebAuthn）：使用通行密钥和 FIDO2 安全密钥实现无密码登录，由 TsgcWSAPIServer_WebAuthn 提供支持。 |
| 位于何处 | TsgcWSAPIServer_WebAuthn 是一个服务端组件，属于 sgcWebSockets Enterprise 和 All-Access，不是本包注册的客户端组件。 |
| 需要什么 | sgcCustomIndy 为 sgcWebSockets Core 提供的经过修补的 Indy 编译版本。 |
| 如何添加 | 订购 sgcAuth 时，订购页面会自动将 sgcCustomIndy 添加到您的购物车。已经拥有授权？可以在结账时移除这一项，两种方式都不会产生额外费用。 |
| 客户端 | 浏览器端的 JavaScript 应用驱动 WebAuthn 验证流程；sgcHTML 提供了一个与该服务器配套的现成 WebAuthn 登录 UI 组件。 |
标准轨规范，以及在每个受支持编译器上通用的同一份源代码。
| 方面 | 细节 |
|---|---|
| OAuth2 标准 | OAuth 2.0（RFC 6749）、PKCE（RFC 7636）、Device Authorization Grant（RFC 8628）、Token Revocation（RFC 7009）、Token Introspection（RFC 7662）、DPoP（RFC 9449）。 |
| JWT 标准 | JSON Web Token（RFC 7519）、JSON Web Signature（RFC 7515）、JSON Web Encryption（RFC 7516）。 |
| WebAuthn 标准 | Web Authentication Level 2（W3C），通过 sgcWebSockets 的 WebAuthn 服务器实现。 |
| 平台 | 两个客户端均为纯 HTTPS 和本地签名，因此覆盖 Delphi 支持的每一个平台：Windows Win32/Win64、Linux 64 位、macOS、iOS 和 Android。 |
| 编译器 | Delphi 和 C++ Builder 7 至 13。 |
| 版本 | OAuth2 客户端和 JWT 客户端自 Standard 版本起也随 sgcWebSockets 提供，All-Access 包含全部内容。 |
| 授权 | 独立产品。已内置 sgcWebSockets Core 运行时，并包含完整源代码。 |