Sdílet prostřednictvím

Implementace OAuth 2.0 v aplikacích pro Windows

OAuth2Manager v Windows App SDK umožňuje desktopovým aplikacím, jako je WinUI 3, bezproblémově provádět autorizaci OAuth 2.0 ve Windows. Rozhraní OAuth2Manager API neposkytuje rozhraní API pro implicitní žádosti a přihlašovací údaje pro vlastníky prostředků kvůli souvisejícím obavám o bezpečnost. Použijte typ udělení autorizačního kódu s ověřovacím klíčem pro kód Exchange (PKCE). Další informace najdete v dokumentu PKCE RFC.

Pozadí OAuth 2.0 pro aplikace pro Windows

Windows Runtime (WinRT) WebAuthenticationBroker, která je primárně určená pro aplikace pro UPW, představuje při použití v desktopových aplikacích několik problémů. Mezi klíčové problémy patří závislost na ApplicationView, která není kompatibilní s architekturami desktopových aplikací. Vývojáři se proto musí uchylovat k alternativním řešením zahrnujícím rozhraní vzájemné spolupráce a další kód pro implementaci funkcí OAuth 2.0 do WinUI a dalších desktopových aplikací.

Rozhraní API OAuth2Manager v Windows App SDK

Rozhraní API OAuth2Manager pro Windows App SDK poskytuje zjednodušené řešení, které splňuje očekávání vývojářů. Nabízí bezproblémové funkce OAuth 2.0 s plnou paritou funkcí na všech platformách Windows podporovaných Windows App SDK. Nové rozhraní API eliminuje potřebu těžkopádných alternativních řešení a zjednodušuje proces začlenění funkcí OAuth 2.0 do desktopových aplikací.

OAuth2Manager se liší od WebAuthenticationBroker v WinRT. Řídí se osvědčenými postupy OAuth 2.0 podrobněji – například pomocí výchozího prohlížeče uživatele. Osvědčené postupy pro rozhraní API pocházejí z IETF (Internet Engineering Task Force) OAuth 2.0 Authorization Framework RFC 6749, PKCE RFC 7636 a OAuth 2.0 pro nativní aplikace RFC 8252.

Příklady kódu OAuth 2.0

Úplná ukázková aplikace WinUI je k dispozici na GitHub. Následující části obsahují fragmenty kódu pro nejběžnější toky OAuth 2.0 pomocí rozhraní OAuth2Manager API.

Žádost o autorizační kód

Následující příklad ukazuje, jak provést žádost o autorizační kód pomocí OAuth2Manager v Windows App SDK:

// Get the WindowId for the application window
Microsoft::UI::WindowId parentWindowId = this->AppWindow().Id();

AuthRequestParams authRequestParams = AuthRequestParams::CreateForAuthorizationCodeRequest(L"my_client_id",
   Uri(L"my-app:/oauth-callback/"));
authRequestParams.Scope(L"user:email user:birthday");

AuthRequestResult authRequestResult = co_await OAuth2Manager::RequestAuthWithParamsAsync(parentWindowId, 
   Uri(L"https://my.server.com/oauth/authorize"), authRequestParams);
if (AuthResponse authResponse = authRequestResult.Response())
{
   //To obtain the authorization code
   //authResponse.Code();

   //To obtain the access token
   DoTokenExchange(authResponse);
}
else
{
   AuthFailure authFailure = authRequestResult.Failure();
   NotifyFailure(authFailure.Error(), authFailure.ErrorDescription());
}

Vyměňte autorizační kód za přístupový token

Následující příklad ukazuje, jak pomocí OAuth2Manager vyměnit autorizační kód za přístupový token.

Pro veřejné klienty (například nativní desktopové aplikace), kteří používají PKCE, nezahrnujte tajný klíč klienta. Ověřovatel kódu PKCE místo toho poskytuje zabezpečení:

AuthResponse authResponse = authRequestResult.Response();
TokenRequestParams tokenRequestParams = TokenRequestParams::CreateForAuthorizationCodeRequest(authResponse);

// For public clients using PKCE, do not include ClientAuthentication
TokenRequestResult tokenRequestResult = co_await OAuth2Manager::RequestTokenAsync(
    Uri(L"https://my.server.com/oauth/token"), tokenRequestParams);
