sgcAuth-functiematrix: OAuth2, JWT & WebAuthn

Standaarden & platforms

Delphi 7 tot 13, C++ Builder

sgcAuth is zelfstandig. Het wordt geleverd met de sgcWebSockets Core runtime inbegrepen, dus het is geen add-on voor de OAuth2- en JWT-clients.

Ook in sgcWebSockets. Zowel de OAuth2 Client als de JWT Client zitten ook in sgcWebSockets-edities vanaf Standard. All-Access bevat alles. sgcAuth is het standalone package voor teams die alleen de authenticatieclients nodig hebben.

Componenten

Zeven paletcomponenten

Twee tokenclients en vijf identiteitscomponenten, geregistreerd op de paletpagina SGC Auth.

Component	Klasse	Taak	Beschrijving
OAuth2 Client	`TsgcHTTP_OAuth2_Client`	Een token ophalen	Authorization Code-, PKCE-, Client Credentials-, Resource Owner Password- en Device Code-grants tegen elke OAuth2/OIDC-provider, met een ingebouwde lokale redirectserver.
JWT Client	`TsgcHTTP_JWT_Client`	Een token ondertekenen	Bouwt, ondertekent en verifieert JSON Web Tokens, standalone of als Bearer-tokenbron voor TsgcWebSocketClient, TsgcHTTP1Client en TsgcHTTP2Client.
TOTP Authenticator	`TsgcTOTPAuthenticator`	Een tweede factor controleren	TOTP- en HOTP-secrets, otpauth QR-provisioning, codeverificatie met replaybescherming, en eenmalige herstelcodes.
LDAP Client	`TsgcLDAPClient`	Een directorywachtwoord controleren	LDAP v3- en Active Directory-aanmelding via LDAPS of StartTLS, geneste groepslidmaatschap en gepagineerd zoeken.
SAML Service Provider	`TsgcSAMLServiceProvider`	Single sign-on	SAML 2.0 service provider voor Entra ID, Okta, AD FS, Google Workspace en Keycloak, met strikte handtekening- en assertion-validatie.
OpenID Connect Client	`TsgcHTTP_OIDC_Client`	Een gebruiker aanmelden	Discovery, aanmelden via browser met PKCE en nonce, ID-tokenvalidatie tegen de sleutels van de provider, en het userinfo-endpoint.
Mail OAuth2	`TsgcMailOAuth2`	Mail authenticeren	Access- en refresh tokens voor Microsoft 365 en Gmail, plus de SASL-strings XOAUTH2 en OAUTHBEARER voor SMTP, IMAP en POP3.

OAuth2

Vijf granttypes, één component

TsgcHTTP_OAuth2_Client dekt OAuth 2.0 (RFC 6749) van begin tot eind: het start de flow, vangt de redirect op, wisselt de code in voor een token en beheert het token daarna.

