LSA_AP_LOGON_USER_EX função de retorno de chamada (ntsecpkg.h)

Artigo
08/25/2023

Autentica as credenciais de logon de um usuário.

Essa função é chamada pela LSA (Autoridade de Segurança Local ) somente para o logon inicial de um usuário. As solicitações de autenticação subsequentes devem usar LsaCallAuthenticationPackage. Se LsaApLogonUserEx for bem-sucedido, ele criará uma sessão de logon e retornará as informações usadas para criar o token que representa o usuário conectado recentemente.

Essa função difere de LsaApLogonUser , pois o nome do computador é adicionado ao registro de auditoria para a tentativa de logon.

Sintaxe

LSA_AP_LOGON_USER_EX LsaApLogonUserEx;

NTSTATUS LsaApLogonUserEx(
  [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] PUNICODE_STRING *AccountName,
  [out] PUNICODE_STRING *AuthenticatingAuthority,
  [out] PUNICODE_STRING *MachineName
)
{...}

Parâmetros

[in] ClientRequest

Ponteiro para um tipo de dados de LSA_CLIENT_REQUEST opaco que representa a solicitação do cliente LSA.

[in] LogonType

Uma estrutura SECURITY_LOGON_TYPE que identifica o tipo de logon que está sendo tentado.

[in] AuthenticationInformation

Fornece as informações de autenticação específicas para o pacote de autenticação. A LSA liberará esse buffer.

[in] ClientAuthenticationBase

Fornece o endereço das informações de autenticação dentro do processo do cliente. Isso pode ser necessário para remapear quaisquer ponteiros dentro do buffer AuthenticationInformation .

[in] AuthenticationInformationLength

Indica o comprimento do buffer AuthenticationInformation .

[out] ProfileBuffer

Ponteiro que recebe o endereço do buffer de perfil no processo do cliente. O pacote de autenticação é responsável por alocar o buffer ProfileBuffer dentro do processo do cliente chamando a função AllocateClientBuffer . No entanto, se a LSA encontrar posteriormente um erro que impede um logon bem-sucedido, a LSA cuidará da liberação desse buffer.

O conteúdo desse buffer é determinado pelo pacote de autenticação. A LSA não altera esse buffer; ele simplesmente retorna o valor para a função LsaLogonUser .

[out] ProfileBufferLength

Ponteiro para um ULONG que recebe o comprimento do buffer ProfileBuffer , em bytes.

[out] LogonId

Ponteiro para uma variável LUID que recebe a nova ID de logon que identifica exclusivamente essa sessão de logon. O pacote de autenticação é responsável por alocar esse LUID e criar a sessão de logon LSA para esse logon.

[out] SubStatus

Ponteiro para um NTSTATUS que recebe o motivo de falhas devido a restrições de conta. Os valores retornados em SubStatus são determinados pelo pacote de autenticação.

Veja a seguir os valores de SubStatus para os pacotes de autenticação MSV1_0 e Kerberos.

Valor	Significado
STATUS_INVALID_LOGON_HOURS	A conta de usuário tem restrições de tempo e não pode ser usada para fazer logon no momento.
STATUS_INVALID_WORKSTATION	A conta de usuário tem restrições de estação de trabalho e não pode ser usada para fazer logon da estação de trabalho atual.
STATUS_PASSWORD_EXPIRED	A senha da conta de usuário expirou.
STATUS_ACCOUNT_DISABLED	A conta de usuário está desabilitada no momento e não pode ser usada para fazer logon.

Mais informações sobre códigos NTSTATUS podem ser encontradas no arquivo de cabeçalho Subauth.h fornecido com o SDK da Plataforma.

[out] TokenInformationType

Ponteiro que recebe o endereço de um valor LSA_TOKEN_INFORMATION_TYPE que indica o tipo de informações retornadas para inclusão no token a ser criado. As informações são retornadas por meio do parâmetro TokenInformation .

[out] TokenInformation

Ponteiro que recebe o endereço das informações a serem incluídas no token. O formato e o conteúdo de TokenInformation são indicados pelo parâmetro TokenInformationType . Seu pacote de autenticação é responsável por alocar a memória usada por TokenInformation; no entanto, essa memória será liberada pela LSA.

[out] AccountName

Ponteiro para uma estrutura LSA_UNICODE_STRING que recebe o nome da conta de usuário. AccountName sempre deve ser retornado, independentemente do êxito ou falha da chamada; sua cadeia de caracteres está incluída no registro de auditoria para uma tentativa de autenticação. Seu pacote de autenticação é responsável por alocar a memória usada pelo AccountName . Ele será liberado pela LSA.

[out] AuthenticatingAuthority

Opcional. Ponteiro para uma estrutura LSA_UNICODE_STRING que recebe a descrição da autoridade de autenticação para o logon. Esse parâmetro pode ser NULL. Essa cadeia de caracteres está incluída no registro de auditoria para uma tentativa de autenticação. Seu pacote de autenticação é responsável por alocar a memória usada por AuthenticatingAuthority; no entanto, essa memória será liberada pela LSA.

O pacote de autenticação MSV1_0 retorna o nome de domínio do domínio que valida a conta. O pacote de autenticação Kerberos retorna o nome de domínio NetBIOS.

[out] MachineName

Opcional. Ponteiro que recebe o endereço de uma estrutura LSA_UNICODE_STRING que contém o nome da estação de trabalho do cliente. Essas informações estão incluídas no registro de auditoria para uma tentativa de autenticação. Seu pacote de autenticação é responsável por alocar a memória usada pelo MachineName; no entanto, essa memória será liberada pela LSA.

O pacote de autenticação MSV1_0 retorna o nome NetBIOS da estação de trabalho do cliente.

Retornar valor

Se a função for bem-sucedida, ela deverá retornar STATUS_SUCCESS.

Caso contrário, ele deverá retornar um código de erro NTSTATUS, que pode ser um dos valores a seguir ou um dos valores retornados da função de política LSA.

Código de retorno	Descrição
STATUS_NO_MEMORY	Não foi possível concluir o logon porque a cota de memória do cliente é insuficiente para alocar o buffer de retorno.
STATUS_NO_LOGON_SERVERS	Nenhum controlador de domínio está disponível para atender à solicitação de autenticação.
STATUS_LOGON_FAILURE	Falha na tentativa de logon. O motivo da falha não é especificado; os motivos típicos incluem nomes de usuário e senhas com ortografia incorreta.
STATUS_ACCOUNT_RESTRICTION	A conta de usuário e a senha são legítimas, mas as restrições de conta de usuário impedem o logon bem-sucedido no momento.
STATUS_BAD_VALIDATION_CLASS	As informações de autenticação fornecidas são reconhecidas pelo pacote de autenticação.

Os aplicativos de chamada podem usar a função LsaNtStatusToWinError para converter o código NTSTATUS em um código de erro do Windows.

Comentários

Os pacotes de autenticação devem implementar uma das seguintes funções: LsaApLogonUser, LsaApLogonUserEx ou LsaApLogonUserEx2.

LsaApLogonUserEx foi adicionado para certificação C2. C2 é uma classificação de segurança definida pelo governo Estados Unidos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ntsecpkg.h