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スキームについては、「OAuth 2.0の概要」、QOAuthHttpServerReplyHandler 、およびQOAuthUriSchemeReplyHandler を参照してください。

を使用するとQt WebEngine

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

中核となる制御機能に加え、QtWidgets および QtQuick アプリケーションの両方に対応した使いやすいビューが用意されています。これらのビューは、OAuth 2.0 認証におけるユーザーエージェントとして使用できます。 Qt WebEngine は、大規模で汎用性の高いモジュールであり、このドキュメントでは OAuth2 認証での使用に焦点を当てています。

Qt WebEngine をアプリケーションの一部として組み込む方法は数多くあります。実用的な観点から、主な考慮事項は以下の通りです。

• QtQuick アプリケーションと QtWidgets アプリケーションの区別。これは、QtNetworkAuth クラスとの必要な統合をどのように設定するかに影響します。
• リダイレクトURIスキーマ。これは、どのQtNetworkAuth レスポンスハンドラクラスを使用するか、およびその使用方法に影響します（OAuth 2.0の概要を参照）。

QtQuick および QtWidgets アプリケーション

Qt WebEngine は、OAuth 2.0 認証において 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);

これらは、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 を使用する場合、処理はシステムブラウザと同様に行われます。Qt WebEngine を使用すると、システムブラウザと同様に、認証がリプライハンドラの localhost サーバーにリダイレクトされます。

カスタムスキームの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 WebEngine 未処理のURIスキーマに対してQDesktopServices::openUrl()を呼び出し、それに対応するQOAuthUriSchemeReplyHandler がこれをリッスンします。

https URI

https URI およびQOAuthUriSchemeReplyHandler を使用する場合、ロジックは若干異なります。カスタムスキーム URIと同様に、アプリケーションの設定は必要ありませんが、認証段階の最後に Web エンジンへのリダイレクトを指定する必要があります。

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();
    }
});