Partager via


Fonction CredUIPromptForCredentialsA (wincred.h)

La fonction CredUIPromptForCredentials crée et affiche une boîte de dialogue configurable qui accepte les informations d’identification d’un utilisateur.

Les applications qui ciblent Windows Vista ou Windows Server 2008 doivent appeler CredUIPromptForWindowsCredentials au lieu de cette fonction, pour les raisons suivantes :

Syntaxe

CREDUIAPI DWORD CredUIPromptForCredentialsA(
  [in, optional] PCREDUI_INFOA pUiInfo,
  [in]           PCSTR         pszTargetName,
  [in]           PCtxtHandle   pContext,
  [in, optional] DWORD         dwAuthError,
  [in, out]      PSTR          pszUserName,
  [in]           ULONG         ulUserNameBufferSize,
  [in, out]      PSTR          pszPassword,
  [in]           ULONG         ulPasswordBufferSize,
  [in, out]      BOOL          *save,
  [in]           DWORD         dwFlags
);

Paramètres

[in, optional] pUiInfo

Pointeur vers une structure CREDUI_INFO qui contient des informations pour personnaliser l’apparence de la boîte de dialogue.

[in] pszTargetName

Pointeur vers une chaîne terminée par un caractère Null qui contient le nom de la cible pour les informations d’identification, généralement un nom de serveur. Pour les connexions du système de fichiers distribué (DFS), cette chaîne se présente sous la forme ServerName\ShareName. Ce paramètre est utilisé pour identifier les informations cibles lors du stockage et de la récupération des informations d’identification.

[in] pContext

Ce paramètre est réservé à un usage futur. Elle doit être NULL.

[in, optional] dwAuthError

Spécifie la raison pour laquelle la boîte de dialogue d’informations d’identification est nécessaire. Un appelant peut passer ce paramètre d’erreur Windows, retourné par un autre appel d’authentification, pour permettre à la boîte de dialogue de prendre en charge certaines erreurs. Par exemple, si le mot de passe a expiré status code est passé, la boîte de dialogue peut inviter l’utilisateur à modifier le mot de passe sur le compte.

[in, out] pszUserName

Pointeur vers une chaîne terminée par null qui contient le nom d’utilisateur pour les informations d’identification. Si une chaîne de longueur différente de zéro est transmise, l’option UserName de la boîte de dialogue est préremplie avec la chaîne. Dans le cas d’informations d’identification autres que userName/Password, un format marshalé des informations d’identification peut être transmis. Cette chaîne est créée en appelant CredMarshalCredential.

Cette fonction copie le nom fourni par l’utilisateur dans cette mémoire tampon, en copiant un maximum de caractères ulUserNameMaxChars . Ce format peut être converti au format UserName/Password à l’aide de CredUIParseUsername. Un format marshalé peut être passé directement à un fournisseur de support de sécurité (SSP).

Si l’indicateur de CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’une forme qui ne doit pas être inspectée, imprimée ou conservée, autre que la transmettre à CredUIParseUsername. Les résultats suivants de CredUIParseUsername peuvent être transmis uniquement à une fonction d’authentification côté client telle que WNetAddConnection ou une fonction SSP.

Si aucun domaine ou serveur n’est spécifié dans le cadre de ce paramètre, la valeur du paramètre pszTargetName est utilisée comme domaine pour former une paire DomainName\UserName . À la sortie, ce paramètre reçoit une chaîne qui contient cette paire DomainName\UserName .

[in] ulUserNameBufferSize

Nombre maximal de caractères pouvant être copiés dans pszUserName , y compris le caractère null de fin.

Note CREDUI_MAX_USERNAME_LENGTH n’inclut pas le caractère null de fin.
 

[in, out] pszPassword

Pointeur vers une chaîne terminée par null qui contient le mot de passe des informations d’identification. Si une chaîne de longueur différente de zéro est spécifiée pour pszPassword, l’option de mot de passe de la boîte de dialogue est préremplie avec la chaîne.

