Fonction LogonUserW (winbase.h)

Article
11/20/2024

La fonction LogonUser tente de journaliser un utilisateur sur l’ordinateur local. L’ordinateur local est l’ordinateur à partir duquel LogonUser a été appelé. Vous ne pouvez pas utiliser logonUser 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 texte clair mot de passe. 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 LogonUserW(
  [in]           LPCWSTR lpszUsername,
  [in, optional] LPCWSTR lpszDomain,
  [in, optional] LPCWSTR lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

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), @nom d’utilisateur DNSDomainName, 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, définies dans Winbase.h.

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.
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 LogonUser 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 LogonUser, 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. Remarque : Depuis janvier 2023, il n’est pas possible d’utiliser le type d’ouverture de session LOGON32_LOGON_NEW_CREDENTIALS avec un compte de service administré de groupe (gMSA).
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	Les ginas ne sont plus pris en charge. Windows Server 2003 et Windows XP : Ce type d’ouverture de session concerne DLL GINA 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

Spécifie le 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 négocié, sauf si vous transmettez NULL pour le nom de domaine et que le nom d’utilisateur n’est pas au format UPN. Dans ce cas, le fournisseur 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] 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, LogonUser retourne un jeton d’emprunt d’identité que vous ne pouvez pas utiliser dans CreateProcessAsUser, sauf si vous appelez DuplicateTokenEx pour le convertir en jeton principal.

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

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 constantes des droits de compte.

Un utilisateur est considéré comme connecté s’il existe au moins un jeton. Si vous appelez CreateProcessAsUser, puis fermez le jeton, le système considère que l’utilisateur est toujours connecté jusqu’à ce que le processus (et tous les processus enfants) se terminent.

Si l’appel LogonUser réussit, le système avertit 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.

Exemples

Vous pouvez générer un jeton LocalService à l’aide du code suivant.

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

Note

L’en-tête winbase.h définit LogonUser en tant qu’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