Qt OAuth2 ブラウザサポート

OAuth2 ユーザーエージェント

OAuth2認証ステージでは 、ユーザーエージェントに依存します。 Qt WebEngine.

システムブラウザと組み込みユーザエージェントのどちらを選択するかは、いくつかの要因に依存します。以下は、いくつかの主な考慮事項を説明するものである：

• システムブラウザは、すでにユーザによるアクティブなログインを持っている可能性がある。そのため、認可段階でのユーザ認証は、既存のログインを使用できるため、より簡単かもしれません。これとは対照的に、埋め込みユーザエージェントの場合、ユーザは通常、新しいログインを実行する必要があります。一方、システムブラウザにログインセッションを残すことは、必ずしも望ましいとは限りません。システムブラウザはまた、アプリケーションの使用データを他者と共有する可能性があります。
• システムブラウザは通常、ユーザーにとって使い慣れたものであり、ログインのための使い慣れたユーザーエクスペリエンスを提供します。一方、埋め込みユーザーエージェントは、見慣れたルックアンドフィールを提供しないかもしれませんが、アプリケーション開発者は、ログインインタラクションを別のブラウザウィンドウで発生させるのではなく、アプリケーションウィンドウの一部として埋め込むことができます。さらに、アプリケーション開発者は、必要なくなったら埋め込みユーザーエージェントを自動的に閉じることができます。
• システムブラウザは、アドレスバーや証明書の検証のような、使い慣れたセキュリティビジュアルをユーザに提供します。これらは埋め込みユーザエージェントでは見えないかもしれません。さらに、システムブラウザは、基礎となるオペレーティングシステムのセキュリティ機能をよりよく活用するかもしれません。
• 組み込みのユーザエージェントは、ユーザが入力したすべてのセキュリティ証明書にアクセスできる可能性があります。
• すべてのプラットフォームが、https やカスタムURIスキームによるリダイレクトURLの処理をサポートしているわけではありません(QOAuthUriSchemeReplyHandler 参照)。これらのプラットフォームでは、組み込みユーザーエージェントを使用して制限を回避することができます。
• 埋め込みユーザーエージェントをアプリケーションの一部として含めることは、一般的に大きなコン ポーネントとなり、アプリケーションのストレージフットプリントを増加させます。一方、すべてのユースケースにおいて、システムブラウザが利用できないかもしれませんし、アプリケーションは他の目的のためにすでに組み込みユーザエージェントを使用しているかもしれません。

これらのことを考慮すると、ネイティブ・アプリケーションではシステム・ブラウザを使用することが推奨されます。しかし、上記のいくつかの点が示唆しているように、組み込みユーザーエージェントを使用するための有効なユースケースがまだあるかもしれません。

システムブラウザの使用

システムブラウザを使用するには、それを開き、アプリケーションによって設定された認可URLに移動する必要があります。典型的な使い方は以下のようになる：

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);

コードはQAbstractOAuth::authorizeWithBrowser シグナルとQDesktopServices::openUrl スロットを接続する。これによりシステムブラウザが開き、ユーザーは必要な認証と認可を行います。アプリケーションや Qt ライブラリは、システムブラウザを直接制御することはできません。

システムブラウザでサポートされるリダイレクト URL スキームの詳細については、Qt OAuth2 Overview,QOAuthHttpServerReplyHandler,QOAuthUriSchemeReplyHandler を参照してください。

使用方法Qt WebEngine

Qt WebEngineは、Qt アプリケーションに直接 Web コンテンツを埋め込むための Web ブラウザエンジンを提供します。

コアとなるコントロール機能とともに、QtWidgets と QtQuick アプリケーション用の使いやすいビューが用意されています。これらのビューは OAuth2 認証のユーザーエージェントとして使用できます。 Qt WebEngineは大規模で多用途なモジュールですが、このドキュメントでは OAuth2 認証での使用に焦点を当てています。

QtWebEngine をアプリケーションの一部として組み込む方法はたくさんあります。実用的な観点からの主な検討事項は以下の通りです：

• QtQuick vs QtWidgets アプリケーションです。QtQuick と QtWidgets のアプリケーションの違いは、QtNetworkAuth クラスとの必要な統合の設定方法に影響します。
• リダイレクト URI スキーム。これは、どのQtNetworkAuth リプライハンドラクラスをどのように使用するかに影響します（Qt OAuth2 Overview を参照）。

QtQuick と QtWidgets アプリケーション

QtWebEngine は、OAuth2 認証のために QtQuick と QtWidgets の両方のアプリケーションで使うことができます。主な違いは、いくつかの必要なイネーブラの設定方法です。