Cette fonction copie le mot de passe fourni par l’utilisateur dans cette mémoire tampon, en copiant un maximum de caractères ulPasswordMaxChars . Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’une forme qui ne doit pas être inspectée, imprimée ou conservée, autre que la transmettre à une fonction d’authentification côté client telle que WNetAddConnection ou une fonction SSP.

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] ulPasswordBufferSize

Nombre maximal de caractères pouvant être copiés dans pszPassword , y compris le caractère null de fin.

Note CREDUI_MAX_PASSWORD_LENGTH n’inclut pas le caractère null de fin.
 

[in, out] save

Pointeur vers un boOL qui spécifie l’état initial de la zone Enregistrer case activée et reçoit l’état de la zone Enregistrer case activée une fois que l’utilisateur a répondu à la boîte de dialogue. Si cette valeur n’est pas NULL et que CredUIPromptForCredentials retourne NO_ERROR, pfSave retourne l’état de la zone Enregistrer case activée lorsque l’utilisateur a choisi OK dans la boîte de dialogue.

Si l’indicateur CREDUI_FLAGS_PERSIST est spécifié, la zone Enregistrer case activée n’est pas affichée, mais est considérée comme sélectionnée.

Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST est spécifié et que CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX n’est pas spécifié, la zone Enregistrer case activée n’est pas affichée, mais est considérée comme désactivée.

Une application qui doit utiliser CredUI pour inviter l’utilisateur à entrer des informations d’identification, mais qui n’a pas besoin des services de gestion des informations d’identification fournis par le gestionnaire d’informations d’identification, peut utiliser pfSave pour recevoir l’état de la zone Enregistrer case activée une fois que l’utilisateur a fermé la boîte de dialogue. Pour ce faire, l’appelant doit spécifier CREDUI_FLAGS_DO_NOT_PERSIST et CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX dans dwFlags. Lorsque CREDUI_FLAGS_DO_NOT_PERSIST et CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX sont définis, l’application est responsable de l’examen de *pfSave après le retour de la fonction, et si *pfSave a la valeur TRUE, l’application doit prendre l’action appropriée pour enregistrer les informations d’identification de l’utilisateur dans les ressources de l’application.

[in] dwFlags

Valeur DWORD qui spécifie un comportement spécial pour cette fonction. Cette valeur peut être une combinaison ou au niveau du bit de zéro ou plus des valeurs suivantes.

