웹 인증 브로커
이 문서에서는 UWP(유니버설 Windows 플랫폼) 앱을 OpenID 또는 OAuth와 같은 인증 프로토콜을 사용하는 온라인 ID 공급자에 연결하는 방법을 설명합니다. AuthenticateAsync 메서드는 온라인 ID 공급자로 요청을 보내고, 앱이 액세스할 수 있는 공급자 리소스에 대해 설명하는 액세스 토큰을 다시 가져옵니다.
참고 항목
완전한 코드 샘플을 사용하려면 GitHub의 WebAuthenticationBroker 리포지토리를 복제하세요.
온라인 공급자에 앱 등록하기
연결하려는 온라인 ID 공급자에게 앱을 등록해야 합니다. ID 공급자에서 앱을 등록하는 방법을 확인할 수 있습니다. 등록 후 온라인 공급자는 보통 앱에 대한 ID 또는 비밀 키를 제공합니다.
인증 요청 URI 빌드하기
요청 URI는 앱 ID 또는 인증 완료 후 사용자가 전송되는 기밀 리디렉션 URI 그리고 예상 응답 유형과 같은 다른 필수 정보가 첨부된 온라인 공급자에게 인증 요청을 보내는 주소로 구성됩니다. 공급자에게 필요한 매개 변수를 확인할 수 있습니다.
requestUri 매개 변수로써 전송된 요청 URI는 AuthenticateAsync 메서드 변수 형태로 전송됩니다. https://로 시작하는 보안 주소여야 합니다.
다음 예제는 URI 요청을 빌드하는 방법을 보여 줍니다.
string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";
System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);
온라인 공급자에게 연결
AuthenticateAsync 메서드를 호출하여 온라인 ID 공급자에게 연결하고 엑세스 토큰을 확보합니다. 이 메서드는 이전 단계에서 requestUri 매개 변수로써 만들어진 URI와 , 사용자를 callbackUri 매개 변수로 리디렉션 하는 URI를 취합니다.
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI,
endURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
Warning
AuthenticateAsync 외에도 Windows.Security.Authentication.Web namespace는 AuthenticateAndContinue 메서드가 포함되어 있습니다. 이 메서드를 호출하지 마세요. 오로지 Windows Phone 8.1만을 대상으로 하는 앱 전용으로 설계되었으며 Windows 10부터는 사용되지 않습니다.
SSO(Single Sign-On)를 사용하여 연결하기.
통상적으로 웹 인증 브로커는 쿠키 유지를 허용하지 않습니다. 이 때문에 앱 사용자가 로그인 상태 유지 의사를 표시하더라도(예: 공급자의 로그인 대화 상자에서 체크박스를 선택하여) 해당 공급자의 리소스에 액세스할 때마다 로그인해야 합니다. SSO를 사용하여 로그인 하려면 온라인 ID 공급자가 웹 인증 브로커의 SSO를 활성화 해야 하고 당신의 앱은 AuthenticateAsync 오버로드, 즉 callbackUri 매개 변수를 사용하지 않는 오버로드를 호출해야 합니다. 이렇게 하면 웹 인증 브로커가 영구적 쿠키를 저장할 수 있기 때문에 향후 같은 앱에서 인증을 호출할 때 사용자가 반복적으로 로그인을 할 필요가 없습니다(액세스 토큰이 만료될 때까지 사용자가 효과적으로 "로그인").
SSO를 지원하려면 온라인 공급자가 ms-app://<appSID> 형식의 리디렉션 URI를 등록할 수 있도록 허용해야 합니다. 여기서 <appSID>는 앱의 SID입니다. 앱의 앱 개발자 페이지에서나 GetCurrentApplicationCallbackUri 메서드를 호출하거나 해서 앱의 SID를 찾을 수 있습니다.
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
디버깅
운영 로그를 검토하거나 Fiddler를 사용하여 웹 요청 및 응답을 검토하는 등 웹 인증 브로커 API 오류를 해결하는 대에는 여러 가지 방법이 있습니다.
작업 로그.
작업 로그를 사용하여 작동하지 않는 항목을 확인할 수 있는 경우가 많습니다. 웹 사이트 개발자가 웹 인증 브로커에 의한 웹 페이지 처리 방법을 이해할 수 있도록 도와주는 전용 이벤트 로그 채널인 Microsoft-Windows-WebAuth\Operational이 있습니다. 이 채널을 사용하려면 eventvwr.exe를 시작하고 Application and Services\Microsoft\Windows\WebAuth 아래의 작업 로그를 사용하도록 설정합니다. 또한 웹 인증 브로커는 사용자 에이전트 스트링에 고유한 스트링을 추가하여 웹 서버에서 자신을 식별합니다. 스트링은 "MSAuthHost/1.0"입니다. 버전 번호는 나중에 바뀔 수 있으므로 코드에서 해당 버전 번호를 신뢰해서는 안 됩니다. 전체 사용자 에이전트 스트링과 전체 디버깅 단계의 예는 다음과 같습니다.
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)
- 작업 로그를 활성화하세요.
- Contoso 소셜 애플리케이션을 실행하세요.
- 생성된 로그 항목을 사용하면 웹 인증 브로커의 동작을 더 자세히 이해할 수 있게 됩니다. 이 사례의 경우, 다음을 포함할 수 있습니다:
- 탐색 시작: AuthHost가 시작될 때 기록되고 시작 및 종료 URL 정보가 포함됩니다.
- 탐색 완료: 웹 페이지 로딩 완료를 기록합니다.
- 메타 태그: 메타 태그를 조우하면 세부 정보와 함께 기록합니다.
- 탐색 종료: 사용자가 종료한 탐색일 경우 입니다.
- 탐색 오류: AuthHost가 HttpStatusCode를 포함한 URL에서 탐색 오류를 접하였습니다.
- 탐색 끝: 종료 URL이 조우되었습니다.
Fiddler
Fiddler 웹 디버거는 앱과 함께 사용할 수 있습니다. 자세한 내용은 Fiddler 설명서를 참조하세요.
AuthHost는 개인 네트워크 기능을 제공하기 위해 고유한 앱 컨테이너에서 실행되므로 레지스트리 키를 설정해야 합니다. Windows 레지스트리 편집기 버전 5.00
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001
이 레지스트리 키가 없는 경우 관리자 권한으로 명령 프롬프트에서 만들 수 있습니다.
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f이것이 아웃바운드 트래픽을 생성하기 때문에 AuthHost에 대한 규칙을 추가하세요.
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s List Loopback Exempted AppContainers [1] ----------------------------------------------------------------- Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe SID: S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349 [2] ----------------------------------------------------------------- Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe SID: S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544 [3] ----------------------------------------------------------------- Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe SID: S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935Fiddler로 들어오는 트래픽의 방화벽 규칙을 추가합니다.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기