CredUIPromptForCredentialsA, fonction (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érente 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 null qui contient le nom de la cible pour les informations d’identification, généralement un nom de serveur. Pour les connexions DFS (Distributed File System), 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é à une utilisation ultérieure. 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 transmettre 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 code d’état expiré du mot de passe a expiré, 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 passée, 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 Nom d’utilisateur/mot de passe, 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 ulUserNameMaxChars caractères. Ce format peut être converti en format UserName/Password à l’aide de CredUIParseUsername. Un format marshalé peut être transmis directement à un fournisseur de support de sécurité (SSP).
Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’un formulaire qui ne doit pas être inspecté, imprimé ou conservé autre que de le 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. En sortie, ce paramètre reçoit une chaîne qui contient cette paire DomainName\UserName.
[in] ulUserNameBufferSize
Nombre maximal de caractères qui peuvent ê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 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 ulPasswordMaxChars caractères. Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’un formulaire qui ne doit pas être inspecté, imprimé ou conservé autre que de le 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 qui peuvent être copiés dans pszPassword y compris le caractère null de fin.
[in, out] save
Pointeur vers une BOOL qui spécifie l’état initial de la case Enregistrer et reçoit l’état de la case Enregistrer une fois que l’utilisateur a répondu à la boîte de dialogue. Si cette valeur n’est pas NULL et CredUIPromptForCredentials retourne NO_ERROR, pfSave retourne l’état de la case Enregistrer lorsque l’utilisateur a choisi OK dans la boîte de dialogue.
Si l’indicateur CREDUI_FLAGS_PERSIST est spécifié, la case Enregistrer 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 case Enregistrer 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 l'Enregistrer case à cocher une fois que l’utilisateur ferme 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 chargée d’examiner * pfSave une fois la fonction retournée, et si *pfSave est 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 deOU de zéro ou plusieurs 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 d’un nom d’utilisateur. |
|
Ne stockez pas les informations d’identification ni les cases à cocher d’affichage. Vous pouvez passer CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX avec cet indicateur pour afficher la case à cocher Enregistrer uniquement, et le résultat est retourné dans le paramètre de sortie pfSave. |
|
Remplissez la zone de liste déroulante 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 appelle CredUIConfirmCredentials après vérification pour déterminer 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 connexion ». |
|
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 l’entrée d’un nom d’utilisateur. |
|
N’affichez pas la case Enregistrer, mais les informations d’identification sont enregistrées comme si la case était affichée et cochée. |
|
Remplissez la zone de liste déroulante avec les administrateurs locaux uniquement.Windows XP Home Edition : Cet indicateur filtre le compte Administrateur connu. |
|
Remplissez la zone de liste déroulante avec des certificats et des cartes à puce uniquement. N’autorisez pas l’entrée d’un nom d’utilisateur. |
|
Remplissez la zone de liste déroulante avec des certificats ou des cartes à puce uniquement. N’autorisez pas l’entrée d’un nom d’utilisateur. |
|
Cet indicateur est significatif uniquement dans la localisation d’informations d’identification correspondantes pour préremplir la boîte de dialogue, si l’authentification échoue. Lorsque cet indicateur est spécifié, les informations d’identification génériques ne sont pas mises en correspondance. Il n’a aucun effet lors de l’écriture d’informations d’identification. CredUI ne crée pas d’informations d’identification qui contiennent des caractères génériques. Les éléments trouvés ont été créés explicitement par l’utilisateur ou créés par programme, comme cela se produit lorsqu’une connexion RAS est établie. |
|
Si la case à cocher est cochée, activez la case Enregistrer et renvoyez TRUE dans le paramètre de sortie pfSave, sinon, renvoyez FALSE. La case à cocher utilise la valeur de 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é uniquement à des fins d’invite. |
|
Vérifiez que le nom d’utilisateur est valide. |
Valeur de retour
La valeur de retour est une DWORD
| Valeur | Description |
|---|---|
|
L’utilisateur a choisi Annuler. Les paramètres pszUserName et pszPassword n’ont pas changé. |
|
Cet état est retourné pour l’une des configurations d’indicateur non valides. |
|
pszTargetName est NULL, la chaîne vide ou plus longue que CREDUI_MAX_DOMAIN_LENGTH, ou pUiInfo n’est pas 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 de CREDUI_FLAGS_DO_NOT_PERSIST. |
|
L’utilisateur a choisi OK. Les paramètres pszUserName, pszPasswordet paramètres 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 aucune des informations d’identification n’est spécifiée, les informations d’identification sont des informations d’identification de domaine.
Un certificat X509 doit avoir une valeur d’utilisation de clé améliorée
Windows XP : cette valeur de référence EKU n’est pas nécessaire pour afficher les certificats X509.
Si CREDUI_FLAGS_GENERIC_CREDENTIALS n’est pas spécifié ou CREDUI_FLAGS_COMPLETE_USERNAME est spécifié, le nom typé est syntaxe vérifiée. La vérification de la syntaxe applique les mêmes règles que celles appliquées par CredUIParseUserName. Si le nom typé n’est pas valide, l’utilisateur est invité à en entrer un valide. Si la partie domaine du nom typé est manquante, un domaine est fourni en fonction du nom cible.
Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que CREDUI_FLAGS_VALIDATE_USERNAME est également spécifié, le nom typé est vérifié. Si le nom typé n’est pas valide, l’utilisateur est invité à en entrer un valide.
Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME n’est spécifié, le nom typé n’est pas vérifié de manière quelconque.
Si aucune CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST n’est définie, la case à cocher Enregistrer
Modes d’appel
- L’appelant tente d’accéder à la ressource cible, appelle credui (en passant une description de la ressource cible et l’état d’échec), appelez CredUIParseUserName, accédez à nouveau à la ressource cible, puis appelez CredUIConfirmCredentials.
- L’appelant peut demander des informations d’identification sans accéder à des 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. Demander des 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 est transmis, car les informations d’identification dans le gestionnaire d’informations d’identification ne sont 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 d’une ressource, appelez CredGetTargetInfo. CredGetTargetInfo retourne des informations mises en cache par le package d’authentification Negotiate, NTLM ou Kerberos lorsqu’un de ces packages a été utilisé pour s’authentifier auprès de la cible nommée. CredGetTargetInfo retourne certains noms ou tous les 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 cible. Chaque nom cible est stocké le plus généralement possible sans entrer en collision 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 cible, un utilisateur particulier ne peut avoir qu’une seule information d’identification par cible stockée dans le gestionnaire d’informations d’identification.
Note
L’en-tête wincred.h définit CredUIPromptForCredentials comme 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 | wincred.h |
| bibliothèque | Credui.lib |
| DLL | Credui.dll |