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

Artigo
08/25/2023

Usado para autenticar uma tentativa de logon do usuário no logon inicial do usuário. Uma nova sessão de logon é estabelecida para o usuário e as informações de validação para o usuário são retornadas.

Sintaxe

LSA_AP_LOGON_USER_EX2 LsaApLogonUserEx2;

NTSTATUS LsaApLogonUserEx2(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID ProtocolSubmitBuffer,
  [in]  PVOID ClientBufferBase,
  [in]  ULONG SubmitBufferSize,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferSize,
  [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,
  [out] PSECPKG_PRIMARY_CRED PrimaryCredentials,
  [out] PSECPKG_SUPPLEMENTAL_CRED_ARRAY *SupplementalCredentials
)
{...}

Parâmetros

[in] ClientRequest

Ponteiro para um buffer opaco LSA_CLIENT_REQUEST que representa a solicitação do cliente.

[in] LogonType

SECURITY_LOGON_TYPE valor que identifica o tipo de logon.

[in] ProtocolSubmitBuffer

Buffer que fornece as informações de autenticação específicas para o pacote de autenticação.

[in] ClientBufferBase

Buffer que fornece o endereço dentro do processo do cliente no qual as informações de autenticação eram residentes. Isso pode ser necessário para corrigir quaisquer ponteiros dentro do buffer de informações de autenticação.

[in] SubmitBufferSize

Um valor ULONG que indica o tamanho, em bytes, do buffer de informações de autenticação.

[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 ProfileBuffer no 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 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] ProfileBufferSize

Ponteiro para um ULONG que recebe o tamanho do buffer ProfileBuffer .

[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.

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 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; 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.

[out] MachineName

Opcional. Ponteiro que recebe o endereço de uma estrutura de UNICODE_STRING que contém o nome do computador do cliente. Opcionalmente, essa cadeia de caracteres pode ser omitida. Essa cadeia de caracteres está incluída no registro de auditoria para essa 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.

[out] PrimaryCredentials

Ponteiro para uma estrutura SECPKG_PRIMARY_CRED que retorna credenciais primárias para entrega a outros pacotes.

[out] SupplementalCredentials

Ponteiro para uma SECPKG_SUPPLEMENTAL_CRED_ARRAY matriz de credenciais complementares para outros pacotes.

Valor retornado

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_QUOTA_EXCEEDED	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 impediam o logon bem-sucedido 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.
STATUS_INVALID_LOGON_TYPE	LogonType não era válido.
STATUS_LOGON_SESSION_COLLISION	A ID de logon selecionada para esta sessão de logon (no parâmetro LogonId ) já existe.
STATUS_NETLOGON_NOT_STARTED	O banco de dados SAM ou o serviço Netlogon é necessário, mas não está disponível.
STATUS_NO_MEMORY	As cotas de pagefile ou memória virtual do cliente são insuficientes para alocar o buffer de retorno.

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