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 :
- CredUIPromptForWindowsCredentials est cohérent avec l’interface utilisateur Windows actuelle.
- CredUIPromptForWindowsCredentials est plus extensible, ce qui permet l’intégration de mécanismes d’authentification supplémentaires tels que la biométrie et les cartes à puce.
- CredUIPromptForWindowsCredentials est conforme à la spécification Common Criteria.
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.
[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.
[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 |
|---|---|
|
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é. |
|
Remplissez la zone de liste déroulante avec l’invite de nom d’utilisateur. |
|
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. |
|
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. |
|
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é. |
|
Considérez les informations d’identification entrées par l’utilisateur comme des informations d’identification génériques. |
|
Informez l’utilisateur des informations d’identification insuffisantes en affichant l’info-bulle « Échec de l’ouverture de session ». |
|
N’autorisez pas l’utilisateur à modifier le nom d’utilisateur fourni. |
|
Remplissez la zone de liste déroulante avec le mot de passe uniquement. N’autorisez pas la saisie d’un nom d’utilisateur. |
|
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. |
|
Remplissez la zone de liste modifiable avec les administrateurs locaux uniquement. Windows XP Édition Familiale : Cet indicateur filtre le compte Administrateur connu. |
|
Remplissez la zone de liste modifiable avec des certificats et des cartes à puce uniquement. N’autorisez pas la saisie d’un nom d’utilisateur. |
|
Remplissez la zone de liste modifiable avec des certificats ou des cartes à puce uniquement. N’autorisez pas la saisie d’un nom d’utilisateur. |
|
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. |
|
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. |
|
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. |
|
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 |
|---|---|
|
L’utilisateur a choisi Annuler. Les paramètres pszUserName et pszPassword n’ont pas changé. |
|
Cette status est retournée pour toutes les configurations d’indicateur qui ne sont pas valides. |
|
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 :
|
|
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. |
|
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.
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
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 |