Fonction LogonUserA (winbase.h)

Article
03/03/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 vous authentifiez l’utilisateur avec un mot de passe en clair . Si la fonction réussit, vous recevez un handle pour 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, pour créer un processus qui s’exécute dans le contexte de l’utilisateur spécifié.

Syntaxe

BOOL LogonUserA(
  [in]           LPCSTR  lpszUsername,
  [in, optional] LPCSTR  lpszDomain,
  [in, optional] LPCSTR  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 de nom d’utilisateur principal (UPN), User@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 compte lpszUsername . Si ce paramètre a la valeur 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 locale.

[in, optional] lpszPassword

Pointeur vers une chaîne terminée par null qui spécifie le mot de passe en texte clair du 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 par lots, où les processus peuvent s’exécuter pour le compte d’un utilisateur sans intervention directe de celui-ci. Ce type est également destiné aux serveurs plus performants qui traitent de nombreuses tentatives d’authentification en texte clair à la fois, comme les serveurs de messagerie ou web.
LOGON32_LOGON_INTERACTIVE	Ce type d’ouverture de session est destiné aux utilisateurs qui utiliseront l’ordinateur de manière interactive, par exemple un utilisateur connecté par un serveur Terminal Server, un interpréteur de commandes distant ou un processus similaire. Ce type d’ouverture de session a pour coût supplémentaire la 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 tout en empruntant l’identité du client. Un serveur peut accepter les informations d’identification en texte clair d’un client, appeler LogonUser, vérifier que l’utilisateur peut accéder au système sur le réseau et toujours communiquer 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 : À compter de janvier 2023, il n’est pas possible d’utiliser le type d’ouverture de session LOGON32_LOGON_NEW_CREDENTIALS avec un compte de service géré de groupe (gMSA).
LOGON32_LOGON_SERVICE	Indique une ouverture de session de type service. Le privilège de service doit être activé pour le compte fourni.
LOGON32_LOGON_UNLOCK	Les ginAs ne sont plus pris en charge. Windows Server 2003 et Windows XP : Ce type d’ouverture de session est destiné aux DLL GINA qui connectent les 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 prendre les 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 passez la valeur 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 de négociation.
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 retournée

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étaillées sur l’erreur, 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é, pas 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 les serveurs distants ou les 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 peut y accéder.

Le privilège SE_TCB_NAME n’est pas requis 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 ouvrir une session sur un utilisateur avec l’indicateur LOGON32_LOGON_INTERACTIVE, l’utilisateur (ou un groupe auquel appartient l’utilisateur) doit avoir le droit de 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 soient terminés.

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 de point d’entrée NPLogonNotify du fournisseur.

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)

Notes

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll