sgcAuth 功能矩阵

sgcAuth 的全部能力，对应到两个客户端组件、它们实现的授权模式和声明，以及本包与 sgcCustomIndy 搭配解锁的 WebAuthn、TOTP、LDAP、SAML、OpenID Connect 和 Mail OAuth2 组件。每项能力在 Delphi 和 C++ Builder 中的表现完全一致，每份授权都提供完整源代码。

OAuth2

五种授权模式，一个组件

JWT

签名、附加或验证

WebAuthn

通行密钥，经由 sgcCustomIndy

TOTP

第二身份因素验证码与恢复码

LDAP

通过 TLS 实现 Active Directory 登录

SAML

SAML 2.0 单点登录

OpenID Connect

登录并验证 ID 令牌

Mail OAuth2

面向 SMTP、IMAP 和 POP3 的 OAuth2

标准与平台

Delphi 7 至 13，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 令牌来源。
TOTP 身份验证器TsgcTOTPAuthenticator检查第二身份因素TOTP 与 HOTP 密钥、otpauth 二维码配置、带防重放保护的验证码校验，以及一次性恢复码。
LDAP 客户端TsgcLDAPClient校验目录密码通过 LDAPS 或 StartTLS 实现 LDAP v3 与 Active Directory 登录，支持嵌套组成员关系与分页搜索。
SAML 服务提供者TsgcSAMLServiceProvider单点登录面向 Entra ID、Okta、AD FS、Google Workspace 和 Keycloak 的 SAML 2.0 服务提供者，具备严格的签名与断言验证。
OpenID Connect 客户端TsgcHTTP_OIDC_Client登录用户发现机制、带 PKCE 和 nonce 的浏览器登录、根据提供者密钥验证 ID 令牌，以及 userinfo 端点。
Mail OAuth2TsgcMailOAuth2验证邮件身份Microsoft 365 和 Gmail 的访问令牌与刷新令牌，以及面向 SMTP、IMAP 和 POP3 的 SASL XOAUTH2 与 OAUTHBEARER 字符串。
OAuth2

五种授权模式，一个组件

TsgcHTTP_OAuth2_Client 端到端覆盖 OAuth 2.0（RFC 6749）：启动流程、捕获重定向、用授权码换取令牌，并在此后管理该令牌。

能力API说明
Authorization CodeOAuth2Options.GrantType := auth2Code适用于可以保存客户端密钥的可信服务端 Web 应用的标准流程。
Authorization Code + PKCEauth2CodePKCE（RFC 7636）带授权码交换证明密钥（PKCE）的同一流程，适用于无法保存密钥的原生、移动端和单页应用。
Client Credentialsauth2ClientCredentials无需用户参与的服务器到服务器调用：守护进程和服务账号。
Resource Owner Passwordauth2ResourceOwnerPassword应用程序直接收集用户密码，并用其换取令牌。
Device Codeauth2DeviceCode（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、StopStart 打开系统浏览器（或签发设备代码）并开始配置好的授权流程；Stop 中止流程并关闭本地监听器。
刷新Refresh用刷新令牌换取新的访问令牌，无需再次跳转浏览器。
吊销与自省Revoke（RFC 7009）、Introspect（RFC 7662）使某个令牌失效，或在提供商处查询其状态和元数据。
DPoPDPoPOptions、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；如果用户未能及时完成授权，则触发失效事件。
JWT

签名、附加或验证

TsgcHTTP_JWT_Client 通过一个 JWTOptions 属性实现 RFC 7519（JSON Web Token）、RFC 7515（JWS）和 RFC 7516（JWE）。

