CredUIPromptForCredentialsA 함수(wincred.h)
CredUIPromptForCredentials 함수는 사용자의 자격 증명 정보를 허용하는 구성 가능한 대화 상자를 만들고 표시합니다.
Windows Vista 또는 Windows Server 2008을 대상으로 하는 애플리케이션은 다음과 같은 이유로 이 함수 대신 CredUIPromptForWindowsCredentials 호출해야 합니다.
- CredUIPromptForWindowsCredentials 현재 Windows 사용자 인터페이스와 일치합니다.
- CredUIPromptForWindowsCredentials 확장 가능하므로 생체 인식 및 스마트 카드와 같은 추가 인증 메커니즘을 통합할 수 있습니다.
- CredUIPromptForWindowsCredentials 공통 조건 사양을 준수합니다.
통사론
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
);
매개 변수
[in, optional] pUiInfo
대화 상자의 모양을 사용자 지정하기 위한 정보가 포함된 CREDUI_INFO 구조체에 대한 포인터입니다.
[in] pszTargetName
자격 증명의 대상 이름(일반적으로 서버 이름)을 포함하는 null로 끝나는 문자열에 대한 포인터입니다. DFS(분산 파일 시스템) 연결의 경우 이 문자열은 ServerName
[in] pContext
이 매개 변수는 나중에 사용하도록 예약되어 있습니다. NULL
[in, optional] dwAuthError
자격 증명 대화 상자가 필요한 이유를 지정합니다. 호출자는 다른 인증 호출에서 반환된 이 Windows 오류 매개 변수를 전달하여 대화 상자가 특정 오류를 수용할 수 있도록 할 수 있습니다. 예를 들어 암호 만료 상태 코드가 전달되면 대화 상자에서 사용자에게 계정의 암호를 변경하라는 메시지를 표시할 수 있습니다.
[in, out] pszUserName
자격 증명의 사용자 이름을 포함하는 null로 끝나는 문자열에 대한 포인터입니다. 길이가 0이 아닌 문자열이 전달되면 대화 상자의 UserName 옵션이 문자열로 미리 채워집니다. UserName/암호이외의 자격 증명의 경우 자격 증명의 마샬링된 형식을 전달할 수 있습니다. 이 문자열은 CredMarshalCredential호출하여 생성됩니다.
이 함수는 사용자가 제공한 이름을 이 버퍼에 복사하여 최대 ulUserNameMaxChars 문자를 복사합니다. 이 형식은 CredUIParseUsername사용하여 UserName/암호 형식으로 변환할 수 있습니다. 마샬링된 형식은 SSP(보안 지원 공급자)에 직접 전달될 수 있습니다.
CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하지 않으면 이 매개 변수에서 반환되는 값은 CredUIParseUsername전달하지 않고 검사, 인쇄 또는 유지해서는 안 되는 폼입니다. CredUIParseUsername 후속 결과는 WNetAddConnection 또는 SSP 함수와 같은 클라이언트 쪽 인증 함수에만 전달될 수 있습니다.
이 매개 변수의 일부로 도메인 또는 서버를 지정하지 않으면 pszTargetName 매개 변수의 값이 도메인으로 사용되어 DomainName\UserName 쌍을 형성합니다. 출력에서 이 매개 변수는 DomainName\UserName 쌍을 포함하는 문자열을 받습니다.
[in] ulUserNameBufferSize
종료 null 문자를 포함하여 pszUserName 복사할 수 있는 최대 문자 수입니다.
[in, out] pszPassword
자격 증명의 암호를 포함하는 null로 끝나는 문자열에 대한 포인터입니다. 0이 아닌 문자열이 pszPassword지정되면 대화 상자의 암호 옵션이 문자열로 미리 채워집니다.
이 함수는 사용자가 제공한 암호를 이 버퍼에 복사하여 최대 ulPasswordMaxChars 문자를 복사합니다. CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하지 않으면 이 매개 변수에서 반환되는 값은 WNetAddConnection 또는 SSP 함수와 같은 클라이언트 쪽 인증 함수에 전달하는 것 외에는 검사, 인쇄 또는 유지해서는 안 되는 폼입니다.
암호 사용을 마쳤으면 SecureZeroMemory 함수를 호출하여 메모리에서 암호를 지웁 수 있습니다. 암호 보호에 대한 자세한 내용은 암호 처리참조하세요.
[in] ulPasswordBufferSize
종료 null 문자를 포함하여 pszPassword 복사할 수 있는 최대 문자 수입니다.
[in, out] save
저장 확인란의 초기 상태를 지정하고 사용자가 대화 상자에 응답한 후 저장 확인란의 상태를 받는 BOOL 대한 포인터입니다. 이 값이 NULL
CREDUI_FLAGS_PERSIST 플래그를 지정하면 저장 확인란이 표시되지 않지만 선택된 것으로 간주됩니다.
CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하고 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 지정하지 않으면 저장 확인란이 표시되지 않지만 지워진 것으로 간주됩니다.
자격 증명을 사용자에게 요청하기 위해 CredUI를 사용해야 하지만 자격 증명 관리자에서 제공하는 자격 증명 관리 서비스가 필요하지 않은 애플리케이션은 사용자가 대화 상자를 닫은 후 pfSave 사용하여 저장 확인란의 상태를 받을 수 있습니다. 이렇게 하려면 호출자는 dwFlagsCREDUI_FLAGS_DO_NOT_PERSIST 및 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 지정해야 합니다. CREDUI_FLAGS_DO_NOT_PERSIST 및 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 설정되면 애플리케이션은 함수가 반환된 후 *
[in] dwFlags
이 함수에 대한 특수 동작을 지정하는 DWORD 값입니다. 이 값은 다음 값 중 0개 이상의 비트또는 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
자격 증명 관리자의 기존 자격 증명에서 자격 증명을 반환할 수 있더라도 사용자 인터페이스가 표시되도록 지정합니다. 이 플래그는 CREDUI_FLAGS_GENERIC_CREDENTIALS 지정한 경우에만 허용됩니다. |
|
사용자 이름에 대한 프롬프트로 콤보 상자를 채웁다. |
|
자격 증명을 저장하거나 확인란을 표시하지 마세요. 이 플래그를 사용하여 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 전달하여 저장 확인란만 표시할 수 있으며 결과는 pfSave 출력 매개 변수에 반환됩니다. |
|
사용자 이름/암호로만 콤보 상자를 채웁다. 콤보 상자에 인증서 또는 스마트 카드를 표시하지 마세요. |
|
반환된 자격 증명이 실제로 유효한지 여부를 확인한 후 호출자가 CredUIConfirmCredentials 호출하도록 지정합니다. 이 메커니즘은 유효하지 않은 자격 증명이 자격 증명 관리자에 저장되지 않도록 합니다. CREDUI_FLAGS_DO_NOT_PERSIST 지정하지 않는 한 모든 경우에 이 플래그를 지정합니다. |
|
사용자가 입력한 자격 증명을 일반 자격 증명으로 간주합니다. |
|
"로그온 실패" 풍선 팁을 표시하여 사용자에게 자격 증명이 부족하다고 알립니다. |
|
사용자가 제공된 사용자 이름을 변경할 수 없습니다. |
|
암호로만 콤보 상자를 채웁다. 사용자 이름을 입력할 수 없습니다. |
|
저장 확인란을 표시하지 마세요. 하지만 상자가 표시되고 선택된 것처럼 자격 증명이 저장됩니다. |
|
로컬 관리자만 콤보 상자를 채웁니다.Windows XP Home Edition: 이 플래그는 잘 알려진 관리자 계정을 필터링합니다. |
|
인증서 및 스마트 카드로만 콤보 상자를 채웁니다. 사용자 이름을 입력할 수 없습니다. |
|
인증서 또는 스마트 카드로만 콤보 상자를 채웁니다. 사용자 이름을 입력할 수 없습니다. |
|
이 플래그는 인증이 실패할 경우 대화 상자를 미리 채우기 위해 일치하는 자격 증명을 찾는 경우에만 의미가 있습니다. 이 플래그를 지정하면 와일드카드 자격 증명이 일치하지 않습니다. 자격 증명을 작성할 때는 효과가 없습니다. CredUI는 와일드카드 문자를 포함하는 자격 증명을 만들지 않습니다. RAS 연결을 만들 때와 같이 사용자가 명시적으로 만들거나 프로그래밍 방식으로 생성된 모든 항목이 있습니다. |
|
확인란을 선택한 경우 |
|
자격 증명은 "runas" 자격 증명입니다. TargetName 매개 변수는 실행 중인 명령 또는 프로그램의 이름을 지정합니다. 프롬프트 용도로만 사용됩니다. |
|
사용자 이름이 유효한지 확인합니다. |
반환 값
반환 값은 DWORD 다음 값 중 하나일 수 있습니다.
| 값 | 묘사 |
|---|---|
|
사용자가 취소를 선택했습니다. pszUserName 및 pszPassword 매개 변수는 변경되지 않았습니다. |
|
이 상태는 유효하지 않은 플래그 구성에 대해 반환됩니다. |
|
pszTargetName
|
|
자격 증명 관리자를 사용할 수 없습니다. 일반적으로 이 오류는 CredUIPromptForCredentials 호출하고 CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 전달하여 처리됩니다. |
|
사용자가 확인 |
발언
CredUIPromptForCredentials 함수는 애플리케이션 모달 대화 상자를 만들고 표시합니다. 대화 상자가 표시되고 사용자 또는 애플리케이션이 대화 상자를 닫을 때까지 애플리케이션의 다른 창이 활성화될 수 없습니다.
플래그 CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE 및 CREDUI_FLAGS_EXCLUDE_CERTIFICATE 함께 사용할 수 없습니다.
CREDUI_FLAGS_DO_NOT_PERSIST 지정한 경우
CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS 플래그와 CREDUI_FLAGS_GENERIC_CREDENTIALS 함께 사용할 수 없습니다. 둘 다 지정되지 않은 경우 자격 증명은 도메인 자격 증명입니다.
X509 인증서에는 표시할 szOID_KP_SMARTCARD_LOGON(1.3.6.1.4.1.311.20.2.2)의 향상된 EKU(키 사용량) 값이 있어야 합니다.
Windows XP: 이 EKU 값은 X509 인증서를 표시할 필요가 없습니다.
CREDUI_FLAGS_GENERIC_CREDENTIALS 지정되지 않았거나 CREDUI_FLAGS_COMPLETE_USERNAME 지정한 경우 형식화된 이름은
CREDUI_FLAGS_GENERIC_CREDENTIALS 지정되고 CREDUI_FLAGS_VALIDATE_USERNAME 지정한 경우 형식화된 이름은 구문이 선택됩니다. 형식화된 이름이 유효하지 않으면 사용자에게 유효한 이름을 입력하라는 메시지가 표시됩니다.
CREDUI_FLAGS_GENERIC_CREDENTIALS 지정되고 CREDUI_FLAGS_COMPLETE_USERNAME 또는 CREDUI_FLAGS_VALIDATE_USERNAME 지정되지 않은 경우 형식화된 이름은 어떤 방식으로든 검사되지 않습니다.
CREDUI_FLAGS_PERSIST CREDUI_FLAGS_DO_NOT_PERSIST 설정되지 않은 경우 저장 확인란이 표시되고 자격 증명이 저장되는지 여부를 제어합니다.
호출 모드
- 호출자는 대상 리소스에 액세스하고, credui를 호출하고(대상 리소스 및 실패 상태에 대한 설명을 전달), CredUIParseUserName호출하고, 대상 리소스에 다시 액세스한 다음, CredUIConfirmCredentials호출합니다.
- 호출자는 CREDUI_FLAGS_DO_NOT_PERSIST 전달하여 리소스에 액세스하지 않고 자격 증명을 요청할 수 있습니다.
- 일반 자격 증명의 경우 인증 패키지가 없습니다. 따라서 애플리케이션은 인증을 수행하려면 자격 증명에 액세스해야 합니다. 첫 번째 인증 전에 CREDUI_FLAGS_ALWAYS_SHOW_UI 전달하지 않고 자격 증명을 묻는 메시지를 표시합니다. 사용자 인터페이스는 자격 증명 관리자에 자격 증명이 없는 경우에만 표시됩니다. 애플리케이션 내의 모든 후속 메시지에서 자격 증명 관리자의 자격 증명이 해당 리소스에 대해 명확하게 유효하지 않으므로 CREDUI_FLAGS_ALWAYS_SHOW_UI 전달됩니다.
대상 정보는 액세스할 리소스의 위치에 대한 정보입니다. 리소스에 대한 모든 잠재적 대상 이름 목록은 CredGetTargetInfo호출합니다. CredGetTargetInfo 패키지 중 하나를 사용하여 명명된 대상에 인증할 때 Negotiate, NTLM 또는 Kerberos 인증 패키지에 의해 캐시된 정보를 반환합니다. CredGetTargetInfo 대상에 대해 다음 이름 중 일부 또는 전부를 반환합니다.
- 컴퓨터의 NetBIOS 서버 이름
- 컴퓨터의 DNS 서버 이름
- 컴퓨터가 속한 도메인의 NetBIOS 도메인 이름
- 컴퓨터가 속한 도메인의 DNS 도메인 이름
- 컴퓨터가 속한 트리의 DNS 트리 이름
- 정보를 수집한 패키지의 이름
자격 증명은 대상 이름에 따라 자격 증명 관리자에 저장됩니다. 각 대상 이름은 자격 증명 관리자에 이미 저장된 자격 증명과 충돌하지 않고 가능한 한 일반적으로 저장됩니다. 자격 증명은 대상 이름으로 저장되므로 특정 사용자는 자격 증명 관리자에 저장된 대상당 하나의 자격 증명만 가질 수 있습니다.
메모
wincred.h 헤더는 CRedUIPromptForCredentials를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincred.h |
| 라이브러리 | Credui.lib |
| DLL | Credui.dll |
참고 항목
credGetTargetInfo
credUIConfirmCredentials
credUIParseUserName
credUIPromptForWindowsCredentials
WNetAddConnection