Tutto quello che fa sgcAuth, mappato sui due componenti client, i grant type e le claim che implementano, e i componenti WebAuthn, TOTP, LDAP, SAML, OpenID Connect e Mail OAuth2 che il pacchetto sblocca insieme a sgcCustomIndy. Ogni funzionalità si comporta allo stesso modo in Delphi e in C++ Builder, e ogni licenza include il codice sorgente completo.
Cinque grant type, un solo componente
Firma, allega o verifica
Passkey, tramite sgcCustomIndy
Codici a due fattori e codici di recupero
Accesso Active Directory su TLS
Single sign-on SAML 2.0
Accesso con validazione dell'ID token
OAuth2 per SMTP, IMAP e POP3
Da Delphi 7 a 13, C++ Builder
sgcAuth è autosufficiente. Viene distribuito con il runtime sgcWebSockets Core incluso, quindi non è un componente aggiuntivo per i client OAuth2 e JWT.
Anche dentro sgcWebSockets. Sia il client OAuth2 sia il client JWT sono inclusi anche nelle edizioni di sgcWebSockets a partire dalla Standard. All-Access include tutto. sgcAuth è il package autonomo per i team che hanno bisogno solo dei client di autenticazione.
Due client per i token e cinque componenti di identità, registrati sulla pagina della palette SGC Auth.
| Componente | Classe | Compito | Descrizione |
|---|---|---|---|
| OAuth2 Client | TsgcHTTP_OAuth2_Client | Ottieni un token | Grant Authorization Code, PKCE, Client Credentials, Resource Owner Password e Device Code contro qualsiasi provider OAuth2/OIDC, con un server locale di redirect integrato. |
| JWT Client | TsgcHTTP_JWT_Client | Firma un token | Crea, firma e verifica JSON Web Token, in autonomia o come sorgente del Bearer token per TsgcWebSocketClient, TsgcHTTP1Client e TsgcHTTP2Client. |
| TOTP Authenticator | TsgcTOTPAuthenticator | Verifica un secondo fattore | Secret TOTP e HOTP, provisioning QR otpauth, verifica dei codici con protezione dai replay e codici di recupero monouso. |
| LDAP Client | TsgcLDAPClient | Verifica una password di directory | Accesso LDAP v3 e Active Directory su LDAPS o StartTLS, appartenenza a gruppi annidati e ricerca paginata. |
| SAML Service Provider | TsgcSAMLServiceProvider | Single sign-on | Service provider SAML 2.0 per Entra ID, Okta, AD FS, Google Workspace e Keycloak, con validazione rigorosa di firma e assertion. |
| OpenID Connect Client | TsgcHTTP_OIDC_Client | Autentica un utente | Discovery, accesso via browser con PKCE e nonce, validazione dell'ID token rispetto alle chiavi del provider ed endpoint userinfo. |
| Mail OAuth2 | TsgcMailOAuth2 | Autentica la posta | Access e refresh token per Microsoft 365 e Gmail, più le stringhe SASL XOAUTH2 e OAUTHBEARER per SMTP, IMAP e POP3. |
TsgcHTTP_OAuth2_Client copre OAuth 2.0 (RFC 6749) end to end: avvia il flusso, intercetta il redirect, scambia il codice con un token e gestisce il token in seguito.
| Funzionalità | API | Note |
|---|---|---|
| Authorization Code | OAuth2Options.GrantType := auth2Code | Il flusso standard per applicazioni web server-side affidabili che possono conservare un client secret. |
| Authorization Code + PKCE | auth2CodePKCE (RFC 7636) | Lo stesso flusso con una Proof Key for Code Exchange, per app native, mobile e single-page che non possono conservare un secret. |
| Client Credentials | auth2ClientCredentials | Chiamate da server a server senza un utente nel mezzo: demoni e account di servizio. |
| Resource Owner Password | auth2ResourceOwnerPassword | L'applicazione raccoglie direttamente la password dell'utente e la scambia con un token. |
| Device Code | auth2DeviceCode (RFC 8628) | Per dispositivi con input limitato, smart TV, console multimediali, IoT: mostra un codice utente che la persona inserisce su un secondo dispositivo. |
| Identità del client | OAuth2Options.ClientId, ClientSecret, Username, Password | Da impostare secondo le specifiche API del tuo provider; Username/Password coprono i provider che richiedono Basic Authentication sull'endpoint del token. |
| Endpoint del provider | AuthorizationServerOptions.AuthURL, TokenURL, Scope, RevocationURL, IntrospectionURL | Gli URL e la lista di scope pubblicati nella documentazione OAuth2/OIDC del tuo provider. |
| Preset social | TsgcHTTP_OAuth2_Client_Google, TsgcHTTP_OAuth2_Client_Microsoft | Discendenti già pronti che preconfigurano gli endpoint e gli scope di Google e Microsoft. |
| Listener di redirect locale | LocalServerOptions.IP, Port, RedirectURL | Il piccolo server HTTP che il componente avvia per ricevere il redirect del codice di autorizzazione; predefinito sulla porta 8080, oppure 0 per scegliere una porta casuale nelle app desktop. |
| Esegui il flusso | Start, Stop | Start apre il browser di sistema (o emette il device code) e avvia il grant configurato; Stop lo interrompe e chiude il listener locale. |
| Refresh | Refresh | Scambia un refresh token con un nuovo access token senza un altro passaggio dal browser. |
| Revoca e introspezione | Revoke (RFC 7009), Introspect (RFC 7662) | Invalida un token, oppure interroga il suo stato e i suoi metadati presso il provider. |
| DPoP | DPoPOptions, GenerateDPoPKeyPair, OnDPoPSign | Materiale della chiave e firma per la Demonstrating Proof-of-Possession (RFC 9449), per i provider che legano i token a una coppia di chiavi. |
| Trasporto HTTP | HTTPClientOptions | Configurazione TLS e log per il client HTTP interno che invia le POST agli endpoint di token, revoca e introspezione. |
| Eventi del ciclo di vita | OnBeforeAuthorizeCode, OnAfterAuthorizeCode, OnBeforeAccessToken, OnAfterAccessToken, OnBeforeRefreshToken, OnAfterRefreshToken | Coppie prima/dopo attorno a ogni passo del flusso. |
| Eventi di errore | OnErrorAccessToken, OnErrorAuthorizeCode, OnErrorRefreshToken, OnErrorRevokeToken, OnErrorIntrospectToken | Uno per ogni punto di fallimento del flusso, ciascuno con l'errore, la descrizione e l'URI del provider. |
| Eventi Device Code | OnDeviceCode, OnDeviceCodeExpired | Consegna il codice utente e l'URI di verifica da mostrare, e scatta se l'utente non completa l'autorizzazione in tempo. |
TsgcHTTP_JWT_Client implementa la RFC 7519 (JSON Web Token), la RFC 7515 (JWS) e la RFC 7516 (JWE) attraverso un'unica proprietà JWTOptions.
| Funzionalità | API | Note |
|---|---|---|
| Header | JWTOptions.Header.alg, typ, kid | L'header JOSE. alg sceglie tra jwtHS256/384/512, jwtRS256/384/512, jwtES256/384/512 o i post-quantum jwtMLDSA44/jwtMLDSA65/jwtMLDSA87; i campi extra passano da Header.AddKeyValue. |
| Payload / claim | JWTOptions.Payload.iss, sub, aud, exp, nbf, iat, jti | Le claim registrate dalla RFC 7519; le claim personalizzate si aggiungono con Payload.AddKeyValue. |
| Materiale della chiave di firma | JWTOptions.Algorithms.HS.Secret, RS.PrivateKey, ES.PrivateKey, MLDSA.PrivateKey | Secret condiviso per HMAC, chiave privata in formato PEM per RSA o ECDSA, PEM PKCS#8 per ML-DSA, selezionati da Header.alg. |
| Firme post-quantum | jwtMLDSA44, jwtMLDSA65, jwtMLDSA87 | Gli algoritmi JWS ML-DSA della RFC 9964, implementati in Pascal puro, quindi su questo percorso non interviene OpenSSL. Il client firma con JWTOptions.Algorithms.MLDSA.PrivateKey, un PEM PKCS#8; un server verifica con JWTOptions.Algorithms.MLDSA.PublicKey, un PEM SubjectPublicKeyInfo, una volta impostato JWTOptions.Algorithms.MLDSA.Enabled. |
| JSON Web Key ML-DSA | sgcMLDSA_ExportPublicJWK, sgcMLDSA_ExportPrivateJWK, sgcMLDSA_ImportJWK, sgcMLDSA_ImportJWKAsPEM | JSON Web Key AKP, per pubblicare una chiave ML-DSA in un JWKS o leggerne una da un provider. |
| Aggiornamento automatico | JWTOptions.RefreshTokenAfter | Se maggiore di zero, Sign aggiorna iat e ricalcola exp automaticamente; 0 rigenera il token a ogni richiesta. |
| Firma indipendente | Sign | Crea, firma e restituisce il token codificato (header.payload.signature) come singola stringa, senza bisogno di un client HTTP o WebSocket. |
| Collegamento a un client | Start, Client.Authentication.Token.JWT | Start firma il JWT configurato e lo consegna come Bearer token al componente ospite; impostalo una volta su Authentication.Token.JWT e ogni richiesta parte firmata. |
| Funziona con | TsgcWebSocketClient, TsgcHTTP1Client, TsgcHTTP2Client | Ognuno dei tre accetta un TsgcHTTP_JWT_Client come sorgente del Bearer token tramite Authentication.Token. |
| Configurazione OpenSSL | JWTOptions.OpenSSL_Options | Versione API e percorso della libreria usati dagli algoritmi RS ed ES (APIVersion, LibPath, LibPathCustom, UnixSymLinks). |
WebAuthn fa parte della proposta di sgcAuth, ma non è un terzo componente registrato in questo pacchetto. È servito dal server WebAuthn di sgcWebSockets, e richiede sgcCustomIndy sotto.
| Ambito | Dettaglio |
|---|---|
| Cos'è | W3C Web Authentication Level 2 (WebAuthn): accesso passwordless con passkey e chiavi di sicurezza FIDO2, gestito da TsgcWSAPIServer_WebAuthn. |
| Dove si trova | TsgcWSAPIServer_WebAuthn è un componente lato server, parte di sgcWebSockets Enterprise e All-Access, non un client registrato da questo pacchetto. |
| Cosa richiede | La build Indy modificata che sgcCustomIndy distribuisce come componente aggiuntivo per sgcWebSockets Core. |
| Come viene aggiunto | La pagina d'ordine aggiunge sgcCustomIndy al tuo carrello automaticamente quando ordini sgcAuth. Possiedi già una licenza? Rimuovi la riga al pagamento, nessun costo extra in entrambi i casi. |
| Lato client | Un'applicazione JavaScript lato browser pilota la cerimonia WebAuthn; sgcHTML distribuisce un componente UI di login WebAuthn già pronto che si abbina al server. |
| Passkey | Accesso senza nome utente con credenziali discoverable, autofill delle passkey tramite conditional mediation, più passkey per utente, rilevamento sincronizzata o legata al dispositivo tramite BackupEligible e BackupState, e rilevamento di authenticator clonati. |
TsgcTOTPAuthenticator implementa TOTP (RFC 6238) e HOTP (RFC 4226), i codici mostrati da Google Authenticator, Microsoft Authenticator e qualsiasi altra app authenticator.
| Funzionalità | API | Note |
|---|---|---|
| Secret | GenerateSecret, SecretLength | Un secret Base32 casuale, 20 byte di default, da memorizzare con il record utente. |
| Provisioning QR | GetProvisioningURI, Issuer | Costruisce l'URI otpauth://totp/ con issuer, algoritmo, cifre e periodo, pronto per essere reso come codice QR. |
| Verifica un codice | VerifyCode, Window | Accetta lo step temporale corrente e Window step prima o dopo di esso, 1 di default, così un orologio del telefono sfasato di pochi secondi riesce comunque ad accedere. |
| Protezione dai replay | VerifyCode con aLastTimeStep | Accetta solo uno step temporale superiore all'ultimo utilizzato e restituisce lo step corrispondente, così un codice non può mai essere usato due volte. |
| Contatori HOTP | GenerateHOTP, VerifyHOTP | La variante basata sul contatore per i token hardware, con una finestra di look-ahead che risincronizza il contatore in caso di successo. |
| Codici di recupero | GenerateRecoveryCodes | Riempie qualsiasi TStrings con codici monouso univoci, il fallback per quando l'utente perde il dispositivo. |
| Algoritmi e cifre | Algorithm, Digits, Period | HMAC-SHA1, il default supportato da tutte le app, HMAC-SHA256 o HMAC-SHA512, con codici da 6 a 8 cifre e qualsiasi periodo. |
TsgcLDAPClient è un client LDAP v3 (RFC 4511) che autentica gli utenti su Active Directory o qualsiasi altra directory LDAP e ne legge i gruppi.
| Funzionalità | API | Note |
|---|---|---|
| Connessione | Host, Connect, BindDN, Password, BaseDN | Il server della directory, l'account di servizio usato per le ricerche e la base delle ricerche di utenti e gruppi. |
| LDAPS e StartTLS | Security, TLSOptions | ldapsecLDAPS per TLS implicito sulla porta 636 o ldapsecStartTLS sulla porta 389. Uno StartTLS rifiutato chiude la connessione, il client non ripiega mai sul testo in chiaro. |
| Modalità di accesso | AuthenticationMode, UserSearchFilter | ldapamUPN, ldapamDownLevel, ldapamSearchThenBind o ldapamDN trasformano il nome digitato nel bind name. |
| Autentica | Authenticate | Verifica nome utente e password in un'unica chiamata e restituisce il DN dell'utente. |
| Gruppi annidati | GetUserGroups | Valori memberOf diretti, oppure ogni gruppo raggiunto attraverso altri gruppi con la regola Active Directory LDAP_MATCHING_RULE_IN_CHAIN. |
| Ricerca paginata | Search, PageSize, SizeLimit, TimeLimit | Simple Paged Results viene usato automaticamente, 500 voci per pagina di default, e voci e referral tornano in una lista TsgcLDAPEntries. |
| Bind sicuri | Bind, WhoAmI, LastResultCode, LastErrorMessage | Un DN con password vuota viene rifiutato senza contattare il server, chiudendo la falla dell'unauthenticated bind della RFC 4513. |
| Thread | Ogni metodo pubblico | Le chiamate sono serializzate, così un'unica istanza può servire le richieste di login di un server HTTP o WebSocket multi-thread. |
TsgcSAMLServiceProvider trasforma un'applicazione web Delphi in un service provider SAML 2.0 per Microsoft Entra ID, Okta, AD FS, Google Workspace, Keycloak e altri identity provider.
| Funzionalità | API | Note |
|---|---|---|
| Identità del service provider | EntityID, AssertionConsumerServiceURL | L'entity ID e l'URL ACS che riceve le risposte inviate dal browser. |
| Metadata in entrambe le direzioni | GetMetadata, LoadIdPMetadata | GetMetadata produce i metadata dell'SP da registrare nell'IdP. LoadIdPMetadata popola IdPEntityID, IdPSSOURL, IdPSSOBinding e IdPCertificates. |
| Binding Redirect e POST | GetAuthnRequestRedirectURL, GetAuthnRequestPostForm | L'URL HTTP-Redirect con l'AuthnRequest compresso, oppure un form HTTP-POST a invio automatico. |
| Richieste firmate | SignAuthnRequests, SPCertificate, SPPrivateKey | Firma l'AuthnRequest per gli identity provider che lo richiedono. |
| Solo chiavi fidate | IdPCertificates, AllowSHA1 | Le firme sono verificate solo rispetto ai certificati IdP configurati, mai un certificato incorporato nel messaggio. RSA-SHA256, RSA-SHA384 e RSA-SHA512 con canonicalizzazione esclusiva, SHA-1 solo se consentito. |
| Protezione dal signature wrapping | ProcessResponse | La risposta deve contenere esattamente un'assertion come figlio diretto, e la firma deve fare riferimento a quell'elemento. |
| Controlli sull'assertion | ClockSkew, MaxAssertionAge, AllowIdPInitiated | Issuer, audience, destination, InResponseTo e la finestra di validità vengono convalidati, con una cache anti-replay degli assertion ID. L'accesso avviato dall'IdP resta disattivato finché non viene abilitato. |
| Risultato | TsgcSAMLResult | NameID, NameIDFormat, SessionIndex, AuthnInstant, gli Attributes con i loro nomi descrittivi, e un ErrorMessage leggibile. |
TsgcHTTP_OIDC_Client implementa OpenID Connect Core 1.0 sopra il client OAuth2, quindi loopback redirect, refresh token, DPoP, device code, revoca e introspection sono già inclusi.
| Funzionalità | API | Note |
|---|---|---|
| Discovery | OIDCOptions.Issuer, Discover, DiscoveryDocument | Legge la configurazione del provider e popola gli URL di authorization e token, JWKSURI, UserInfoEndpoint e EndSessionEndpoint. |
| Accesso | Start | Apre il browser ed esegue il flusso Authorization Code tramite il server di redirect locale del client OAuth2. |
| PKCE e nonce | OIDCOptions.UsePKCE, Nonce | PKCE è attivo di default e ogni accesso invia un nonce nuovo che l'ID token deve rispecchiare. |
| Validazione dell'ID token | IDToken, IDTokenClaims, IDTokenValid, OnOIDCIDToken | Vengono verificati firma, issuer, audience, scadenza con ClockSkew e nonce. Sono accettati solo RS256, RS384, RS512, ES256 ed ES384, none e gli algoritmi HS vengono sempre rifiutati. |
| Rotazione delle chiavi | TsgcOIDCJWKS, RefetchInterval | Una cache thread safe delle chiavi di firma del provider. Un key id sconosciuto attiva un nuovo download, così la rotazione delle chiavi non richiede alcun riavvio. |
| Validazione lato server | sgcOIDC_ValidateIDToken, OIDCOptions.AllowedTenants | Convalida i bearer token ricevuti dalla tua REST API o dal server WebSocket rispetto alla stessa cache delle chiavi, e limita le app multi-tenant di Entra ID alle organizzazioni che accetti. |
| Userinfo | GetUserInfo | Restituisce il JSON del profilo dell'utente che ha effettuato l'accesso. |
TsgcMailOAuth2 ottiene e rinnova i token che Microsoft 365 e Gmail richiedono per la posta, e li trasforma nelle stringhe SASL XOAUTH2 e OAUTHBEARER (RFC 7628) che il tuo client di posta invia.
| Funzionalità | API | Note |
|---|---|---|
| Preset provider | Provider, TenantId, ClientId | mopMicrosoft365 o mopGmail con gli endpoint corretti. mopCustom prende CustomAuthURL, CustomTokenURL, CustomDeviceAuthorizationURL e CustomScope. |
| Scope in base ai protocolli | Protocols, GetScope | Qualsiasi combinazione di mpSMTP, mpIMAP e mpPOP3 richiede gli scope corrispondenti, con offline_access su Microsoft 365. |
| Browser o device code | Flow, LocalServerOptions, OnDeviceCode | mofAuthorizationCodePKCE apre il browser con un loopback redirect, mofDeviceCode è adatto a servizi e console. |
| Ciclo di vita del token | Start, Refresh, AccessToken, RefreshToken, ExpiresAt, OnTokensChanged | Refresh rinnova l'access token in modo sincrono e OnTokensChanged viene generato ogni volta, così puoi salvare il nuovo refresh token. |
| Stringhe SASL | GetXOAuth2, GetOAuthBearer | Le risposte iniziali in Base64 per AUTH XOAUTH2 e AUTH OAUTHBEARER. Le varianti Raw e le funzioni sgcGetXOAuth2 aiutano con il debug e altre fonti di token. |
| Indipendente dal trasporto | HTTPClientOptions | Il componente non apre mai una connessione di posta. Usa Indy TIdSMTP, TIdIMAP4 o TIdPOP3, oppure qualsiasi libreria di posta in grado di inviare un comando SASL raw. |
Specifiche standard, e lo stesso sorgente su ogni compilatore supportato.
| Ambito | Dettaglio |
|---|---|
| Standard 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). |
| Standard JWT | JSON Web Token (RFC 7519), JSON Web Signature (RFC 7515), JSON Web Encryption (RFC 7516), ML-DSA per JOSE (RFC 9964). |
| Standard WebAuthn | Web Authentication Level 2 (W3C), tramite il server WebAuthn di sgcWebSockets. |
| Standard di identità | TOTP (RFC 6238), HOTP (RFC 4226), LDAP v3 (RFC 4511), SAML 2.0 (OASIS), OpenID Connect Core 1.0, SASL OAUTHBEARER (RFC 7628) e XOAUTH2. |
| Piattaforme | Entrambi i client sono HTTPS puro e firma locale, quindi ogni piattaforma Delphi è coperta: Windows Win32/Win64, Linux a 64 bit, macOS, iOS e Android. |
| Compilatori | Delphi e C++ Builder dalla versione 7 alla 13. |
| Edizioni | Il client OAuth2 e il client JWT sono inclusi anche in sgcWebSockets a partire dalla Standard, i componenti WebAuthn, TOTP, LDAP, SAML, OpenID Connect e Mail OAuth2 in Enterprise, e All-Access include tutto. |
| Licenze | Autonomo. Il runtime sgcWebSockets Core è incluso e il codice sorgente completo fa parte della fornitura. |