能力API说明
HeaderJWTOptions.Header.alg、typ、kidJOSE 头部。alg 用于选择 jwtHS256/384/512、jwtRS256/384/512、jwtES256/384/512，或后量子的 jwtMLDSA44/jwtMLDSA65/jwtMLDSA87；额外字段通过 Header.AddKeyValue 添加。
Payload / 声明JWTOptions.Payload.iss、sub、aud、exp、nbf、iat、jtiRFC 7519 中已注册的声明；自定义声明通过 Payload.AddKeyValue 添加。
签名密钥材料JWTOptions.Algorithms.HS.Secret、RS.PrivateKey、ES.PrivateKey、MLDSA.PrivateKeyHMAC 使用共享密钥，RSA 或 ECDSA 使用 PEM 编码的私钥，ML-DSA 使用 PKCS#8 PEM，由 Header.alg 决定使用哪一种。
后量子签名jwtMLDSA44、jwtMLDSA65、jwtMLDSA87RFC 9964 的 ML-DSA JWS 算法，以纯 Pascal 实现，因此这条路径上不涉及 OpenSSL。客户端使用 JWTOptions.Algorithms.MLDSA.PrivateKey（PKCS#8 PEM）签名；服务器在设置 JWTOptions.Algorithms.MLDSA.Enabled 之后，用 JWTOptions.Algorithms.MLDSA.PublicKey（SubjectPublicKeyInfo PEM）验证。
ML-DSA JSON Web KeysgcMLDSA_ExportPublicJWK、sgcMLDSA_ExportPrivateJWK、sgcMLDSA_ImportJWK、sgcMLDSA_ImportJWKAsPEMAKP JSON Web Key，用于在 JWKS 中发布 ML-DSA 公钥，或读取提供方发布的公钥。
自动刷新JWTOptions.RefreshTokenAfter大于零时，Sign 会自动刷新 iat 并重新计算 exp；为 0 时则每次请求都重新生成令牌。
独立签名Sign构建、签名并以单个字符串形式返回编码后的令牌（header.payload.signature），无需 HTTP 或 WebSocket 客户端。
接入客户端Start、Client.Authentication.Token.JWTStart 对配置好的 JWT 签名，并将其作为 Bearer 令牌交给宿主组件；只需在 Authentication.Token.JWT 上设置一次，之后每个请求都会带着签名发出。
适用对象TsgcWebSocketClient、TsgcHTTP1Client、TsgcHTTP2Client三者均可通过 Authentication.Token 接受一个 TsgcHTTP_JWT_Client 作为其 Bearer 令牌来源。
OpenSSL 配置JWTOptions.OpenSSL_OptionsRS 和 ES 算法所使用的 API 版本与库路径（APIVersion、LibPath、LibPathCustom、UnixSymLinks）。
WebAuthn

无密码登录，还需一块拼图

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 组件。
通行密钥基于可发现凭据的无用户名登录，通过条件中介实现的通行密钥自动填充，每个用户可拥有多个通行密钥，通过 BackupEligible 和 BackupState 区分同步型与设备绑定型，以及克隆身份验证器检测。
TOTP

每个验证码只被接受一次

TsgcTOTPAuthenticator 实现了 TOTP（RFC 6238）和 HOTP（RFC 4226），即 Google Authenticator、Microsoft Authenticator 及其他所有身份验证器应用显示的验证码。

能力API说明
密钥GenerateSecret、SecretLength随机的 Base32 密钥，默认 20 字节，与用户记录一起存储。
二维码配置GetProvisioningURI、Issuer使用颁发者、算法、位数和周期构建 otpauth://totp/ URI，可直接渲染为二维码。
验证码校验VerifyCode、Window接受当前时间步长前后 Window 个步长（默认 1）内的验证码，因此手机时钟存在几秒偏差时仍可登录。
防重放保护带 aLastTimeStep 的 VerifyCode只接受大于上一次所用时间步长的验证码，并返回匹配到的步长，因此同一验证码永远不能被使用两次。
HOTP 计数器GenerateHOTP、VerifyHOTP面向硬件令牌的基于计数器的变体，带有在验证成功后重新同步计数器的前瞻窗口。
恢复码GenerateRecoveryCodes向任意 TStrings 填充唯一的一次性验证码，作为用户丢失设备时的后备方案。
算法与位数Algorithm、Digits、Period每款应用都支持的默认算法 HMAC-SHA1，或 HMAC-SHA256、HMAC-SHA512，验证码可设为 6 到 8 位，周期也可自定义。
LDAP

通过 TLS 实现 Active Directory 登录

TsgcLDAPClient 是一个 LDAP v3 客户端（RFC 4511），用于对照 Active Directory 或任意其他 LDAP 目录验证用户身份并读取其所属组。

