Función CredUIPromptForCredentialsW (wincred.h)
La función CredUIPromptForCredentials crea y muestra un cuadro de diálogo configurable que acepta información de credenciales de un usuario.
Las aplicaciones destinadas a Windows Vista o Windows Server 2008 deben llamar a CredUIPromptForWindowsCredentials en lugar de a esta función, por los siguientes motivos:
- CredUIPromptForWindowsCredentials es coherente con la interfaz de usuario actual de Windows.
- CredUIPromptForWindowsCredentials es más extensible, lo que permite la integración de mecanismos de autenticación adicionales, como biometría y tarjetas inteligentes.
- CredUIPromptForWindowsCredentials es compatible con la especificación Common Criteria.
Sintaxis
CREDUIAPI DWORD CredUIPromptForCredentialsW(
[in, optional] PCREDUI_INFOW pUiInfo,
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PWSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
Parámetros
[in, optional] pUiInfo
Puntero a una estructura de CREDUI_INFO que contiene información para personalizar la apariencia del cuadro de diálogo.
[in] pszTargetName
Puntero a una cadena terminada en null que contiene el nombre del destino para las credenciales, normalmente un nombre de servidor. Para las conexiones del Sistema de archivos distribuido (DFS), esta cadena tiene el formato NombreServidor ShareName\. Este parámetro se usa para identificar la información de destino al almacenar y recuperar credenciales.
[in] pContext
Este parámetro se reserva para uso futuro. Debe ser NULL.
[in, optional] dwAuthError
Especifica por qué se necesita el cuadro de diálogo de credenciales. Un llamador puede pasar este parámetro de error de Windows, devuelto por otra llamada de autenticación, para permitir que el cuadro de diálogo admita determinados errores. Por ejemplo, si se pasa el código de estado expirado de la contraseña, el cuadro de diálogo podría pedir al usuario que cambie la contraseña de la cuenta.
[in, out] pszUserName
Puntero a una cadena terminada en null que contiene el nombre de usuario de las credenciales. Si se pasa una cadena de longitud distinta de cero, la opción UserName del cuadro de diálogo se rellena previamente con la cadena. En el caso de las credenciales que no sean UserName/Password, se puede pasar un formato serializado de la credencial. Esta cadena se crea llamando a CredMarshalCredential.
Esta función copia el nombre proporcionado por el usuario en este búfer y copia un máximo de caracteres ulUserNameMaxChars . Este formato se puede convertir al formatode contraseñausername/ mediante CredUIParseUsername. Un formato serializado se puede pasar directamente a un proveedor de soporte técnico de seguridad (SSP).
Si no se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no debe inspeccionarse, imprimirse o conservarse excepto pasarlo a CredUIParseUsername. Los resultados posteriores de CredUIParseUsername solo se pueden pasar a una función de autenticación del lado cliente, como WNetAddConnection o una función SSP.
Si no se especifica ningún dominio o servidor como parte de este parámetro, el valor del parámetro pszTargetName se usa como dominio para formar un par NombreDeUsuario DeDominio\. En la salida, este parámetro recibe una cadena que contiene ese par NombreDeDominio\UserName .
[in] ulUserNameBufferSize
Número máximo de caracteres que se pueden copiar en pszUserName , incluido el carácter nulo de terminación.
[in, out] pszPassword
Puntero a una cadena terminada en null que contiene la contraseña de las credenciales. Si se especifica una cadena de longitud distinta de cero para pszPassword, la opción de contraseña del cuadro de diálogo se rellenará previamente con la cadena.
Esta función copia la contraseña proporcionada por el usuario en este búfer y copia un máximo de caracteres ulPasswordMaxChars . Si no se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no debe inspeccionarse, imprimirse o conservarse aparte de pasarlo a una función de autenticación del lado cliente, como WNetAddConnection o una función SSP.
Cuando haya terminado de usar la contraseña, borre la contraseña de la memoria mediante una llamada a la función SecureZeroMemory . Para obtener más información sobre la protección de contraseñas, consulte Control de contraseñas.
[in] ulPasswordBufferSize
Número máximo de caracteres que se pueden copiar en pszPassword , incluido el carácter nulo de terminación.
[in, out] save
Puntero a una BOOL que especifica el estado inicial de la casilla Guardar y recibe el estado de la casilla Guardar después de que el usuario haya respondido al cuadro de diálogo. Si este valor no es NULL y CredUIPromptForCredentials devuelve NO_ERROR, pfSave devuelve el estado de la casilla Guardar cuando el usuario eligió Aceptar en el cuadro de diálogo.
Si se especifica la marca CREDUI_FLAGS_PERSIST, no se muestra la casilla Guardar , pero se considera seleccionada.
Si se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST y no se especifica CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, no se muestra la casilla Guardar , pero se considera desactivada.
Una aplicación que necesita usar CredUI para solicitar al usuario las credenciales, pero no necesita los servicios de administración de credenciales proporcionados por el administrador de credenciales, puede usar pfSave para recibir el estado de la casilla Guardar después de que el usuario cierre el cuadro de diálogo. Para ello, el autor de la llamada debe especificar CREDUI_FLAGS_DO_NOT_PERSIST y CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX en dwFlags. Cuando se establecen CREDUI_FLAGS_DO_NOT_PERSIST y CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, la aplicación es responsable de examinar *pfSave después de que se devuelva la función y, si *pfSave es TRUE, la aplicación debe realizar la acción adecuada para guardar las credenciales de usuario dentro de los recursos de la aplicación.
[in] dwFlags
Valor DWORD que especifica un comportamiento especial para esta función. Este valor puede ser una combinación or bit a bit de cero o más de los valores siguientes.
| Valor | Significado |
|---|---|
|
Especifica que se mostrará una interfaz de usuario incluso si las credenciales se pueden devolver desde una credencial existente en el administrador de credenciales. Esta marca solo se permite si también se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS. |
|
Rellene el cuadro combinado con el mensaje de un nombre de usuario. |
|
No almacene credenciales ni muestre casillas. Puede pasar CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX con esta marca para mostrar solo la casilla Guardar y el resultado se devuelve en el parámetro de salida pfSave . |
|
Rellene el cuadro combinado solo con nombre de usuario o contraseña. No muestre certificados ni tarjetas inteligentes en el cuadro combinado. |
|
Especifica que el autor de la llamada llamará a CredUIConfirmCredentials después de comprobar si las credenciales devueltas son realmente válidas. Este mecanismo garantiza que las credenciales que no son válidas no se guarden en el administrador de credenciales. Especifique esta marca en todos los casos a menos que se especifique CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Tenga en cuenta las credenciales escritas por el usuario para que sean credenciales genéricas. |
|
Notifique al usuario las credenciales insuficientes mostrando la sugerencia de globo "Inicio de sesión incorrecto". |
|
No permita que el usuario cambie el nombre de usuario proporcionado. |
|
Rellene el cuadro combinado solo con la contraseña. No permita escribir un nombre de usuario. |
|
No muestre la casilla Guardar , pero la credencial se guarda como si se mostrara y seleccionara la casilla. |
|
Rellene el cuadro combinado solo con administradores locales. Windows XP Home Edition: Esta marca filtrará la cuenta de administrador conocida. |
|
Rellene el cuadro combinado solo con certificados y tarjetas inteligentes. No permita escribir un nombre de usuario. |
|
Rellene el cuadro combinado solo con certificados o tarjetas inteligentes. No permita escribir un nombre de usuario. |
|
Esta marca solo es significativa para buscar una credencial coincidente para rellenar previamente el cuadro de diálogo, si se produce un error de autenticación. Cuando se especifica esta marca, no se coincidirán las credenciales con caracteres comodín. No tiene ningún efecto al escribir una credencial. CredUI no crea credenciales que contienen caracteres comodín. Cualquier encontrado fue creado explícitamente por el usuario o creado mediante programación, como sucede cuando se realiza una conexión RAS. |
|
Si la casilla está activada, muestre la casilla Guardar y devuelva TRUE en el parámetro de salida pfSave ; de lo contrario, devuelva FALSE. La casilla usa el valor de pfSave de forma predeterminada. |
|
La credencial es una credencial "runas". El parámetro TargetName especifica el nombre del comando o programa que se está ejecutando. Solo se usa para solicitar propósitos. |
|
Compruebe que el nombre de usuario es válido. |
Valor devuelto
El valor devuelto es un DWORD y puede ser uno de los siguientes valores.
| Valor | Descripción |
|---|---|
|
El usuario eligió Cancelar. Los parámetros pszUserName y pszPassword no han cambiado. |
|
Este estado se devuelve para cualquiera de las configuraciones de marca que no son válidas. |
|
PszTargetName es NULL, la cadena vacía o más larga que CREDUI_MAX_DOMAIN_LENGTH, o pUiInfo no es NULL y la estructura de CredUI_INFO apuntada no cumple uno de los siguientes requisitos:
|
|
No se puede usar el administrador de credenciales. Normalmente, este error se controla llamando a CredUIPromptForCredentials y pasando la marca de CREDUI_FLAGS_DO_NOT_PERSIST. |
|
El usuario eligió Aceptar. Los parámetros pszUserName, pszPassword y pfSave devolverán los valores documentados anteriormente. |
Comentarios
La función CredUIPromptForCredentials crea y muestra un cuadro de diálogo modal de aplicación. Una vez que se muestra el cuadro de diálogo y hasta que el usuario o la aplicación lo cierran, no se puede activar ninguna otra ventana de la aplicación.
Las marcas CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE y CREDUI_FLAGS_EXCLUDE_CERTIFICATE son mutuamente excluyentes.
Si se especifica CREDUI_FLAGS_DO_NOT_PERSIST, debe especificarse pszTargetName o se debe especificar uiInfo-pszMessageText> y uiInfo-pszCaption>.
Las marcas CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS y CREDUI_FLAGS_GENERIC_CREDENTIALS son mutuamente excluyentes. Si no se especifica ninguno, la credencial es una credencial de dominio.
Un certificado X509 debe tener un valor de uso mejorado de clave (EKU) de szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) que se mostrará.
Windows XP: Este valor de EKU no es necesario para mostrar certificados X509.
Si no se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS o se especifica CREDUI_FLAGS_COMPLETE_USERNAME, se comprueba la sintaxis del nombre con tipo. La comprobación de sintaxis aplica las mismas reglas que aplica CredUIParseUserName. Si el nombre con tipo no es válido, se le pedirá al usuario uno válido. Si falta la parte de dominio del nombre con tipo, se proporcionará una en función del nombre de destino.
Si se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS y también se especifica CREDUI_FLAGS_VALIDATE_USERNAME, se comprueba la sintaxis del nombre con tipo. Si el nombre con tipo no es válido, se le pedirá al usuario uno válido.
Si se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS y no se especifica ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME, el nombre con tipo no se comprueba de ninguna manera.
Si no se establece ni CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST, se muestra la casilla Guardar y controla si se guarda la credencial.
Modos de llamada
- El autor de la llamada intentará acceder al recurso de destino, llamará a credui (pasando una descripción del recurso de destino y el estado de error), llame a CredUIParseUserName, vuelva a acceder al recurso de destino y, a continuación, llame a CredUIConfirmCredentials.
- El autor de la llamada puede solicitar credenciales sin tener acceso a ningún recurso pasando CREDUI_FLAGS_DO_NOT_PERSIST.
- Para las credenciales genéricas, no hay ningún paquete de autenticación. Por lo tanto, la aplicación debe tener acceso a la credencial para realizar la autenticación. Solicitar credenciales, no pasar CREDUI_FLAGS_ALWAYS_SHOW_UI antes de la primera autenticación. La interfaz de usuario solo aparecerá si no hay ninguna credencial en el administrador de credenciales. En todos los mensajes posteriores desde dentro de la aplicación, se pasará CREDUI_FLAGS_ALWAYS_SHOW_UI porque la credencial del administrador de credenciales no es claramente válida para ese recurso.
La información de destino es información sobre la ubicación del recurso al que se va a acceder. Para obtener una lista de todos los nombres de destino potenciales de un recurso, llame a CredGetTargetInfo. CredGetTargetInfo devuelve información almacenada en caché por el paquete de autenticación Negotiate, NTLM o Kerberos cuando se usó uno de esos paquetes para autenticarse en el destino con nombre. CredGetTargetInfo devuelve algunos o todos los nombres siguientes para el destino:
- Nombre del servidor NetBIOS del equipo
- Nombre del servidor DNS del equipo
- Nombre de dominio netBIOS del dominio al que pertenece el equipo
- Nombre de dominio DNS del dominio al que pertenece el equipo
- Nombre del árbol DNS del árbol al que pertenece el equipo
- Nombre del paquete que recopiló la información
Las credenciales se almacenan en el administrador de credenciales en función del nombre de destino. Cada nombre de destino se almacena lo más generalmente posible sin colisionar con las credenciales ya almacenadas en el administrador de credenciales. Dado que las credenciales se almacenan por nombre de destino, un usuario determinado solo puede tener una credencial por destino almacenada en el administrador de credenciales.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wincred.h |
| Library | Credui.lib |
| Archivo DLL | Credui.dll |