Qt OAuth2 の概要

OAuth2

RFC 6749 OAuth 2.0は、パスワードのような機密性の高いユーザー情報を公開することなくリソースの認可を可能にする認可フレームワークを定義しています。

OAuth2 フレームワークでは、いくつかのクライアントタイプ（パブリックと機密）とフロー（暗黙的、認証コード、その他）が定義されています。典型的な Qt アプリケーションの場合、クライアントタイプはpublic ネイティブアプリケーションとみなされます。publicは、出荷されたバイナリに埋め込まれたパスワードのような秘密を保持するために、アプリケーションが信頼されていないことを意味します。

RFC 8252 OAuth 2.0 for Native Appsは、このようなアプリケーションのベストプラクティスをさらに定義しています。特に、Authorization Code Flowを推奨フローとして定義しています。QtNetworkAuth は、このフローの具体的な実装を提供しており、このドキュメントの焦点でもあります。

Qt OAuth2 クラス

QtNetworkAuth Qt OAuth2 には、具象クラスと抽象クラスの両方が用意されています。抽象クラスはカスタムフローを実装するためのもので、具象クラスは具体的な実装を提供します。

OAuth2 フローをQtNetworkAuth で実装するには、2 つのクラスが必要です：

• OAuth2 フロー実装クラスはメイン API を提供し、フローのオーケストレータとなる。OAuth2 フロー実装クラスは主要な API を提供し、フローのオーケストレータとなる。抽象クラスはQAbstractOAuth2 であり、具体的な実装はQOAuth2AuthorizationCodeFlow である。
• リプライハンドラクラスは、認可サーバーからのリプライを処理する。認可コードフローでは、認可、アクセストークン要求、アクセストークン更新が含まれる。リプライの処理結果は、さらにフロークラスで処理される。リプライハンドラの抽象クラスはQAbstractOAuthReplyHandler であり、具象クラスはQOAuthHttpServerReplyHandler とQOAuthUriSchemeReplyHandler である。

認可コードフロー

認可コードフローは、Qtアプリケーションのようなネイティブアプリケーションに推奨されるOAuth2フローです。

次のコード・スニペットは、セットアップの例です：

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;
m_oauth.setAuthorizationUrl(QUrl("https://some.authorization.service/v3/authorize"_L1));
m_oauth.setAccessTokenUrl(QUrl("https://some.authorization.service/v3/access_token"_L1));
m_oauth.setClientIdentifier("a_client_id"_L1);
m_oauth.setScope("read"_L1);

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);
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();
});
m_handler.setRedirectUrl(QUrl{"com.my.app:/oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);

// Initiate the authorization
if (m_handler.listen()) {
    m_oauth.grant();
}

ステージ

認可コードフローには2つの主要なステージがあります：リソースの認可（必要なユーザー認証を含む）とアクセストークンのリクエストです。さらに、アクセストークンの使用とアクセストークンの更新が続きます。以下の図に、これらのステージを示します：

• 認可段階では、ユーザーは認証され、リソースへのアクセスを認可します。これには、ユーザーによるブラウザの操作が必要です。
• 認可後、受け取った認可コードを使用してアクセストークンを要求し、オプションでリフレッシュトークンを要求します。
• アクセストークンが取得されると、アプリケーションはそれを使用して目的のリソースにアクセスします。アクセストークンはリソースリクエストに含まれ、トークンの有効性を確認するのはリソースサーバーです。トークンをリクエストに含める方法はいくつかありますが、HTTPAuthorization ヘッダーに含めるのが最も一般的です。
• アクセストークンの更新。アクセストークンの有効期限は、通常1時間など比較的早く切れます。もしアプリケーションがアクセストークンに加えてリフレッシュトークンを受け取った場合、そのリフレッシュトークンを使って新しいアクセストークンをリクエストすることができます。リフレッシュ・トークンは長寿命であり、アプリケーションはそれを永続化することで、新たな認可段階（ひいてはブラウザとの再インタラクション）の必要性を回避することができます。

詳細とカスタマイズ

OAuth2 のフローは動的で、詳細を追うのは最初は難しいかもしれません。下の図は、成功した認証コードフローの主な詳細を示しています。

わかりやすくするために、この図ではあまり使用されないシグナルを省略していますが、全体として詳細と主なカスタマイズポイントを示しています。カスタマイズのポイントは、アプリケーションがキャッチできる（そしてコールできる）さまざまなシグナル/スロットと、QAbstractOAuth::setModifyParametersFunction （）で設定可能なコールバックです。

リプライ・ハンドラの選択

どのリプライハンドラを使うか、あるいは実装するかは、使用するredirect_uriに依存します。redirect_uri は、認可の段階が終了したときにブラウザがリダイレクトされる場所です。

ネイティブアプリケーションのコンテキストでは、RFC8252は3つの主要な タイプのURIスキームを概説している：loopback https 。

• 私用URI：私用URI: OSがアプリケーションにカスタムURIスキームを登録することを許可 している場合に使用できる。このようなカスタムスキームを持つURLを開こうとすると、関連する ネイティブアプリケーションが開かれる。QOAuthUriSchemeReplyHandler を参照のこと。
• HTTPS URI：OS がアプリケーションにカスタム HTTPS URL の登録を許可している場合に使用できます。このURLを開こうとすると、関連するネイティブアプリケーショ ンが開かれる。OSがサポートしていれば、このスキームを推奨する。QOAuthUriSchemeReplyHandler を参照のこと。
• ループバックインターフェース：これらはデスクトップ・アプリケーションや開発中のアプリケーションによく使われる。QOAuthHttpServerReplyHandler は、リダイレクトを処理するローカルサーバーをセットアップする ことで、これらのURIを処理するように設計されている。

選択は以下のようないくつかの要因に依存する：

• 認可サーバーベンダーがサポートするリダイレクトURI。リダイレクトURIは認証サーバベンダによってサポートされている。サポートはベンダによって異なり、特定のクライアントのタイプやオペレーティングシステムに固有であることが多い。また、アプリケーションが公開されているかどうかによってもサポートが異なる場合がある。
• ターゲットプラットフォームがサポートするリダイレクトURIスキーム。
• アプリケーション固有の使いやすさ、セキュリティ、その他の要件。

RFC 8252では、他の方法よりもセキュリティと使いやすさの点で優れているとして、 https スキームの使用を推奨している。