能力API说明
连接Host、Connect、BindDN、Password、BaseDN目录服务器、用于搜索的服务账号，以及用户和组搜索的基准位置。
LDAPS 与 StartTLSSecurity、TLSOptions端口 636 上隐式 TLS 的 ldapsecLDAPS，或端口 389 上的 ldapsecStartTLS。被拒绝的 StartTLS 会关闭连接，客户端绝不会回退为明文。
登录模式AuthenticationMode、UserSearchFilterldapamUPN、ldapamDownLevel、ldapamSearchThenBind 或 ldapamDN 将输入的用户名转换为绑定名。
身份验证Authenticate一次调用即可检查用户名和密码，并返回该用户的 DN。
嵌套组GetUserGroups直接的 memberOf 值，或通过 Active Directory 规则 LDAP_MATCHING_RULE_IN_CHAIN 获取经由其他组间接到达的每一个组。
分页搜索Search、PageSize、SizeLimit、TimeLimit自动使用 Simple Paged Results，默认每页 500 条，条目与引用返回到 TsgcLDAPEntries 列表中。
安全绑定Bind、WhoAmI、LastResultCode、LastErrorMessage带空密码的 DN 会在不联系服务器的情况下被拒绝，从而堵上 RFC 4513 中的未认证绑定漏洞。
多线程每个公共方法调用均经过串行化，因此单个实例即可为多线程 HTTP 或 WebSocket 服务器的登录请求提供服务。
SAML

SAML 2.0 单点登录

TsgcSAMLServiceProvider 让 Delphi Web 应用成为面向 Microsoft Entra ID、Okta、AD FS、Google Workspace、Keycloak 及其他身份提供者的 SAML 2.0 服务提供者。

能力API说明
服务提供者身份EntityID、AssertionConsumerServiceURL实体 ID，以及接收浏览器回传响应的 ACS URL。
双向元数据GetMetadata、LoadIdPMetadataGetMetadata 生成需在 IdP 中注册的 SP 元数据。LoadIdPMetadata 填充 IdPEntityID、IdPSSOURL、IdPSSOBinding 和 IdPCertificates。
Redirect 与 POST 绑定GetAuthnRequestRedirectURL、GetAuthnRequestPostForm带压缩后 AuthnRequest 的 HTTP-Redirect URL，或自动提交的 HTTP-POST 表单。
已签名的请求SignAuthnRequests、SPCertificate、SPPrivateKey为要求签名的身份提供者对 AuthnRequest 进行签名。
仅信任受信证书IdPCertificates、AllowSHA1签名只对照已配置的 IdP 证书校验，绝不信任消息中内嵌的证书。支持 RSA-SHA256、RSA-SHA384 和 RSA-SHA512 及排他规范化，仅在允许时才接受 SHA-1。
签名包装攻击防护ProcessResponse响应必须恰好包含一个作为直接子元素的断言，且签名必须引用该元素。
断言校验ClockSkew、MaxAssertionAge、AllowIdPInitiated会校验颁发者、受众、目的地、InResponseTo 和有效期窗口，并维护断言 ID 的防重放缓存。IdP 发起的登录在启用之前始终保持关闭。
结果TsgcSAMLResultNameID、NameIDFormat、SessionIndex、AuthnInstant、带有友好名称的 Attributes，以及可读的 ErrorMessage。
OpenID Connect

使用任意 OpenID 提供者登录

TsgcHTTP_OIDC_Client 在 OAuth2 客户端之上实现了 OpenID Connect Core 1.0，因此回环重定向、刷新令牌、DPoP、设备代码、吊销与内省等能力都随之而来。

能力API说明
发现机制OIDCOptions.Issuer、Discover、DiscoveryDocument读取提供者配置，并填充授权与令牌 URL、JWKSURI、UserInfoEndpoint 和 EndSessionEndpoint。
登录Start打开浏览器，并通过 OAuth2 客户端的本地重定向服务器运行 Authorization Code 流程。
PKCE 与 nonceOIDCOptions.UsePKCE、Nonce默认启用 PKCE，每次登录都会发送一个新的 nonce，ID 令牌必须原样返回。
ID 令牌验证IDToken、IDTokenClaims、IDTokenValid、OnOIDCIDToken会校验签名、颁发者、受众、结合 ClockSkew 的过期时间以及 nonce。仅接受 RS256、RS384、RS512、ES256 和 ES384，none 和 HS 系列算法始终被拒绝。
密钥轮换TsgcOIDCJWKS、RefetchInterval提供者签名密钥的线程安全缓存。未知的密钥 ID 会触发新的下载，因此密钥轮换无需重启应用。
服务器端验证sgcOIDC_ValidateIDToken、OIDCOptions.AllowedTenants使用同一个密钥缓存验证您的 REST API 或 WebSocket 服务器收到的 Bearer 令牌，并将多租户 Entra ID 应用限制为您接受的组织。
UserinfoGetUserInfo返回已登录用户的资料 JSON。
Mail OAuth2

面向 SMTP、IMAP 和 POP3 的 OAuth2

TsgcMailOAuth2 获取并续期 Microsoft 365 和 Gmail 邮件所需的令牌，并将其转换为邮件客户端要发送的 SASL XOAUTH2 和 OAUTHBEARER（RFC 7628）字符串。

能力API说明
提供者预设Provider、TenantId、ClientId使用正确端点的 mopMicrosoft365 或 mopGmail。mopCustom 接受 CustomAuthURL、CustomTokenURL、CustomDeviceAuthorizationURL 和 CustomScope。
根据协议生成作用域Protocols、GetScopempSMTP、mpIMAP 和 mpPOP3 的任意组合都会请求对应的作用域，并在 Microsoft 365 上附加 offline_access。
浏览器或设备代码Flow、LocalServerOptions、OnDeviceCodemofAuthorizationCodePKCE 以回环重定向打开浏览器，mofDeviceCode 适合服务与控制台程序。
令牌生命周期Start、Refresh、AccessToken、RefreshToken、ExpiresAt、OnTokensChangedRefresh 同步刷新访问令牌，每次都会触发 OnTokensChanged，方便您持久化新的刷新令牌。
SASL 字符串GetXOAuth2、GetOAuthBearer用于 AUTH XOAUTH2 和 AUTH OAUTHBEARER 的 Base64 初始响应。Raw 变体和 sgcGetXOAuth2 函数有助于调试及使用其他令牌来源。
与传输方式无关HTTPClientOptions该组件从不建立邮件连接。可搭配 Indy 的 TIdSMTP、TIdIMAP4 或 TIdPOP3，或任何能够发送原始 SASL 命令的邮件库使用。
标准与平台

RFC、编译器与目标平台

标准轨规范，以及在每个受支持编译器上通用的同一份源代码。

方面细节
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）、用于 JOSE 的 ML-DSA（RFC 9964）。
WebAuthn 标准Web Authentication Level 2（W3C），通过 sgcWebSockets 的 WebAuthn 服务器实现。
身份标准TOTP（RFC 6238）、HOTP（RFC 4226）、LDAP v3（RFC 4511）、SAML 2.0（OASIS）、OpenID Connect Core 1.0、SASL OAUTHBEARER（RFC 7628）与 XOAUTH2。
平台两个客户端均为纯 HTTPS 和本地签名，因此覆盖 Delphi 支持的每一个平台：Windows Win32/Win64、Linux 64 位、macOS、iOS 和 Android。
编译器Delphi 和 C++ Builder 7 至 13。
版本OAuth2 客户端和 JWT 客户端自 Standard 版本起也随 sgcWebSockets 提供，WebAuthn、TOTP、LDAP、SAML、OpenID Connect 和 Mail OAuth2 组件在 Enterprise 版本中提供，All-Access 包含全部内容。
授权独立产品。已内置 sgcWebSockets Core 运行时，并包含完整源代码。
超值之选：All-AccesseSeGeCe 全部产品，含高级支持，每年 €1,059 起。
查看 All-Access 价格

用 sgcAuth 构建

下载免费试用版，从 Delphi 或 C++ Builder 获取您的第一个访问令牌或签名 JWT。

下载免费试用版 查看价格