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(분산 파일 시스템) 연결의 경우 이 문자열은 ServerNameShareName\ 형식입니다. 이 매개 변수는 자격 증명을 저장하고 검색할 때 대상 정보를 식별하는 데 사용됩니다.
[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로 끝나는 문자열에 대한 포인터입니다. pszPassword에 길이가 0이 아닌 문자열을 지정하면 대화 상자의 암호 옵션이 문자열로 미리 채워집니다.
이 함수는 사용자가 제공한 암호를 이 버퍼에 복사하여 최대 ulPasswordMaxChars 문자를 복사합니다. CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하지 않으면 이 매개 변수에서 반환되는 값은 WNetAddConnection 또는 SSP 함수와 같은 클라이언트 쪽 인증 함수에 전달하는 것 외에는 검사, 인쇄 또는 유지해서는 안 되는 폼입니다.
암호 사용을 마쳤으면 SecureZeroMemory 함수를 호출하여 메모리에서 암호를 지웁 수 있습니다. 암호 보호에 대한 자세한 내용은 암호 처리를 참조하세요.
[in] ulPasswordBufferSize
종료 null 문자를 포함하여 pszPassword 에 복사할 수 있는 최대 문자 수입니다.
[in, out] save
저장 검사 상자의 초기 상태를 지정하고 사용자가 대화 상자에 응답한 후 저장 검사 상자의 상태를 수신하는 BOOL에 대한 포인터입니다. 이 값이 NULL이 아니고 CredUIPromptForCredentials가 NO_ERROR 반환하는 경우 사용자가 대화 상자에서 확인을 선택하면 pfSave가 검사 저장 상자의 상태를 반환합니다.
CREDUI_FLAGS_PERSIST 플래그를 지정하면 저장 검사 상자가 표시되지 않지만 선택된 것으로 간주됩니다.
CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하고 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 지정하지 않으면 저장 검사 상자가 표시되지 않지만 지워진 것으로 간주됩니다.
자격 증명을 묻는 메시지를 사용자에게 표시하기 위해 CredUI를 사용해야 하지만 자격 증명 관리자가 제공하는 자격 증명 관리 서비스가 필요하지 않은 애플리케이션은 사용자가 대화 상자를 닫은 후 pfSave를 사용하여 저장 검사 상자의 상태를 받을 수 있습니다. 이렇게 하려면 호출자가 dwFlags에서 CREDUI_FLAGS_DO_NOT_PERSIST 및 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 지정해야 합니다. CREDUI_FLAGS_DO_NOT_PERSIST 및 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 설정되면 애플리케이션은 함수가 반환된 후 *pfSave 를 검사해야 하며, *pfSave 가 TRUE이면 애플리케이션이 애플리케이션의 리소스 내에서 사용자 자격 증명을 저장하기 위해 적절한 조치를 취해야 합니다.
[in] dwFlags
이 함수에 대한 특수 동작을 지정하는 DWORD 값입니다. 이 값은 다음 값 중 0개 이상의 비트 OR 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
자격 증명 관리자의 기존 자격 증명에서 자격 증명을 반환할 수 있더라도 사용자 인터페이스가 표시되도록 지정합니다. 이 플래그는 CREDUI_FLAGS_GENERIC_CREDENTIALS 지정한 경우에만 허용됩니다. |
|
사용자 이름에 대한 프롬프트로 콤보 상자를 채웁다. |
|
자격 증명을 저장하거나 검사 상자를 표시하지 마세요. 이 플래그를 사용하여 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 전달하여 저장 검사 상자만 표시할 수 있으며 결과는 pfSave 출력 매개 변수에 반환됩니다. |
|
사용자 이름/암호로만 콤보 상자를 채웁다. 콤보 상자에 인증서 또는 스마트 카드를 표시하지 마세요. |
|
반환된 자격 증명이 실제로 유효한지 여부를 확인한 후 호출자가 CredUIConfirmCredentials 를 호출하도록 지정합니다. 이 메커니즘은 유효하지 않은 자격 증명이 자격 증명 관리자에 저장되지 않도록 합니다. CREDUI_FLAGS_DO_NOT_PERSIST 지정하지 않는 한 모든 경우에 이 플래그를 지정합니다. |
|
사용자가 입력한 자격 증명을 일반 자격 증명으로 간주합니다. |
|
"로그온 실패" 풍선 팁을 표시하여 사용자에게 자격 증명이 충분하지 않음을 알립니다. |
|
사용자가 제공된 사용자 이름을 변경할 수 없도록 합니다. |
|
암호로만 콤보 상자를 채웁다. 사용자 이름을 입력할 수 없습니다. |
|
저장 검사 상자를 표시하지 마세요. 하지만 상자가 표시되고 선택된 것처럼 자격 증명이 저장됩니다. |
|
로컬 관리자로만 콤보 상자를 채웁니다. Windows XP Home Edition: 이 플래그는 잘 알려진 관리자 계정을 필터링합니다. |
|
인증서 및 스마트 카드로만 콤보 상자를 채웁니다. 사용자 이름을 입력할 수 없습니다. |
|
인증서 또는 스마트 카드로만 콤보 상자를 채웁니다. 사용자 이름을 입력할 수 없습니다. |
|
이 플래그는 인증이 실패할 경우 대화 상자를 미리 채우기 위해 일치하는 자격 증명을 찾는 경우에만 의미가 있습니다. 이 플래그를 지정하면 와일드카드 자격 증명이 일치하지 않습니다. 자격 증명을 작성할 때는 아무런 효과가 없습니다. CredUI는 와일드카드 문자를 포함하는 자격 증명을 만들지 않습니다. RAS 연결을 만들 때와 같이 발견된 모든 항목이 사용자가 명시적으로 만들거나 프로그래밍 방식으로 생성되었습니다. |
|
검사 상자를 선택한 경우 저장 검사 상자를 표시하고 pfSave 출력 매개 변수에 TRUE를 반환하고, 그렇지 않으면 FALSE를 반환합니다. 확인란은 기본적으로 pfSave 의 값을 사용합니다. |
|
자격 증명은 "runas" 자격 증명입니다. TargetName 매개 변수는 실행 중인 명령 또는 프로그램의 이름을 지정합니다. 메시지를 표시하는 용도로만 사용됩니다. |
|
사용자 이름이 유효한지 확인합니다. |
반환 값
반환 값은 DWORD 이며 다음 값 중 하나일 수 있습니다.
| 값 | Description |
|---|---|
|
사용자가 취소를 선택했습니다. pszUserName 및 pszPassword 매개 변수는 변경되지 않았습니다. |
|
이 상태 유효하지 않은 플래그 구성에 대해 반환됩니다. |
|
pszTargetName이 NULL이거나, 빈 문자열이거나, CREDUI_MAX_DOMAIN_LENGTH 이상이거나, pUiInfo가 NULL이 아니고 가리키는 CredUI_INFO 구조체가 다음 요구 사항 중 하나를 충족하지 못했습니다.
|
|
자격 증명 관리자를 사용할 수 없습니다. 일반적으로 이 오류는 CredUIPromptForCredentials 를 호출하고 CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 전달하여 처리됩니다. |
|
사용자가 확인을 선택했습니다. pszUserName, pszPassword 및 pfSave 매개 변수는 앞에서 설명한 값을 반환합니다. |
설명
CredUIPromptForCredentials 함수는 애플리케이션 모달 대화 상자를 만들고 표시합니다. 대화 상자가 표시되고 사용자 또는 애플리케이션이 대화 상자를 닫을 때까지 애플리케이션의 다른 창이 활성화될 수 없습니다.
플래그 CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE 및 CREDUI_FLAGS_EXCLUDE_CERTIFICATE 함께 사용할 수 없습니다.
CREDUI_FLAGS_DO_NOT_PERSIST 지정한 경우 pszTargetName을 지정하거나 uiInfo-pszMessageText> 및 uiInfo-pszCaption>을 지정해야 합니다.
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 지정한 경우 형식화된 이름은 구문이 선택됩니다. 구문 검사는 CredUIParseUserName에서 적용한 것과 동일한 규칙을 적용합니다. 형식화된 이름이 유효하지 않으면 사용자에게 유효한 이름을 입력하라는 메시지가 표시됩니다. 형식화된 이름의 도메인 부분이 누락된 경우 대상 이름에 따라 도메인 부분이 제공됩니다.
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 |