Mogelijkheid	API	Opmerkingen
Authorization Code	`OAuth2Options.GrantType := auth2Code`	De standaardflow voor vertrouwde server-side webtoepassingen die een client secret kunnen bewaren.
Authorization Code + PKCE	`auth2CodePKCE` (RFC 7636)	Dezelfde flow met een Proof Key for Code Exchange, voor native, mobiele en single-page apps die geen secret kunnen bewaren.
Client Credentials	`auth2ClientCredentials`	Server-naar-server-aanroepen zonder gebruiker in de lus: daemons en serviceaccounts.
Resource Owner Password	`auth2ResourceOwnerPassword`	De toepassing verzamelt het wachtwoord van de gebruiker rechtstreeks en wisselt het in voor een token.
Device Code	`auth2DeviceCode` (RFC 8628)	Voor invoerbeperkte apparaten, smart-tv's, mediaconsoles, IoT: toont een gebruikerscode die de persoon op een tweede apparaat invoert.
Clientidentiteit	`OAuth2Options.ClientId`, `ClientSecret`, `Username`, `Password`	In te stellen volgens de API-specificatie van je provider; Username/Password dekken providers die Basic Authentication op het token-endpoint vereisen.
Provider-endpoints	`AuthorizationServerOptions.AuthURL`, `TokenURL`, `Scope`, `RevocationURL`, `IntrospectionURL`	De URL's en scopelijst uit de OAuth2/OIDC-documentatie van je provider.
Sociale presets	`TsgcHTTP_OAuth2_Client_Google`, `TsgcHTTP_OAuth2_Client_Microsoft`	Kant-en-klare afstammelingen die de Google- en Microsoft-endpoints en -scopes vooraf configureren.
Lokale redirectlistener	`LocalServerOptions.IP`, `Port`, `RedirectURL`	De kleine HTTP-server die het component start om de authorization-code-redirect te ontvangen; standaard poort 8080, of 0 om een willekeurige poort te kiezen voor desktopapps.
De flow uitvoeren	`Start`, `Stop`	`Start` opent de systeembrowser (of geeft de device code uit) en start de geconfigureerde grant; `Stop` breekt hem af en sluit de lokale listener.
Refresh	`Refresh`	Wisselt een refresh-token in voor een nieuw access-token zonder nog een browser-omweg.
Intrekken & introspectie	`Revoke` (RFC 7009), `Introspect` (RFC 7662)	Maak een token ongeldig, of vraag de status en metadata ervan op bij de provider.
DPoP	`DPoPOptions`, `GenerateDPoPKeyPair`, `OnDPoPSign`	Demonstrating Proof-of-Possession (RFC 9449) sleutelmateriaal en ondertekening, voor providers die tokens aan een sleutelpaar binden.
HTTP-transport	`HTTPClientOptions`	TLS- en loggingconfiguratie voor de interne HTTP-client die naar de token-, revocation- en introspection-endpoints POST.
Levenscyclusevents	`OnBeforeAuthorizeCode`, `OnAfterAuthorizeCode`, `OnBeforeAccessToken`, `OnAfterAccessToken`, `OnBeforeRefreshToken`, `OnAfterRefreshToken`	Voor/na-paren rond elke stap van de flow.
Foutevents	`OnErrorAccessToken`, `OnErrorAuthorizeCode`, `OnErrorRefreshToken`, `OnErrorRevokeToken`, `OnErrorIntrospectToken`	Eén per faalpunt in de flow, elk met de foutmelding, beschrijving en URI van de provider.
Device Code-events	`OnDeviceCode`, `OnDeviceCodeExpired`	Levert de te tonen gebruikerscode en verificatie-URI, en vuurt als de gebruiker de autorisatie niet op tijd afrondt.

JWT

Ondertekenen, koppelen of verifiëren

TsgcHTTP_JWT_Client implementeert RFC 7519 (JSON Web Token), RFC 7515 (JWS) en RFC 7516 (JWE) via één JWTOptions-eigenschap.

Mogelijkheid	API	Opmerkingen
Header	`JWTOptions.Header.alg`, `typ`, `kid`	De JOSE-header. `alg` kiest `jwtHS256`/`384`/`512`, `jwtRS256`/`384`/`512`, `jwtES256`/`384`/`512` of de post-quantum `jwtMLDSA44`/`jwtMLDSA65`/`jwtMLDSA87`; extra velden gaan via `Header.AddKeyValue`.
Payload / claims	`JWTOptions.Payload.iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`	De geregistreerde RFC 7519-claims; custom claims worden toegevoegd met `Payload.AddKeyValue`.
Sleutelmateriaal voor ondertekening	`JWTOptions.Algorithms.HS.Secret`, `RS.PrivateKey`, `ES.PrivateKey`, `MLDSA.PrivateKey`	Gedeelde secret voor HMAC, PEM-gecodeerde private key voor RSA of ECDSA, PKCS#8-PEM voor ML-DSA, gekozen via `Header.alg`.
Post-quantum handtekeningen	`jwtMLDSA44`, `jwtMLDSA65`, `jwtMLDSA87`	De ML-DSA JWS-algoritmen van RFC 9964, geïmplementeerd in puur Pascal, dus er komt op dit pad geen OpenSSL aan te pas. De client ondertekent met `JWTOptions.Algorithms.MLDSA.PrivateKey`, een PKCS#8-PEM; een server verifieert met `JWTOptions.Algorithms.MLDSA.PublicKey`, een SubjectPublicKeyInfo-PEM, zodra `JWTOptions.Algorithms.MLDSA.Enabled` is gezet.
ML-DSA JSON Web Keys	`sgcMLDSA_ExportPublicJWK`, `sgcMLDSA_ExportPrivateJWK`, `sgcMLDSA_ImportJWK`, `sgcMLDSA_ImportJWKAsPEM`	AKP JSON Web Keys, om een ML-DSA-sleutel in een JWKS te publiceren of er een van een provider te lezen.
Automatische vernieuwing	`JWTOptions.RefreshTokenAfter`	Groter dan nul: `Sign` vernieuwt `iat` en herberekent `exp` automatisch; 0 genereert het token bij elke request opnieuw.
Zelfstandig ondertekenen	`Sign`	Bouwt, ondertekent en geeft het gecodeerde token (`header.payload.signature`) terug als één string, geen HTTP- of WebSocket-client nodig.
Koppelen aan een client	`Start`, `Client.Authentication.Token.JWT`	`Start` ondertekent de geconfigureerde JWT en levert hem als Bearer-token aan het hostcomponent; stel hem eenmaal in op `Authentication.Token.JWT` en elke request gaat ondertekend uit.
Werkt met	`TsgcWebSocketClient`, `TsgcHTTP1Client`, `TsgcHTTP2Client`	Alle drie accepteren een `TsgcHTTP_JWT_Client` als Bearer-tokenbron via `Authentication.Token`.
OpenSSL-configuratie	`JWTOptions.OpenSSL_Options`	API-versie en bibliotheekpad gebruikt door de RS- en ES-algoritmen (`APIVersion`, `LibPath`, `LibPathCustom`, `UnixSymLinks`).

WebAuthn

Wachtwoordloos aanmelden, met één stuk extra

WebAuthn hoort bij het verhaal van sgcAuth, maar is geen derde geregistreerd component in dit pakket. Het wordt geleverd door de WebAuthn-server van sgcWebSockets, en heeft sgcCustomIndy eronder nodig.

Gebied	Detail
Wat het is	W3C Web Authentication Level 2 (WebAuthn): wachtwoordloos aanmelden met passkeys en FIDO2-beveiligingssleutels, aangedreven door `TsgcWSAPIServer_WebAuthn`.
Waar het zich bevindt	`TsgcWSAPIServer_WebAuthn` is een servercomponent, onderdeel van sgcWebSockets Enterprise en All-Access, geen client die door dit pakket wordt geregistreerd.
Wat het nodig heeft	De gepatchte Indy-build die sgcCustomIndy als add-on levert voor sgcWebSockets Core.
Hoe het wordt toegevoegd	De bestelpagina voegt sgcCustomIndy automatisch toe aan je winkelmandje wanneer je sgcAuth bestelt. Heb je al een licentie? Verwijder de regel bij het afrekenen, in beide gevallen zonder extra kosten.
Client-zijde	Een browsergebaseerde JavaScript-toepassing stuurt de WebAuthn-ceremonie aan; sgcHTML levert een kant-en-klaar WebAuthn-inlog-UI-component dat bij de server past.
Passkeys	Aanmelden zonder gebruikersnaam met discoverable credentials, passkey-autofill via conditional mediation, meerdere passkeys per gebruiker, detectie van gesynchroniseerd of aan het toestel gebonden via `BackupEligible` en `BackupState`, en detectie van gekloonde authenticators.

TOTP

Tweede-factor-codes, elk maar één keer geaccepteerd

TsgcTOTPAuthenticator implementeert TOTP (RFC 6238) en HOTP (RFC 4226), de codes die Google Authenticator, Microsoft Authenticator en elke andere authenticator-app tonen.

Mogelijkheid	API	Opmerkingen
Secrets	`GenerateSecret`, `SecretLength`	Een willekeurig Base32-secret, standaard 20 bytes, te bewaren bij het gebruikersrecord.
QR-provisioning	`GetProvisioningURI`, `Issuer`	Bouwt de `otpauth://totp/`-URI met issuer, algoritme, cijfers en periode, klaar om als QR-code te renderen.
Een code verifiëren	`VerifyCode`, `Window`	Accepteert de huidige tijdstap en `Window` stappen ervoor of erna, standaard 1, zodat een telefoonklok die een paar seconden afwijkt nog steeds kan aanmelden.
Replaybescherming	`VerifyCode` met `aLastTimeStep`	Accepteert alleen een tijdstap groter dan de laatst gebruikte en geeft de gevonden stap terug, zodat een code nooit twee keer kan worden gebruikt.
HOTP-tellers	`GenerateHOTP`, `VerifyHOTP`	De tellergebaseerde variant voor hardwaretokens, met een look-ahead-venster dat de teller bij succes opnieuw synchroniseert.
Herstelcodes	`GenerateRecoveryCodes`	Vult elke `TStrings` met unieke eenmalige codes, de fallback voor wanneer de gebruiker het toestel kwijtraakt.
Algoritmes en cijfers	`Algorithm`, `Digits`, `Period`	HMAC-SHA1, de standaard die elke app ondersteunt, HMAC-SHA256 of HMAC-SHA512, met codes van 6 tot 8 cijfers en elke periode.

LDAP

Active Directory-aanmelding via TLS

TsgcLDAPClient is een LDAP v3-client (RFC 4511) die gebruikers authenticeert tegen Active Directory of elke andere LDAP-directory en hun groepen leest.

Mogelijkheid	API	Opmerkingen
Verbinding	`Host`, `Connect`, `BindDN`, `Password`, `BaseDN`	De directoryserver, het serviceaccount voor zoekopdrachten, en de basis van de gebruikers- en groepszoekopdrachten.
LDAPS en StartTLS	`Security`, `TLSOptions`	`ldapsecLDAPS` voor impliciete TLS op poort 636 of `ldapsecStartTLS` op poort 389. Een geweigerde StartTLS sluit de verbinding, de client valt nooit terug op leesbare tekst.
Aanmeldmodi	`AuthenticationMode`, `UserSearchFilter`	`ldapamUPN`, `ldapamDownLevel`, `ldapamSearchThenBind` of `ldapamDN` zetten de ingevoerde naam om in de bind-naam.
Authenticeren	`Authenticate`	Controleert gebruikersnaam en wachtwoord in één aanroep en geeft de DN van de gebruiker terug.
Geneste groepen	`GetUserGroups`	Directe `memberOf`-waarden, of elke groep bereikt via andere groepen met de Active Directory-regel `LDAP_MATCHING_RULE_IN_CHAIN`.
Gepagineerd zoeken	`Search`, `PageSize`, `SizeLimit`, `TimeLimit`	Simple Paged Results wordt automatisch gebruikt, standaard 500 items per pagina, en de items en referrals komen terug in een `TsgcLDAPEntries`-lijst.
Veilige binds	`Bind`, `WhoAmI`, `LastResultCode`, `LastErrorMessage`	Een DN met een leeg wachtwoord wordt geweigerd zonder de server te contacteren, wat de unauthenticated-bind-lek van RFC 4513 afsluit.
Threads	Elke publieke methode	Aanroepen zijn geserialiseerd, zodat één instantie de loginaanvragen van een multithreaded HTTP- of WebSocket-server kan bedienen.

SAML

SAML 2.0 single sign-on

TsgcSAMLServiceProvider maakt van een Delphi-webtoepassing een SAML 2.0 service provider voor Microsoft Entra ID, Okta, AD FS, Google Workspace, Keycloak en andere identity providers.

Mogelijkheid	API	Opmerkingen
Identiteit van de service provider	`EntityID`, `AssertionConsumerServiceURL`	De entity ID en de ACS-URL die de door de browser geposte responses ontvangt.
Metadata in beide richtingen	`GetMetadata`, `LoadIdPMetadata`	`GetMetadata` produceert de SP-metadata om bij de IdP te registreren. `LoadIdPMetadata` vult `IdPEntityID`, `IdPSSOURL`, `IdPSSOBinding` en `IdPCertificates`.
Redirect- en POST-bindings	`GetAuthnRequestRedirectURL`, `GetAuthnRequestPostForm`	De HTTP-Redirect-URL met de gecomprimeerde AuthnRequest, of een automatisch verzonden HTTP-POST-formulier.
Ondertekende requests	`SignAuthnRequests`, `SPCertificate`, `SPPrivateKey`	Ondertekent de AuthnRequest voor identity providers die dit vereisen.
Alleen vertrouwde sleutels	`IdPCertificates`, `AllowSHA1`	Handtekeningen worden alleen gecontroleerd tegen de geconfigureerde IdP-certificaten, nooit een certificaat dat in het bericht is ingesloten. RSA-SHA256, RSA-SHA384 en RSA-SHA512 met exclusieve canonicalisatie, SHA-1 alleen indien toegestaan.
Bescherming tegen signature wrapping	`ProcessResponse`	De response moet exact één assertion als direct kindelement bevatten, en de handtekening moet naar dat element verwijzen.
Assertion-controles	`ClockSkew`, `MaxAssertionAge`, `AllowIdPInitiated`	Issuer, audience, destination, `InResponseTo` en het geldigheidsvenster worden gevalideerd, met een replaycache van assertion-ID's. Door de IdP geïnitieerde login blijft uit totdat het is ingeschakeld.
Resultaat	`TsgcSAMLResult`	`NameID`, `NameIDFormat`, `SessionIndex`, `AuthnInstant`, de `Attributes` met hun vriendelijke namen, en een leesbare `ErrorMessage`.

OpenID Connect

Aanmelden met elke OpenID-provider

TsgcHTTP_OIDC_Client implementeert OpenID Connect Core 1.0 bovenop de OAuth2-client, dus de loopback-redirect, refresh tokens, DPoP, device code, revocation en introspection komen automatisch mee.

Mogelijkheid	API	Opmerkingen
Discovery	`OIDCOptions.Issuer`, `Discover`, `DiscoveryDocument`	Leest de providerconfiguratie en vult de authorization- en token-URL's, `JWKSURI`, `UserInfoEndpoint` en `EndSessionEndpoint`.
Aanmelden	`Start`	Opent de browser en doorloopt de Authorization Code-flow via de lokale redirectserver van de OAuth2-client.
PKCE en nonce	`OIDCOptions.UsePKCE`, `Nonce`	PKCE staat standaard aan en elke aanmelding stuurt een nieuwe nonce die het ID-token moet weerspiegelen.
ID-tokenvalidatie	`IDToken`, `IDTokenClaims`, `IDTokenValid`, `OnOIDCIDToken`	Handtekening, issuer, audience, vervaldatum met `ClockSkew`, en nonce worden gecontroleerd. Alleen RS256, RS384, RS512, ES256 en ES384 worden geaccepteerd, `none` en de HS-algoritmes worden altijd geweigerd.
Sleutelrotatie	`TsgcOIDCJWKS`, `RefetchInterval`	Een thread-safe cache van de ondertekeningssleutels van de provider. Een onbekend key-ID activeert een nieuwe download, zodat sleutelrotatie geen herstart vereist.
Validatie aan serverzijde	`sgcOIDC_ValidateIDToken`, `OIDCOptions.AllowedTenants`	Valideert de bearer-tokens die je REST API of WebSocket-server ontvangt tegen dezelfde sleutelcache, en beperkt multi-tenant Entra ID-apps tot de organisaties die je accepteert.
Userinfo	`GetUserInfo`	Geeft de profiel-JSON van de aangemelde gebruiker terug.

Mail OAuth2

OAuth2 voor SMTP, IMAP en POP3

TsgcMailOAuth2 haalt de tokens op die Microsoft 365 en Gmail voor mail verwachten en vernieuwt ze, en zet ze om in de SASL-strings XOAUTH2 en OAUTHBEARER (RFC 7628) die je mailclient verstuurt.

Mogelijkheid	API	Opmerkingen
Providerpresets	`Provider`, `TenantId`, `ClientId`	`mopMicrosoft365` of `mopGmail` met de juiste endpoints. `mopCustom` gebruikt `CustomAuthURL`, `CustomTokenURL`, `CustomDeviceAuthorizationURL` en `CustomScope`.
Scopes op basis van de protocollen	`Protocols`, `GetScope`	Elke combinatie van `mpSMTP`, `mpIMAP` en `mpPOP3` vraagt de bijbehorende scopes op, met `offline_access` op Microsoft 365.
Browser of device code	`Flow`, `LocalServerOptions`, `OnDeviceCode`	`mofAuthorizationCodePKCE` opent de browser met een loopback-redirect, `mofDeviceCode` past bij services en consoles.
Levenscyclus van het token	`Start`, `Refresh`, `AccessToken`, `RefreshToken`, `ExpiresAt`, `OnTokensChanged`	`Refresh` vernieuwt het access token synchroon en `OnTokensChanged` wordt elke keer geactiveerd, zodat je het nieuwe refresh token kunt bewaren.
SASL-strings	`GetXOAuth2`, `GetOAuthBearer`	De Base64-initiële responses voor `AUTH XOAUTH2` en `AUTH OAUTHBEARER`. De `Raw`-varianten en de `sgcGetXOAuth2`-functies helpen bij debuggen en andere tokenbronnen.
Onafhankelijk van transport	`HTTPClientOptions`	Het component opent nooit een mailverbinding. Gebruik Indy `TIdSMTP`, `TIdIMAP4` of `TIdPOP3`, of elke mailbibliotheek die een ruw SASL-commando kan versturen.