Valeur Signification
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
Spécifie qu’une interface utilisateur s’affiche même si les informations d’identification peuvent être retournées à partir d’informations d’identification existantes dans le gestionnaire d’informations d’identification. Cet indicateur n’est autorisé que si CREDUI_FLAGS_GENERIC_CREDENTIALS est également spécifié.
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
Remplissez la zone de liste déroulante avec l’invite de nom d’utilisateur.
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
Ne stockez pas d’informations d’identification ni n’affichez case activée zones. Vous pouvez passer CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX avec cet indicateur pour afficher la zone Enregistrer case activée uniquement, et le résultat est retourné dans le paramètre de sortie pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
Remplissez la zone de liste modifiable avec le nom d’utilisateur/mot de passe uniquement. N’affichez pas de certificats ou de cartes à puce dans la zone de liste déroulante.
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
Spécifie que l’appelant appelleRa CredUIConfirmCredentials après avoir vérifié si les informations d’identification retournées sont réellement valides. Ce mécanisme garantit que les informations d’identification non valides ne sont pas enregistrées dans le gestionnaire d’informations d’identification. Spécifiez cet indicateur dans tous les cas, sauf si CREDUI_FLAGS_DO_NOT_PERSIST est spécifié.
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
Considérez les informations d’identification entrées par l’utilisateur comme des informations d’identification génériques.
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
Informez l’utilisateur des informations d’identification insuffisantes en affichant l’info-bulle « Échec de l’ouverture de session ».
CREDUI_FLAGS_KEEP_USERNAME
0x100000
N’autorisez pas l’utilisateur à modifier le nom d’utilisateur fourni.
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
Remplissez la zone de liste déroulante avec le mot de passe uniquement. N’autorisez pas la saisie d’un nom d’utilisateur.
CREDUI_FLAGS_PERSIST
0x01000
N’affichez pas la zone Enregistrer case activée, mais les informations d’identification sont enregistrées comme si la zone était affichée et sélectionnée.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
Remplissez la zone de liste modifiable avec les administrateurs locaux uniquement. Windows XP Édition Familiale : Cet indicateur filtre le compte Administrateur connu.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
Remplissez la zone de liste modifiable avec des certificats et des cartes à puce uniquement. N’autorisez pas la saisie d’un nom d’utilisateur.
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
Remplissez la zone de liste modifiable avec des certificats ou des cartes à puce uniquement. N’autorisez pas la saisie d’un nom d’utilisateur.
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
Cet indicateur n’est significatif que dans la recherche d’informations d’identification correspondantes pour préremplir la boîte de dialogue en cas d’échec de l’authentification. Lorsque cet indicateur est spécifié, les informations d’identification génériques ne sont pas mises en correspondance. Elle n’a aucun effet lors de l’écriture d’informations d’identification. CredUI ne crée pas d’informations d’identification contenant des caractères génériques. Tous les trouvés ont été créés explicitement par l’utilisateur ou créés par programmation, comme cela se produit lorsqu’une connexion RAS est établie.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
Si la zone case activée est sélectionnée, affichez la zone Enregistrer case activée et retournez TRUE dans le paramètre de sortie pfSave ; sinon, retournez FALSE. La case à cocher utilise la valeur dans pfSave par défaut.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
Les informations d’identification sont des informations d’identification « runas ». Le paramètre TargetName spécifie le nom de la commande ou du programme en cours d’exécution. Il est utilisé à des fins d’invite uniquement.
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
Vérifiez que le nom d’utilisateur est valide.

Valeur retournée

La valeur de retour est un DWORD et peut être l’une des valeurs suivantes.

Valeur Description
ERROR_CANCELLED
L’utilisateur a choisi Annuler. Les paramètres pszUserName et pszPassword n’ont pas changé.
ERROR_INVALID_FLAGS
Cette status est retournée pour toutes les configurations d’indicateur qui ne sont pas valides.
ERROR_INVALID_PARAMETER
PszTargetName a la valeur NULL, la chaîne vide ou est plus long que CREDUI_MAX_DOMAIN_LENGTH, ou pUiInfo n’a pas la valeur NULL et la structure CredUI_INFO pointée n’a pas satisfait à l’une des exigences suivantes :
  • Le membre cbSize doit être un.
  • Si le membre hbmBanner n’est pas NULL, il doit être de type OBJ_BITMAP.
  • Si le membre pszMessageText n’est pas NULL, il ne doit pas être supérieur à CREDUI_MAX_MESSAGE_LENGTH.
  • Si le membre pszCaptionText n’est pas NULL, il ne doit pas être supérieur à CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION
Impossible d’utiliser le gestionnaire d’informations d’identification. En règle générale, cette erreur est gérée en appelant CredUIPromptForCredentials et en passant l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR
L’utilisateur a choisi OK. Les paramètres pszUserName, pszPassword et pfSave retournent les valeurs documentées précédemment.

Remarques

La fonction CredUIPromptForCredentials crée et affiche une boîte de dialogue modale d’application. Une fois la boîte de dialogue affichée et jusqu’à ce qu’elle soit fermée par l’utilisateur ou l’application, aucune autre fenêtre de l’application ne peut devenir active.

Les indicateurs CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE et CREDUI_FLAGS_EXCLUDE_CERTIFICATE s’excluent mutuellement.

Si CREDUI_FLAGS_DO_NOT_PERSIST est spécifié, pszTargetName doit être spécifié ou uiInfo-pszMessageText> et uiInfo-pszCaption> doivent être spécifiés.

Les indicateurs CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS et CREDUI_FLAGS_GENERIC_CREDENTIALS s’excluent mutuellement. Si aucun des deux n’est spécifié, les informations d’identification sont des informations d’identification de domaine.