if (TokenResponse tokenResponse = tokenRequestResult.Response())
{
    String accessToken = tokenResponse.AccessToken();
    String tokenType = tokenResponse.TokenType();

    // RefreshToken string null/empty when not present
    if (String refreshToken = tokenResponse.RefreshToken(); !refreshToken.empty())
    {
        // ExpiresIn is zero when not present
        DateTime expires = winrt::clock::now();
        if (String expiresIn = tokenResponse.ExpiresIn(); std::stoi(expiresIn) != 0)
        {
            expires += std::chrono::seconds(static_cast<int64_t>(std::stoi(expiresIn)));
        }
        else
        {
            // Assume a duration of one hour
            expires += std::chrono::hours(1);
        }

        //Schedule a refresh of the access token
        myAppState.ScheduleRefreshAt(expires, refreshToken);
    }

    // Use the access token for resources
    DoRequestWithToken(accessToken, tokenType);
}
else
{
    TokenFailure tokenFailure = tokenRequestResult.Failure();
    NotifyFailure(tokenFailure.Error(), tokenFailure.ErrorDescription());
}

Pro klienty confidential (například web apps nebo služby), které mají tajný klíč klienta, zahrňte parametr ClientAuthentication:

AuthResponse authResponse = authRequestResult.Response();
TokenRequestParams tokenRequestParams = TokenRequestParams::CreateForAuthorizationCodeRequest(authResponse);
ClientAuthentication clientAuth = ClientAuthentication::CreateForBasicAuthorization(L"my_client_id",
    L"my_client_secret");

TokenRequestResult tokenRequestResult = co_await OAuth2Manager::RequestTokenAsync(
    Uri(L"https://my.server.com/oauth/token"), tokenRequestParams, clientAuth);
// Handle the response as shown in the previous example

Aktualizace tokenu access

Následující příklad ukazuje, jak aktualizovat token access pomocí metody OAuth2ManagerRefreshTokenAsync.

Pro veřejné klienty , kteří používají PKCE, vynecháte ClientAuthentication parametr:

TokenRequestParams tokenRequestParams = TokenRequestParams::CreateForRefreshToken(refreshToken);

// For public clients using PKCE, do not include ClientAuthentication
TokenRequestResult tokenRequestResult = co_await OAuth2Manager::RequestTokenAsync(
    Uri(L"https://my.server.com/oauth/token"), tokenRequestParams);
if (TokenResponse tokenResponse = tokenRequestResult.Response())
{
    UpdateToken(tokenResponse.AccessToken(), tokenResponse.TokenType(), tokenResponse.ExpiresIn());

    //Store new refresh token if present
    if (String refreshToken = tokenResponse.RefreshToken(); !refreshToken.empty())
    {
        // ExpiresIn is zero when not present
        DateTime expires = winrt::clock::now();
        if (String expiresInStr = tokenResponse.ExpiresIn(); !expiresInStr.empty())
        {
            int expiresIn = std::stoi(expiresInStr);
            if (expiresIn != 0)
            {
                expires += std::chrono::seconds(static_cast<int64_t>(expiresIn));
            }
        }
        else
        {
            // Assume a duration of one hour
            expires += std::chrono::hours(1);
        }

        //Schedule a refresh of the access token
        myAppState.ScheduleRefreshAt(expires, refreshToken);
    }
}
else
{
    TokenFailure tokenFailure = tokenRequestResult.Failure();
    NotifyFailure(tokenFailure.Error(), tokenFailure.ErrorDescription());
}

U důvěrných klientů , kteří mají tajný klíč klienta, uveďte ClientAuthentication parametr:

TokenRequestParams tokenRequestParams = TokenRequestParams::CreateForRefreshToken(refreshToken);
ClientAuthentication clientAuth = ClientAuthentication::CreateForBasicAuthorization(L"my_client_id",
    L"my_client_secret");
TokenRequestResult tokenRequestResult = co_await OAuth2Manager::RequestTokenAsync(
    Uri(L"https://my.server.com/oauth/token"), tokenRequestParams, clientAuth);
// Handle the response as shown in the previous example

Dokončení žádosti o autorizaci

K dokončení žádosti o autorizaci z aktivace protokolu by vaše aplikace měla zpracovat událost AppInstance.Activated . Tato událost se vyžaduje, když má vaše aplikace vlastní logiku přesměrování. Úplný příklad je k dispozici na GitHub.

Použijte následující kód:

void App::OnActivated(const IActivatedEventArgs& args)
{
    if (args.Kind() == ActivationKind::Protocol)
    {
        auto protocolArgs = args.as<ProtocolActivatedEventArgs>();
        if (OAuth2Manager::CompleteAuthRequest(protocolArgs.Uri()))
        {
            TerminateCurrentProcess();
        }

        DisplayUnhandledMessageToUser();
    }
}

Související obsah

  • Last updated on