LSA_AP_LOGON_USER funzione di callback (ntsecpkg.h)

Articolo
08/25/2023

Autentica le credenziali di accesso di un utente.

Questa funzione viene chiamata solo per l'accesso iniziale di un utente. Le richieste di autenticazione successive devono usare LsaCallAuthenticationPackage.

Se LsaApLogonUser ha esito positivo, crea una sessione di accesso. Restituisce anche informazioni usate per compilare il token che rappresenta l'utente appena connesso.

Sintassi

LSA_AP_LOGON_USER LsaApLogonUser;

NTSTATUS LsaApLogonUser(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID AuthenticationInformation,
  [in]  PVOID ClientAuthenticationBase,
  [in]  ULONG AuthenticationInformationLength,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferLength,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PLSA_UNICODE_STRING *AccountName,
  [out] PLSA_UNICODE_STRING *AuthenticatingAuthority
)
{...}

Parametri

[in] ClientRequest

Puntatore a un buffer LSA_CLIENT_REQUEST opaco che rappresenta la richiesta del client LSA. Il pacchetto di autenticazione può passare questo valore in AllocateClientBuffer e FreeClientBuffer per identificare il processo client in cui è necessario allocare o liberare memoria.

[in] LogonType

Valore SECURITY_LOGON_TYPE che identifica il tipo di accesso richiesto.

[in] AuthenticationInformation

Fornisce le informazioni di autenticazione specifiche per il pacchetto di autenticazione. L'LSA libera questo buffer. Si tratta dello stesso buffer di input passato a LsaLogonUser.

[in] ClientAuthenticationBase

Fornisce l'indirizzo delle informazioni di autenticazione all'interno del processo client. Potrebbe essere necessario eseguire il mapping di tutti i puntatori all'interno del buffer AuthenticationInformation .

[in] AuthenticationInformationLength

Indica la lunghezza, in byte, del buffer AuthenticationInformation .

[out] ProfileBuffer

Puntatore che riceve l'indirizzo del buffer del profilo nel processo client. Il pacchetto di autenticazione è responsabile dell'allocazione del buffer ProfileBuffer all'interno del processo client chiamando la funzione AllocateClientBuffer . Tuttavia, se l'LSA rileva successivamente un errore che impedisce l'accesso corretto, l'LSA libera il buffer.

Il contenuto di questo buffer è determinato dal pacchetto di autenticazione. L'LSA non modifica questo buffer; restituisce semplicemente il valore alla funzione LsaLogonUser .

[out] ProfileBufferLength

Puntatore a un ULONG che riceve la lunghezza del buffer ProfileBuffer , in byte.

[out] LogonId

Puntatore a un LUID che riceve il nuovo ID di accesso che identifica in modo univoco questa sessione di accesso. Il pacchetto di autenticazione è responsabile dell'allocazione di questo LUID e della creazione della sessione di accesso per questo accesso.

[out] SubStatus

Puntatore a un NTSTATUS che riceve il motivo degli errori dovuti alle restrizioni dell'account. I valori restituiti in SubStatus sono determinati dal pacchetto di autenticazione.

Nella tabella seguente sono elencati i valori SubStatus per i pacchetti di autenticazione MSV1_0 e Kerberos.

Valore	Significato
STATUS_INVALID_LOGON_HOURS	L'account utente ha restrizioni di tempo; non può essere usato per accedere in questo momento.
STATUS_INVALID_WORKSTATION	L'account utente ha restrizioni per la workstation; non può essere usato per accedere alla workstation corrente.
STATUS_PASSWORD_EXPIRED	La password dell'account utente è scaduta.
STATUS_ACCOUNT_DISABLED	L'account utente è attualmente disabilitato e non può essere usato per accedere.

Altre informazioni sui codici NTSTATUS sono disponibili nel file di intestazione Subauth.h fornito con Platform SDK.

La funzione LsaNtStatusToWinError converte un codice NTSTATUS in un codice di errore di Windows.

[out] TokenInformationType

Puntatore che riceve l'indirizzo di un valore di LSA_TOKEN_INFORMATION_TYPE che indica il tipo di informazioni restituite per l'inclusione nel token da creare. Le informazioni vengono restituite nel buffer TokenInformation .

[out] TokenInformation

Puntatore che riceve informazioni da includere nel token. Il formato e il contenuto del buffer TokenInformation sono indicati dal parametro TokenInformationType . Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da TokenInformation; tuttavia, questa memoria verrà liberata dall'LSA.

[out] AccountName

Puntatore a una struttura LSA_UNICODE_STRING che riceve il nome dell'account utente. AccountName deve sempre essere restituito indipendentemente dall'esito positivo o negativo della chiamata; la stringa è inclusa nel record di controllo per un tentativo di autenticazione. Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da AccountName; tuttavia, questa memoria verrà liberata dall'LSA.

[out] AuthenticatingAuthority

Facoltativa. Puntatore a una struttura LSA_UNICODE_STRING che riceve la descrizione dell'autorità di autenticazione per l'accesso. Questo parametro può essere NULL. Questa stringa è inclusa nel record di controllo per un tentativo di autenticazione. Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da AuthenticatingAuthority; tuttavia, questa memoria verrà liberata dall'LSA.

Il pacchetto di autenticazione MSV1_0 restituisce il nome di dominio del dominio convalidando l'account. Il pacchetto di autenticazione Kerberos restituisce il nome di dominio NetBIOS.

Valore restituito

Se la funzione ha esito positivo, deve restituire STATUS_SUCCESS.

Se la funzione ha esito negativo, deve restituire un codice di errore NTSTATUS, che può essere uno dei valori seguenti o uno dei valori restituiti della funzione Criteri LSA.

Codice restituito	Descrizione
STATUS_NO_MEMORY	Impossibile completare l'accesso perché la quota di memoria del client non è sufficiente per allocare il buffer restituito.
STATUS_NO_LOGON_SERVERS	Nessun controller di dominio è disponibile per il servizio della richiesta di autenticazione.
STATUS_LOGON_FAILURE	Il tentativo di accesso ha avuto esito negativo. Il motivo dell'errore non è specificato; i motivi tipici includono nomi utente e password sbagliati.
STATUS_ACCOUNT_RESTRICTION	L'account utente e la password erano legittimi, ma le restrizioni dell'account utente impediscono l'accesso in questo momento. Per altre informazioni, vedere il parametro SubStatus .
STATUS_BAD_VALIDATION_CLASS	Le informazioni di autenticazione fornite non vengono riconosciute dal pacchetto di autenticazione specificato.

Le applicazioni chiamanti possono usare la funzione LsaNtStatusToWinError per convertire il codice NTSTATUS in un codice di errore di Windows.

Commenti

I pacchetti di autenticazione devono implementare una delle funzioni seguenti: LsaApLogonUser, LsaApLogonUserEx o LsaApLogonUserEx2.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ntsecpkg.h