Un certificat X509 doit avoir une valeur d’utilisation améliorée de la clé (EKU) de szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) pour être affiché.

Windows XP : Cette valeur EKU n’est pas requise pour afficher les certificats X509.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS n’est pas spécifié ou si CREDUI_FLAGS_COMPLETE_USERNAME est spécifié, la syntaxe du nom est vérifiée. La vérification de la syntaxe applique les mêmes règles que celles appliquées par CredUIParseUserName. Si le nom tapé n’est pas valide, l’utilisateur est invité à en fournir un valide. Si la partie domaine du nom typé est manquante, une partie est fournie en fonction du nom cible.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et CREDUI_FLAGS_VALIDATE_USERNAME est également spécifié, la syntaxe du nom typé est vérifiée. Si le nom tapé n’est pas valide, l’utilisateur est invité à en fournir un valide.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME ne l’est, la syntaxe du nom typé n’est pas vérifiée.

Si ni CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST n’est défini, la zone Enregistrer case activée s’affiche et contrôle si les informations d’identification sont enregistrées.

Modes d’appel

  • L’appelant tente d’accéder à la ressource cible, appelle credui (en passant une description de la ressource cible et de l’échec status), appelle CredUIParseUserName, accède à nouveau à la ressource cible, puis appelle CredUIConfirmCredentials.
  • L’appelant peut demander des informations d’identification sans accéder aux ressources en passant CREDUI_FLAGS_DO_NOT_PERSIST.
  • Pour les informations d’identification génériques, il n’existe aucun package d’authentification. Par conséquent, l’application doit accéder aux informations d’identification pour effectuer l’authentification. Invitez les informations d’identification, sans passer CREDUI_FLAGS_ALWAYS_SHOW_UI avant la première authentification. L’interface utilisateur s’affiche uniquement s’il n’y a pas d’informations d’identification dans le gestionnaire d’informations d’identification. Sur tous les messages suivants de l’application, CREDUI_FLAGS_ALWAYS_SHOW_UI seront transmis, car les informations d’identification dans le gestionnaire d’informations d’identification ne sont manifestement pas valides pour cette ressource.
Informations sur la cible

Les informations cibles sont des informations sur l’emplacement de la ressource à accéder. Pour obtenir la liste de tous les noms cibles potentiels pour une ressource, appelez CredGetTargetInfo. CredGetTargetInfo retourne des informations qui ont été mises en cache par le package d’authentification Negotiate, NTLM ou Kerberos quand l’un de ces packages a été utilisé pour s’authentifier auprès de la cible nommée. CredGetTargetInfo retourne tout ou partie des noms suivants pour la cible :

  • Nom du serveur NetBIOS de l’ordinateur
  • Nom du serveur DNS de l’ordinateur
  • Nom de domaine NetBIOS du domaine auquel appartient l’ordinateur
  • Nom de domaine DNS du domaine auquel appartient l’ordinateur
  • Nom de l’arborescence DNS de l’arborescence à laquelle appartient l’ordinateur
  • Nom du package qui a collecté les informations
Toute partie de ces informations peut être manquante si les informations ne s’appliquent pas à l’ordinateur cible. Par instance, un ordinateur membre d’un groupe de travail n’a pas de nom de domaine NetBIOS.

Les informations d’identification sont stockées dans le gestionnaire d’informations d’identification en fonction du nom de la cible. Chaque nom cible est stocké aussi généralement que possible sans entrer en conflit avec les informations d’identification déjà stockées dans le gestionnaire d’informations d’identification. Étant donné que les informations d’identification sont stockées par nom de cible, un utilisateur particulier ne peut avoir qu’une seule information d’identification par cible stockée dans le gestionnaire d’informations d’identification.

Notes

L’en-tête wincred.h définit CredUIPromptForCredentials 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. La combinaison 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 wincred.h
Bibliothèque Credui.lib
DLL Credui.dll

Voir aussi

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection