Funzione LogonUserExW (winbase.h)

Articolo
08/27/2023

La funzione LogonUserEx tenta di registrare un utente nel computer locale. Il computer locale è il computer da cui è stato chiamato LogonUserEx . Non è possibile usare LogonUserEx per accedere a un computer remoto. Specificare l'utente con un nome utente e un dominio e autenticare l'utente con una password di testo non crittografato. Se la funzione ha esito positivo, viene visualizzato un handle a un token che rappresenta l'utente connesso. È quindi possibile usare questo handle di token per rappresentare l'utente specificato o, nella maggior parte dei casi, per creare un processo eseguito nel contesto dell'utente specificato.

Sintassi

BOOL LogonUserExW(
  [in]            LPCWSTR       lpszUsername,
  [in, optional]  LPCWSTR       lpszDomain,
  [in, optional]  LPCWSTR       lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

Parametri

[in] lpszUsername

Puntatore a una stringa con terminazione null che specifica il nome dell'utente. Si tratta del nome dell'account utente a cui accedere. Se si usa il formato UPN ( User Principal Name ), user@DNS_domain_name, il parametro lpszDomain deve essere NULL.

[in, optional] lpszDomain

Puntatore a una stringa con terminazione null che specifica il nome del dominio o del server il cui database account contiene l'account lpszUsername . Se questo parametro è NULL, il nome utente deve essere specificato in formato UPN. Se questo parametro è ".", la funzione convalida l'account usando solo il database dell'account locale.

[in, optional] lpszPassword

Puntatore a una stringa con terminazione null che specifica la password di testo non crittografato per l'account utente specificato da lpszUsername. Al termine dell'uso della password, cancellare la password dalla memoria chiamando la funzione SecureZeroMemory . Per altre informazioni sulla protezione delle password, vedere Gestione delle password.

[in] dwLogonType

Tipo di operazione di accesso da eseguire. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
LOGON32_LOGON_BATCH	Questo tipo di accesso è destinato ai server batch, in cui i processi possono essere eseguiti per conto di un utente senza l'intervento diretto. Questo tipo è anche per server di prestazioni superiori che elaborano molti tentativi di autenticazione di testo non crittografato alla volta, ad esempio posta elettronica o server Web. La funzione LogonUserEx non memorizza nella cache le credenziali per questo tipo di accesso.
LOGON32_LOGON_INTERACTIVE	Questo tipo di accesso è destinato agli utenti che saranno in modo interattivo usando il computer, ad esempio un utente connesso da un server terminale , una shell remota o un processo simile. Questo tipo di accesso ha le spese aggiuntive per la memorizzazione nella cache delle informazioni di accesso per le operazioni disconnesse; pertanto, è inappropriato per alcune applicazioni client/server, ad esempio un server di posta elettronica.
LOGON32_LOGON_NETWORK	Questo tipo di accesso è destinato ai server ad alte prestazioni per autenticare le password di testo non crittografato. La funzione LogonUserEx non memorizza nella cache le credenziali per questo tipo di accesso.
LOGON32_LOGON_NETWORK_CLEARTEXT	Questo tipo di accesso mantiene il nome e la password nel pacchetto di autenticazione, che consente al server di effettuare connessioni ad altri server di rete durante la rappresentazione del client. Un server può accettare credenziali di testo non crittografato da un client, chiamare LogonUserEx, verificare che l'utente possa accedere al sistema attraverso la rete e comunque comunicare con altri server.
LOGON32_LOGON_NEW_CREDENTIALS	Questo tipo di accesso consente al chiamante di clonare il token corrente e specificare nuove credenziali per le connessioni in uscita. La nuova sessione di accesso ha lo stesso identificatore locale, ma usa credenziali diverse per altre connessioni di rete. Questo tipo di accesso è supportato solo dal provider di accesso LOGON32_PROVIDER_WINNT50.
LOGON32_LOGON_SERVICE	Indica un accesso di tipo servizio. L'account fornito deve avere il privilegio del servizio abilitato.
LOGON32_LOGON_UNLOCK	Questo tipo di accesso è per le DLL GINA che accedono agli utenti che verranno usati in modo interattivo nel computer. Questo tipo di accesso può generare un record di controllo univoco che mostra quando la workstation è stata sbloccata.

[in] dwLogonProvider

Provider di accesso. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
LOGON32_PROVIDER_DEFAULT	Usare il provider di accesso standard per il sistema. Il provider di sicurezza predefinito è NTLM.
LOGON32_PROVIDER_WINNT50	Usare il provider di accesso negoziata.
LOGON32_PROVIDER_WINNT40	Usare il provider di accesso NTLM.

[out, optional] phToken

Puntatore a una variabile handle che riceve un handle a un token che rappresenta l'utente specificato.

È possibile usare l'handle restituito nelle chiamate alla funzione ImpersonateLoggedOnUser .

Nella maggior parte dei casi, l'handle restituito è un token primario che è possibile usare nelle chiamate alla funzione CreateProcessAsUser . Tuttavia, se si specifica il flag LOGON32_LOGON_NETWORK, LogonUserEx restituisce un token di rappresentazione che non è possibile usare in CreateProcessAsUser a meno che non si chiami DuplicateTokenEx per convertire il token di rappresentazione in un token primario.

Quando non è più necessario questo handle, chiuderlo chiamando la funzione CloseHandle .

[out, optional] ppLogonSid

Puntatore a un puntatore a un identificatore di sicurezza (SID) che riceve il SID dell'utente connesso.

Al termine dell'uso del SID, liberarlo chiamando la funzione LocalFree .

[out, optional] ppProfileBuffer

Puntatore a un puntatore che riceve l'indirizzo di un buffer contenente il profilo dell'utente connesso.

[out, optional] pdwProfileLength

Puntatore a un DWORD che riceve la lunghezza del buffer del profilo.

[out, optional] pQuotaLimits

Puntatore a una struttura QUOTA_LIMITS che riceve informazioni sulle quote per l'utente connesso.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il tipo di accesso LOGON32_LOGON_NETWORK è più veloce, ma presenta le limitazioni seguenti:

La funzione restituisce un token di rappresentazione, non un token primario. Non è possibile usare questo token direttamente nella funzione CreateProcessAsUser . È tuttavia possibile chiamare la funzione DuplicateTokenEx per convertire il token in un token primario e quindi usarla in CreateProcessAsUser.
Se si converte il token in un token primario e lo si usa in CreateProcessAsUser per avviare un processo, il nuovo processo non può accedere ad altre risorse di rete, ad esempio server remoti o stampanti, tramite il reindirizzamento. Un'eccezione è che se la risorsa di rete non è controllata, il nuovo processo sarà in grado di accedervi.

Il privilegio SE_TCB_NAME non è necessario per questa funzione, a meno che non si stia accedendo a un account Passport.

L'account specificato da lpszUsername deve avere i diritti di account necessari. Ad esempio, per accedere a un utente con il flag LOGON32_LOGON_INTERACTIVE, l'utente (o un gruppo a cui appartiene l'utente) deve avere il diritto di SE_INTERACTIVE_LOGON_NAME account. Per un elenco dei diritti dell'account che influiscono sulle varie operazioni di accesso, vedere Diritti di accesso all'oggetto account.

Un utente viene considerato connesso se esiste almeno un token. Se si chiama CreateProcessAsUser e quindi si chiude il token, l'utente è ancora connesso fino alla fine del processo (e di tutti i processi figlio).

Se la chiamata LogonUserEx ha esito positivo, il sistema notifica ai provider di rete che l'accesso si è verificato chiamando la funzione NPLogonNotify del provider.

Nota

L'intestazione winbase.h definisce LogonUserEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll