상태
패키지 상태: 구현됨 · 로컬 검증 완료. dotnet test가 19개 케이스를 통과합니다(net8.0 크로스 플랫폼 빌드 및 net10.0). Windows 전용 API(WebView2, DPAPI, WinUI 3)는 검증을 위해 Windows 빌드 환경이 필요합니다. 실제 IdP 왕복 테스트는 수동 검증 대기 중입니다. 이 페이지는 구현된 동작을 문서화하며, 프로덕션 준비 완료를 의미하지 않습니다.
요구 사항
- .NET 8 및 Windows App SDK 1.6+
- WebView2 런타임(Evergreen — Microsoft Edge에 사전 설치됨)
- 프로젝트 파일에 <UseWinUI>true</UseWinUI>를 설정해야 합니다
설치
애플리케이션 프로젝트 파일에 PackageReference를 추가하세요:
<ItemGroup>
<PackageReference Include="Xid.Windows" Version="0.1.0" />
</ItemGroup>빠른 시작
using Xid.Windows;
// 1. Configure in App.xaml.cs OnLaunched
XidClient.Shared.Configure(new XidConfiguration
{
Issuer = new Uri("https://xid.dev"),
ClientId = "your_client_id",
RedirectUri = "com.example.myapp://auth/callback",
// Scopes default: openid profile email offline_access
});
// 2. Sign in (opens embedded WebView2 window)
XidSession session = await XidClient.Shared.SignInAsync();
Console.WriteLine($"Signed in: {session.User.Email}");
// 3. Get a valid access token (auto-refresh)
string? token = await XidClient.Shared.GetAccessToken();
// 4. Get current session
XidSession? current = await XidClient.Shared.GetSession();
// 5. Sign out
await XidClient.Shared.SignOut();사용자 정의 URI 스킴 콜백(선택 사항)
WebView2 임베드 창 대신 사용자 정의 URI 스킴 리디렉션을 사용하는 경우 프로토콜 활성화 URI를 HandleRedirectAsync로 전달하세요:
// App.xaml.cs
protected override void OnActivated(IActivatedEventArgs args)
{
if (args.Kind == ActivationKind.Protocol)
{
var protocolArgs = (ProtocolActivatedEventArgs)args;
await XidClient.Shared.HandleRedirectAsync(protocolArgs.Uri);
}
}핵심 API
| 방법 | 설명 |
|---|---|
Configure(XidConfiguration) |
SDK를 초기화합니다. 애플리케이션 시작 시 한 번 호출하세요. |
SignInAsync(options?, ct) |
PKCE S256을 사용하여 임베드 WebView2 인증 창을 엽니다. 완료 시 XidSession을 반환합니다. |
HandleRedirectAsync(Uri, ct) |
사용자 정의 URI 스킴 콜백을 처리하고 인증 코드를 교환합니다. |
GetSession(ct) |
현재 세션을 반환하며 만료가 임박한 경우 자동으로 갱신합니다. |
GetAccessToken(options?, ct) |
유효한 액세스 토큰 문자열을 반환하며 필요 시 갱신을 트리거합니다. |
SignOut(ct) |
DPAPI 보호 IsolatedStorage에서 로컬 세션 토큰을 삭제합니다. |
SetTokenStorage(ITokenStorage) |
기본 DpapiTokenStorage를 사용자 정의 ITokenStorage 구현으로 교체합니다. |
저장소 어댑터
기본 저장소는 DPAPI(CurrentUser 범위)로 토큰을 암호화하고 IsolatedStorage에 저장합니다. Windows Hello 또는 Credential Manager를 사용하려면 ITokenStorage를 구현하세요:
public sealed class MyCustomStorage : ITokenStorage
{
public Task SaveAsync(StoredTokenSet tokens, CancellationToken ct = default) { ... }
public Task<StoredTokenSet?> LoadAsync(CancellationToken ct = default) { ... }
public Task ClearAsync(CancellationToken ct = default) { ... }
}
XidClient.Shared.SetTokenStorage(new MyCustomStorage());의존성
| 패키지 | 버전 | 목적 |
|---|---|---|
Microsoft.WindowsAppSDK |
1.6.250228002 | WinUI 3 호스트 및 WebView2 임베딩 |
Microsoft.Web.WebView2 |
1.0.3065.39 | Chromium 기반 임베드 인증 창 |
System.Security.Cryptography.ProtectedData |
8.0.0 | DPAPI 토큰 저장 암호화 |
보안
- 공개 클라이언트 — client secret이 저장되거나 전송되지 않습니다.
- PKCE S256만 사용합니다. 서버는 plain challenge 방식을 거부합니다.
- DPAPI(CurrentUser 범위)로 암호화되어 IsolatedStorage에 저장된 토큰. 다른 Windows 사용자 계정에서는 접근할 수 없습니다.
- 요청마다 생성되는 OAuth state; CSRF를 방지하기 위해 리디렉션 시 검증됩니다.
알려진 제한 사항
- WebView2 런타임이 있어야 합니다. 폴백으로 WebAuthenticationBroker 지원이 계획되어 있지만 아직 구현되지 않았습니다.
- JWKS 기반 ID token 검증과 end_session sign-out은 구현되어 로컬 테스트를 통과했습니다. L4 지원 전에는 Windows WebView2, DPAPI, IdP 검증이 필요합니다.
- DpapiTokenStorage는 Windows 이외의 플랫폼에서 실행되지 않습니다. 크로스 컴파일 시 다른 ITokenStorage 구현을 사용하세요.