Fonction LogonUserExW (winbase.h)

Article
11/20/2024

La fonction LogonUserEx tente de journaliser un utilisateur sur l’ordinateur local. L’ordinateur local est l’ordinateur à partir duquel LogonUserEx a été appelé. Vous ne pouvez pas utiliser LogonUserEx pour vous connecter à un ordinateur distant. Vous spécifiez l’utilisateur avec un nom d’utilisateur et un domaine et authentifier l’utilisateur avec un mot de passe en texte clair. Si la fonction réussit, vous recevez un handle vers un jeton qui représente l’utilisateur connecté. Vous pouvez ensuite utiliser ce handle de jeton pour emprunter l’identité de l’utilisateur spécifié ou, dans la plupart des cas, créer un processus qui s’exécute dans le contexte de l’utilisateur spécifié.

Syntaxe

BOOL LogonUserExW(
  [in]            LPCWSTR       lpszUsername,
  [in, optional]  LPCWSTR       lpszDomain,
  [in, optional]  LPCWSTR       lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

Paramètres

[in] lpszUsername

Pointeur vers une chaîne terminée par null qui spécifie le nom de l’utilisateur. Il s’agit du nom du compte d’utilisateur auquel se connecter. Si vous utilisez le format nom d’utilisateur principal (UPN), user@DNS_domain_name, le paramètre lpszDomain doit être NULL.

[in, optional] lpszDomain

Pointeur vers une chaîne terminée par null qui spécifie le nom du domaine ou du serveur dont la base de données de compte contient le lpszUsername compte. Si ce paramètre est NULL, le nom d’utilisateur doit être spécifié au format UPN. Si ce paramètre est « ». La fonction valide le compte en utilisant uniquement la base de données de compte local.

[in, optional] lpszPassword

Pointeur vers une chaîne terminée par null qui spécifie le mot de passe en texte clair pour le compte d’utilisateur spécifié par lpszUsername. Lorsque vous avez terminé d’utiliser le mot de passe, effacez le mot de passe de la mémoire en appelant la fonction SecureZeroMemory. Pour plus d’informations sur la protection des mots de passe, consultez Gestion des mots de passe.

[in] dwLogonType

Type d’opération d’ouverture de session à effectuer. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
LOGON32_LOGON_BATCH	Ce type d’ouverture de session est destiné aux serveurs batch, où les processus peuvent s’exécuter pour le compte d’un utilisateur sans leur intervention directe. Ce type est également destiné aux serveurs de performances plus performants qui traitent de nombreuses tentatives d’authentification en texte clair à la fois, telles que la messagerie ou les serveurs web. La fonction LogonUserEx ne met pas en cache les informations d’identification pour ce type d’ouverture de session.
LOGON32_LOGON_INTERACTIVE	Ce type d’ouverture de session est destiné aux utilisateurs qui utilisent l’ordinateur de manière interactive, par exemple un utilisateur connecté par un terminal serveur, un interpréteur de commandes distant ou un processus similaire. Ce type d’ouverture de session a les frais supplémentaires de mise en cache des informations d’ouverture de session pour les opérations déconnectées ; par conséquent, il est inapproprié pour certaines applications client/serveur, telles qu’un serveur de messagerie.
LOGON32_LOGON_NETWORK	Ce type d’ouverture de session est destiné aux serveurs hautes performances pour authentifier les mots de passe en texte clair. La fonction LogonUserEx ne met pas en cache les informations d’identification pour ce type d’ouverture de session.
LOGON32_LOGON_NETWORK_CLEARTEXT	Ce type d’ouverture de session conserve le nom et le mot de passe dans le package d’authentification , ce qui permet au serveur d’établir des connexions à d’autres serveurs réseau lors de l’emprunt d’identité du client. Un serveur peut accepter des informations d’identification en texte clair à partir d’un client, appeler LogonUserEx, vérifier que l’utilisateur peut accéder au système sur le réseau et communiquer toujours avec d’autres serveurs.
LOGON32_LOGON_NEW_CREDENTIALS	Ce type d’ouverture de session permet à l’appelant de cloner son jeton actuel et de spécifier de nouvelles informations d’identification pour les connexions sortantes. La nouvelle session d’ouverture de session a le même identificateur local, mais utilise des informations d’identification différentes pour d’autres connexions réseau. Ce type d’ouverture de session est pris en charge uniquement par le fournisseur d’ouverture de session LOGON32_PROVIDER_WINNT50.
LOGON32_LOGON_SERVICE	Indique une ouverture de session de type de service. Le compte fourni doit avoir le privilège de service activé.
LOGON32_LOGON_UNLOCK	Ce type d’ouverture de session concerne GINA DLL qui se connectent aux utilisateurs qui utiliseront l’ordinateur de manière interactive. Ce type d’ouverture de session peut générer un enregistrement d’audit unique qui indique quand la station de travail a été déverrouillée.

[in] dwLogonProvider

Fournisseur d’ouverture de session. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
LOGON32_PROVIDER_DEFAULT	Utilisez le fournisseur d’ouverture de session standard pour le système. Le fournisseur de sécurité par défaut est NTLM.
LOGON32_PROVIDER_WINNT50	Utilisez le fournisseur d’ouverture de session negotiate.
LOGON32_PROVIDER_WINNT40	Utilisez le fournisseur d’ouverture de session NTLM.

[out, optional] phToken

Pointeur vers une variable de handle qui reçoit un handle vers un jeton qui représente l’utilisateur spécifié.

Vous pouvez utiliser le handle retourné dans les appels à la fonction ImpersonateLoggedOnUser.

Dans la plupart des cas, le handle retourné est un jeton principal que vous pouvez utiliser dans les appels à la fonction CreateProcessAsUser. Toutefois, si vous spécifiez l’indicateur LOGON32_LOGON_NETWORK, LogonUserEx retourne un jeton d’emprunt d’identité que vous ne pouvez pas utiliser dans CreateProcessAsUser, sauf si vous appelez DuplicateTokenEx pour convertir le jeton d’emprunt d’identité en jeton principal.

Lorsque vous n’avez plus besoin de ce handle, fermez-le en appelant la fonction CloseHandle.

[out, optional] ppLogonSid

Pointeur vers un pointeur vers un identificateur de sécurité (SID) qui reçoit le SID de l’utilisateur connecté.

Lorsque vous avez terminé d’utiliser le SID, libérez-le en appelant la fonction LocalFree.

[out, optional] ppProfileBuffer

Pointeur vers un pointeur qui reçoit l’adresse d’une mémoire tampon qui contient le profil de l’utilisateur connecté.

[out, optional] pdwProfileLength

Pointeur vers un DWORD qui reçoit la longueur de la mémoire tampon de profil.

[out, optional] pQuotaLimits

Pointeur vers une structure QUOTA_LIMITS qui reçoit des informations sur les quotas de l’utilisateur connecté.

Valeur de retour

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Le type d’ouverture de session LOGON32_LOGON_NETWORK est le plus rapide, mais il présente les limitations suivantes :

La fonction retourne un jeton d’emprunt d’identité , et non un jeton principal. Vous ne pouvez pas utiliser ce jeton directement dans la fonction CreateProcessAsUser. Toutefois, vous pouvez appeler la fonction DuplicateTokenEx pour convertir le jeton en jeton principal, puis l’utiliser dans CreateProcessAsUser.
Si vous convertissez le jeton en jeton principal et que vous l’utilisez dans CreateProcessAsUser pour démarrer un processus, le nouveau processus ne peut pas accéder à d’autres ressources réseau, telles que des serveurs distants ou des imprimantes, via le redirecteur. Une exception est que si la ressource réseau n’est pas contrôlée par l’accès, le nouveau processus pourra y accéder.

Le privilège SE_TCB_NAME n’est pas nécessaire pour cette fonction, sauf si vous vous connectez à un compte Passport.

Le compte spécifié par lpszUsername doit disposer des droits de compte nécessaires. Par exemple, pour vous connecter à un utilisateur avec l’indicateur LOGON32_LOGON_INTERACTIVE, l’utilisateur (ou un groupe auquel appartient l’utilisateur) doit disposer du droit du compte SE_INTERACTIVE_LOGON_NAME. Pour obtenir la liste des droits de compte qui affectent les différentes opérations d’ouverture de session, consultez droits d’accès aux objets de compte.

Un utilisateur est considéré comme connecté s’il existe au moins un jeton. Si vous appelez CreateProcessAsUser, puis fermez le jeton, l’utilisateur est toujours connecté jusqu’à la fin du processus (et de tous les processus enfants).

Si l’appel logonUserEx réussit, le système informe les fournisseurs réseau que l’ouverture de session s’est produite en appelant la fonction npLogonNotify du fournisseur fonction de point d’entrée.

Note

L’en-tête winbase.h définit LogonUserEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll