CredUIPromptForWindowsCredentials Win32 API 사용법 정리

인증 정보를 받기 위한 대화창으로 (비스타 이상에서만 제공되는) CredUIPromptForWindowsCredentials Win32 API를 사용할 수 있습니다.

CredUIPromptForWindowsCredentials function
; https://docs.microsoft.com/en-us/windows/win32/api/wincred/nf-wincred-creduipromptforwindowscredentialsa

간단한 대화창이지만, 이것을 사용해서 좋은 이유는 운영체제에 등록된 각종 Credential Provider를 감안한 인증창을 띄워주기 때문에 윈도우 통합 인증을 구현하는 시나리오에서 충분한 장점이 있습니다. 비스타/2008 운영체제부터 기존의 MS GINA(Graphical Identification and Authentication)를 대체한 새로운 Credential Provider 인증 모델을 제공하는데요.

Windows Vista용 자격 증명 공급자로 사용자 지정 로그인 환경 만들기
; https://docs.microsoft.com/ko-kr/archive/msdn-magazine/2007/january/custom-login-experiences-credential-providers-in-windows-vista

CredUIPromptForWindowsCredentials API가 Credential Provider를 활성화하기 때문에 사용자 정의 Credential Provider 인증 모듈을 개발할 때 디버깅을 쉽게 할 수 있는 용도로도 사용됩니다.

API 사용 코드는 꽤나 전형적입니다.

BOOL save = false;
DWORD authPackage = 0;
LPVOID authBuffer;
ULONG authBufferSize = 0;
CREDUI_INFO credUiInfo;
DWORD dwFlags = 0;

credUiInfo.pszCaptionText = L"My caption";
credUiInfo.pszMessageText = L"My message";
credUiInfo.cbSize = sizeof(credUiInfo);
credUiInfo.hbmBanner = NULL;
credUiInfo.hwndParent = NULL;

DWORD dwResult = CredUIPromptForWindowsCredentials(&(credUiInfo), 0, &(authPackage),
    NULL, 0, &authBuffer, &authBufferSize, &(save), dwFlags);

if (dwResult == ERROR_SUCCESS)
{
    ::OutputDebugString(L"ERROR_SUCCESS");

    // 사용 후, 보안을 위해 인증 정보를 담은 영역을 '\0'로 지워준다.
    SecureZeroMemory(authBuffer, authBufferSize);
    CoTaskMemFree(authBuffer);
}
else if (dwResult == ERROR_CANCELLED)
{
    ::OutputDebugString(L"ERROR_CANCELLED");
}
else
{
    ::OutputDebugString(L"ERROR");
}

위의 코드를 실행하면 다음과 같은 대화창이 뜹니다.



아무 텍스트나 입력 후 "OK" 버튼을 누르면 ERROR_SUCCESS, "Cancel" 버튼을 누르면 ERROR_CANCELLED가 반환됩니다. (구체적으로 ERROR를 반환하는 시나리오는 잘 모르겠습니다.)

'아무 텍스트'나 입력하는 것이기 때문에, CredUIPromptForWindowsCredentials 함수는 사용자가 입력한 정보가 실제 인증된 계정인지에 대한 여부까지는 확인하지 않습니다. 말 그대로 사용자가 입력한 계정 정보만을 인자로 넘겨줬던 authBuffer 포인터와 authBufferSize로 알려줍니다. 실제로 반환 시점에 디버깅을 통해 authBuffer 포인터를 확인하면 이렇습니다.



위의 화면에서는 사용자가 계정 정보에 "test", 암호에 "qwer"을 입력했을 때의 반환값을 보여주고 있습니다. 바이너리 구조체이고, 그 내부에 사용자가 입력한 계정(THEMYTH8\test)과 암호(위의 그림에서 test 문자열 이후로 있는 정보)가 들어있습니다. 다행히, 이 정보를 해석하는 CredUnPackAuthenticationBuffer API가 있습니다. 따라서 dwResult == ERROR_SUCCESS인 경우 아래의 코드와 같은 식으로 사용자가 입력한 계정 정보를 구할 수 있습니다.

wchar_t userBuffer[1024];
wchar_t domainBuffer[1024];
wchar_t passwordBuffer[1024];

ULONG userBufferSize = 1024;
ULONG domainBufferSize = 1024;
ULONG passwordBufferSize = 1024;

BOOL success = CredUnPackAuthenticationBuffer(CRED_PACK_PROTECTED_CREDENTIALS,
    authBuffer, authBufferSize,
    userBuffer, &userBufferSize,
    domainBuffer, &domainBufferSize,
    passwordBuffer, &passwordBufferSize);
if (success == TRUE)
{
    // userBuffer == THEMYTH8\\test (여기서, THEMYTH8은 컴퓨터 명)
    // domainBuffer == (변화없음, Active Directory에 참여한 PC에만 유효한 값을 반환)
    // passwordBuffer == qwer
}

따라서, 사용자가 입력한 정보 중 암호는 '암호화된 상태'로 전달받고 필요한 경우 CredUnPackAuthenticationBuffer를 평문으로 복원해 사용할 수 있습니다.

참고로, C#(.NET)에서 사용하고 싶다면 다음의 유틸리티 클래스들을 이용하시면 좋습니다. ^^

Windows Common Credential UI Helper for .NET Framework
; https://gist.github.com/mayuki/339952

CredUIPromptForWindowsCredentials return junk characters if you P/Invoke it from managed code on OS’s such as Spanish or French.
; http://blogs.msdn.com/b/dsnotes/archive/2012/02/21/creduipromptforwindowscredentials-return-junk-characters-if-you-p-invoke-it-from-managed-code-on-os-s-such-as-spanish-or-french.aspx

---

CredUIPromptForWindowsCredentials API에 전달하는 옵션 중 마지막 인자인 "DWORD dwFlags"에 대해 알아보겠습니다.



이 값으로 CREDUIWIN_CHECKBOX가 전달되면,

BOOL save = FALSE;
DWORD authPackage = 0;
LPVOID authBuffer;
ULONG authBufferSize = 0;
CREDUI_INFO credUiInfo;

// ...

DWORD dwFlags = CREDUIWIN_CHECKBOX;

DWORD dwResult = CredUIPromptForWindowsCredentials(&(credUiInfo), 0, &(authPackage),
    NULL, 0, &authBuffer, &authBufferSize, &(save), dwFlags);

이렇게 "Remember my credentials" 선택 상자가 보여집니다.



사용자가 이 값을 설정했는지의 여부는 8번째 인자인 "_Inout_opt_ BOOL *pfSave"로 알아낼 수 있습니다. 물론, 전달 시 "TRUE"로 해주면 대화창에서는 미리 선택된 체로 나옵니다.



CREDUIWIN_GENERIC인 경우, CredUIPromptForWindowsCredentials API는 시스템에 등록된 사용자 정의 Credential Provider는 활성화시키지 않습니다. 또한 호출 후의 authBuffer에는 사용자가 입력한 '암호' 문자열이 평문으로 포함됩니다.



시스템에 등록된 사용자 정의 Credential Provider 중, 원하는 Provider를 지정해서 활성화시킬 수 있습니다.



활성화된 Credential Provider들은, 이 옵션이 전달된 경우 관리자 계정들만 열람해서 값을 반환해야 합니다. 문서에 따르면 "This value is intended for User Account Control (UAC) purposes only. We recommend that external callers not set this flag."라고 하면서 일반 사용자 응용 프로그램에서 쓰는 것을 권장하지 않고 있습니다.



긴말 필요없이, 이 옵션은 현실적으로 전달하고 싶지 않을 것입니다. (전달 시, 사용자 입장에서 너무 불편합니다.)

대충 이 정도 옵션만 다루고, 행여 나중에 또 필요한 경우가 생기면 다른 옵션도 설명할 기회를 갖겠습니다. ^^

---

[이 글에 대해서 여러분들과 의견을 공유하고 싶습니다. 틀리거나 미흡한 부분 또는 의문 사항이 있으시면 언제든 댓글 남겨주십시오.]

[최초 등록일: 12/12/2014]
[최종 수정일: 7/17/2021]


이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-변경금지 2.0 대한민국 라이센스에 따라 이용하실 수 있습니다.

by SeongTae Jeong, mailto:techsharer at outlook.com