Funzione LogonUserExExW
La funzione LogonUserExExW tenta di registrare un utente nel computer locale. Il computer locale è il computer da cui è stato chiamato LogonUserExExW . Non è possibile usare LogonUserExW per accedere a un computer remoto. Specificare l'utente usando un nome utente e un dominio e autenticare l'utente usando una password in testo non crittografato. Se la funzione ha esito positivo, riceve 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.
Questa funzione è simile alla funzione LogonUserEx , ad eccezione del fatto che accetta il parametro aggiuntivo pTokenGroups, ovvero un set di uno o più identificatori di sicurezza (SID) aggiunti al token restituito al chiamante quando l'accesso ha esito positivo.
Questa funzione non è dichiarata in un'intestazione pubblica e non ha una libreria di importazione associata. È necessario usare le funzioni LoadLibrary e GetProcAddress per collegare dinamicamente a Advapi32.dll.
Sintassi
BOOL WINAPI LogonUserExExW(
_In_ LPTSTR lpszUsername,
_In_opt_ LPTSTR lpszDomain,
_In_opt_ LPTSTR lpszPassword,
_In_ DWORD dwLogonType,
_In_ DWORD dwLogonProvider,
_In_opt_ PTOKEN_GROUPS pTokenGroups,
_Out_opt_ PHANDLE phToken,
_Out_opt_ PSID *ppLogonSid,
_Out_opt_ PVOID *ppProfileBuffer,
_Out_opt_ LPDWORD pdwProfileLength,
_Out_opt_ PQUOTA_LIMITS pQuotaLimits
);
Parametri
-
lpszUsername [in]
-
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 ), il parametro lpszDomain deve essere NULL.
-
lpszDomain [in, facoltativo]
-
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.
-
lpszPassword [in, facoltativo]
-
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.
-
dwLogonType [in]
-
Tipo di operazione di accesso da eseguire. Questo parametro può avere uno dei valori seguenti.
Valore Significato - LOGON32_LOGON_INTERACTIVE
- 2
Questo tipo di accesso è destinato agli utenti che usano il computer in modo interattivo, ad esempio un utente connesso da un server terminal , una shell remota o un processo simile. Questo tipo di accesso comporta il costo aggiuntivo di 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
- 3
Questo tipo di accesso è destinato ai server ad alte prestazioni per autenticare le password in testo non crittografato. La funzione LogonUserExExW non memorizza nella cache le credenziali per questo tipo di accesso. - LOGON32_LOGON_BATCH
- 4
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 con prestazioni superiori che elaborano molti tentativi di autenticazione in testo non crittografato alla volta, ad esempio i server di posta elettronica o Web. La funzione LogonUserExExW non memorizza nella cache le credenziali per questo tipo di accesso. - LOGON32_LOGON_SERVICE
- 5
Indica un accesso di tipo servizio. L'account specificato deve avere il privilegio di servizio abilitato. - LOGON32_LOGON_UNLOCK
- 7
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 indica quando la workstation è stata sbloccata. - LOGON32_LOGON_NETWORK_CLEARTEXT
- 8
Questo tipo di accesso mantiene il nome e la password nel pacchetto di autenticazione, che consente al server di stabilire connessioni ad altri server di rete durante la rappresentazione del client. Un server può accettare credenziali in testo non crittografato da un client, chiamare LogonUserExW, verificare che l'utente possa accedere al sistema attraverso la rete e comunicare comunque con altri server. - LOGON32_LOGON_NEW_CREDENTIALS
- 9
Questo tipo di accesso consente al chiamante di clonare il token corrente e di 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 . -
dwLogonProvider [in]
-
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 negotiate. - LOGON32_PROVIDER_WINNT40
Utilizzare il provider di accesso NTLM. -
pTokenGroups [in, facoltativo]
-
Puntatore a una struttura TOKEN_GROUPS che specifica un elenco di SID di gruppo aggiunti al token che questa funzione riceve al momento dell'accesso. Tutti i SID aggiunti al token influisce anche sull'espansione del gruppo. Ad esempio, se i SID aggiunti sono membri di gruppi locali, tali gruppi vengono aggiunti anche al token di accesso ricevuto.
Se questo parametro non è NULL, il chiamante di questa funzione deve avere il privilegio SE_TCB_PRIVILEGE concesso e abilitato.
-
phToken [out, facoltativo]
-
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, LogonUserExExW 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 questo handle non è più necessario, chiuderlo chiamando la funzione CloseHandle .
-
ppLogonSid [out, facoltativo]
-
Puntatore a un puntatore a un SID che riceve il SID dell'utente connesso.
Al termine dell'uso del SID, liberarlo chiamando la funzione LocalFree .
-
ppProfileBuffer [out, facoltativo]
-
Puntatore a un puntatore che riceve l'indirizzo di un buffer che contiene il profilo dell'utente connesso.
-
pdwProfileLength [out, facoltativo]
-
Puntatore a un DWORD che riceve la lunghezza del buffer del profilo.
-
pQuotaLimits [out, facoltativo]
-
Puntatore a una struttura di 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.
Osservazioni
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.
L'account specificato da lpszUsername deve avere i diritti di account necessari. Ad esempio, per accedere a un utente con il flag di 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 viene fornito il parametro pTokenGroups facoltativo, LSA non aggiungerà automaticamente il SID locale o il SID di accesso.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato |
Windows Vista [solo app desktop] |
| Server minimo supportato |
Windows Server 2008 [solo app desktop] |
| Versione |
LogonUserExExW è disponibile anche inWindows Server 2003 o Windows XP con la versione di distribuzione generale. |
| Intestazione |
|
| DLL |
|
Vedi anche