以下はQWebEngineView (QtWidget) のセットアップを簡略化したものです。エラー処理と潜在的な Qt WebEngine設定は省略します。

以下のウィジェットを想定しています：

QWebEngineView *webView = nullptr;
QMainWindow mainWindow;

システム・ブラウザを開く代わりに、QWebEngineView を使って認証を行います：

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, [this](const QUrl &url) {
    mainWindow.show();
    webView->load(url);
    webView->show();
});

認証が完了したら、ビューを閉じます：

connect(&m_oauth, &QAbstractOAuth::granted, this, [this]() {
    // Here we use QNetworkRequestFactory to store the access token
    m_api.setBearerToken(m_oauth.token().toLatin1());
    m_handler->close();
    webView->close();
});

QtQuickアプリケーションのフローは原則的に同じですが、QWebEngineView ウィジェットの代わりに、WebEngineView QML要素を使用します：

WebEngineView {
    id: authorizationWebView
    anchors.fill: parent
    visible: false
}

この単純化した例では、C++クラスから必要なAPIを公開しています。

class HttpExample : public QObject
{
    Q_OBJECT
#ifdef QT_QML_LIB
    QML_NAMED_ELEMENT(OAuth2)
#endif
public:
    Q_INVOKABLE void authorize();

signals:
    void authorizationCompleted(bool success);
    void authorizeWithBrowser(const QUrl &url);

この単純化された例は、必要なAPIをC++クラスから公開し、QML側でWebEngineView ：

onAuthorizeWithBrowser:
    (url) => {
        console.log("Starting authorization with WebView")
        authorizationWebView.url = url
        authorizationWebView.visible = true
    }
onAuthorizationCompleted:
    (success) => {
        console.log("Authorized: " + success);
        authorizationWebView.visible = false
    }

リダイレクトURIスキーム

リダイレクトURIスキーム（http 、https 、custom-uri スキーム）の選択は、次のような使い方に影響します。 Qt WebEngine.

httpループバックURI

http ループバックリダイレクト URI とQOAuthHttpServerReplyHandler では、システムブラウザと同様に動作します。QtWebEngine は、システムブラウザと同様に、認可をリプライハンドラのローカルホストサーバにリダイレクトします。

カスタムスキーム URI

カスタムスキームURI（com.example.myqtapp:/redirect ）やQOAuthUriSchemeReplyHandler のフローもシステムブラウザと同様に動作します。

主な違いは、QOAuthUriSchemeReplyHandler ドキュメントで説明されているように、iOS/macOSのユニバーサルリンクや Androidのアプリリンクのようにアプリケーションを設定する必要がないことです。

m_handler.setRedirectUrl(QUrl{"com.example.myqtapp://oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, [this](const QUrl &url) {
    mainWindow.show();
    webView->load(url);
    webView->show();
});
connect(&m_oauth, &QAbstractOAuth::granted, this, [this]() {
    // Here we use QNetworkRequestFactory to store the access token
    m_api.setBearerToken(m_oauth.token().toLatin1());
    m_handler.close();
    webView->close();
});

技術的には Qt WebEngineQOAuthUriSchemeReplyHandler は、未処理の URI スキームに対してQDesktopServices::openUrl() を呼び出します。

https URI

https URI とQOAuthUriSchemeReplyHandler では、ロジックが少し変わります。カスタムスキーム URI の場合と同様に、アプリケーションを設定する必要はありませんが、認証段階の最後にリダイレクトをウェブエンジンに提供する必要があります。

connect(webView, &QWebEngineView::urlChanged, this, [this](const QUrl &url){
    m_handler.handleAuthorizationRedirect(url);
});

これは Qt WebEngineから見ると、リダイレクトURLは有効なhttps URLであり、デフォルトではそのURLへのナビゲーションを試みます。

このようなナビゲーションの試みと、偶発的な認証コードの暴露（リダイレクトURLのドメインがあなたの管理下にない場合を考慮してください）を防ぐために、より複雑なフィルタリングを使用する必要があります。また、QOAuth2AuthorizationCodeFlow::PkceMethod の使用は、認証コードハイジャックの影響を軽減するため、強く推奨されます。

例えば

connect(webView->page(), &QWebEnginePage::navigationRequested,
        this, [this](QWebEngineNavigationRequest &request) {
    if (request.navigationType() == QWebEngineNavigationRequest::RedirectNavigation
        && m_handler.handleAuthorizationRedirect(request.url())) {
        request.reject();
        webView->close();
    } else {
        request.accept();
    }
});