Fonction LogonUserExA (winbase.h)
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 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 LogonUserExA(
[in] LPCSTR lpszUsername,
[in, optional] LPCSTR lpszDomain,
[in, optional] LPCSTR 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 UPN ( User Principal Name ), user@DNS_domain_name, le paramètre lpszDomain doit avoir la valeur 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 prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
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. La fonction LogonUserEx ne met pas en cache les informations d’identification pour ce type d’ouverture de session. |
|
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. |
|
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. |
|
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 LogonUserEx, vérifier que l’utilisateur peut accéder au système sur le réseau et toujours communiquer avec d’autres serveurs. |
|
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. |
|
Indique une ouverture de session de type service. Le privilège de service doit être activé pour le compte fourni. |
|
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
Fournisseur d’ouverture de session. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Utilisez le fournisseur d’ouverture de session standard pour le système. Le fournisseur de sécurité par défaut est NTLM. |
|
Utilisez le fournisseur d’ouverture de session de négociation. |
|
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é.
Une fois que 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 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 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’à ce que le processus (et tous les processus enfants) se soient terminés.
Si l’appel LogonUserEx 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.
Notes
L’en-tête winbase.h définit LogonUserEx 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 |