LSA_AP_LOGON_USER 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 apenas para o logon inicial de um usuário. As solicitações de autenticação subsequentes devem usar LsaCallAuthenticationPackage.

Se LsaApLogonUser for bem-sucedido, ele criará uma sessão de logon. Ele também retorna informações usadas para criar o token que representa o usuário recém-conectado.

Sintaxe

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
)
{...}

Parâmetros

[in] ClientRequest

Ponteiro para um buffer de LSA_CLIENT_REQUEST opaco que representa a solicitação do cliente LSA. Seu pacote de autenticação pode passar esse valor para AllocateClientBuffer e FreeClientBuffer para identificar o processo do cliente no qual a memória deve ser alocada ou liberada.

[in] LogonType

Um valor SECURITY_LOGON_TYPE que identifica o tipo de logon solicitado.

[in] AuthenticationInformation

Fornece as informações de autenticação específicas para o pacote de autenticação. A LSA liberará esse buffer. Esse é o mesmo buffer de entrada passado para LsaLogonUser.

[in] ClientAuthenticationBase

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

[in] AuthenticationInformationLength

Indica o comprimento, em bytes, 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 impeça um logon bem-sucedido, a LSA liberará esse 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 um 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 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.

A tabela a seguir lista 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; ele não pode ser usado para fazer logon no momento.
STATUS_INVALID_WORKSTATION	A conta de usuário tem restrições de estação de trabalho; ele não pode ser usado para fazer logon na estação de trabalho atual.
STATUS_PASSWORD_EXPIRED	A senha da conta de usuário expirou.
STATUS_ACCOUNT_DISABLED	No momento, a conta de usuário está desabilitada 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 enviado com o SDK da Plataforma.

A função LsaNtStatusToWinError converte um código NTSTATUS em um código de erro do Windows.

[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 no buffer TokenInformation .

[out] TokenInformation

Ponteiro que recebe informações a serem incluídas no token. O formato e o conteúdo do buffer 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; no entanto, essa memória será liberada 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.

Valor retornado

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

Se a função falhar, ela 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 incorretas.
STATUS_ACCOUNT_RESTRICTION	A conta de usuário e a senha eram legítimas, mas as restrições de conta de usuário impedem o logon no momento. Para obter informações adicionais, consulte o parâmetro SubStatus .
STATUS_BAD_VALIDATION_CLASS	As informações de autenticação fornecidas não são reconhecidas pelo pacote de autenticação especificado.

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.

Requisitos


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