OAuth2.0の設定と技術的詳細

この記事では、Tulipがコネクタ認証にOAuthを実装する方法について、技術的な詳細を掘り下げていきます。OAuthは強力ですが、これには複雑さが伴います。このガイドは、Tulipが何をサポートし、それがどのように統合されるのかに関する技術的な疑問を解決することを目的としています。

注意：クライアント認証情報のフローは、認証コードのフローとは多少異なります。ステップ 1 と 2 は、クライアント認証情報のフローとは関係ありません。

Tulip 認証コードフロー

Tulip は、コネクタをテストするとき、またはアプリケーション内でコネクタ機能を実行するときに、認証プロセスを開始する。

1.認証サーバへのリダイレクト：

Tulipアプリケーションは、response_type（認証コードフロー用に「code」に設定）、client_id（コネクタUIで割り当て）、redirect_uri（Tulipで事前定義）、スコープとオーディエンス（UIで設定）、およびstate（Cross-Site Request Forgery攻撃から保護するためのランダムな文字列）を含む特定のパラメータとともに、ユーザを認証サーバ（AS）にリダイレクトします。

例：GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&audience=AUDIENCE&state=STATE

2.ユーザが同意を与える：

認証サーバはユーザを認証し、同意画面をユーザに提示する。ユーザは要求されたパーミッションを確認し、サードパーティアプリケーションへのアクセスを許可するか拒否するかを決定することができる。

::: （警告）（注）give コネクタの構成内で、"Skip user consent prompt" コントロールを使用すると、認証要求のプロンプト属性を制御できます。このコントロールを無効にするとconsentが使用され、有効にするとloginが使用されます。

プロンプト属性の追加値が必要な場合は、support@tulip.co。
:::

3.認証コード：

ユーザーが同意した場合、認証サーバーは認証コードを生成し、認証コードとともにユーザーをTulipにリダイレクトします。stateパラメータも含まれ、クライアントがレスポンスの完全性を検証できるようにします。このstateパラメータは、ステップ1で渡されたstateパラメータと一致しなければならない。

クライアントのリダイレクトURIへのリダイレクト例：

REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE。

4.トークン要求：

これでクライアントは認証コードを持ち、それを使って認証サーバのトークン エンドポイントにセキュアなサーバ間リクエストを行う。クライアントは、grant_type (「authorization_code」に設定)、client_id、client_secret (クライアントと認証サーバのみが知っている秘密)、redirect_uri、認証コードを含む。

トークン・リクエストの例

POST /tokenContent-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET``.

5.アクセストークンのレスポンス：

アクセストークンのレスポンス： 認証コードが有効な場合、認証サーバはアクセストークンと、オプションでリフレッシュトークンを応答します。アクセストークンは、ユーザーに代わって保護されたAPIにリクエストを行う際に、クライアントが自分自身を認証するために使用されます。

トークン・レスポンスの例

{ "access_token"："ACCESS_TOKEN", "token_type"："Bearer", "expires_in"：3600, "refresh_token"："REFRESH_TOKEN", "scope"："スコープ"}。

6.リソースサーバーへのアクセス

Tulipは取得したアクセストークンを使って、ユーザーに代わってリソースサーバー(API)に認可されたリクエストを行うことができます。アクセストークンは通常、HTTPリクエストのAuthorizationヘッダーに含まれます。

APIリクエストの例:GET /api/resourceAuthorization：ベアラ ACCESS_TOKEN

リフレッシュ・トークンでトークンの有効期限を管理する

認可サーバーは通常、アクセスを規制するためにトークンに有効期限を設定します。しかし、有効期限が短いトークンは、常にユーザー認証を行うことで Tulip アプリケーションのユーザーエクスペリエンスを中断させるという課題をもたらします。

この問題に対処するために、OAuthはリフレッシュトークンをサポートしています。リフレッシュ・トークンはオプションですが、オペレーターによる手動入力を必要とせず、Tulipがトークンをシームレスにリフレッシュすることで、ユーザー・エクスペリエンスを合理化できるため、強く推奨されます。

Tulipがトークンのリフレッシュを管理する方法

Tulipは、アクセストークンの有効期限が切れたことを検知すると、自動的に関連するリフレッシュトークンを使用して新しいトークンの取得を試みます。その主な目的は、ユーザーの再認証を最小限に抑えることです。以下のステップは、Tulipが実行するロジックの概要です：

1. 有効期限の検出：
2. Tulipは、認証フローのステップ5で受け取ったexpires_in属性に基づいて、期限切れのトークンを識別します。

1. トークン・フローの試み：

2. Tulipは、最初の認証フローで使用されたグラントタイプを置き換え、refresh_tokenグラントタイプを使用してトークンフローを開始します。

3. トークンの検証：

4. 新しいトークンが取得されると、Tulipはそれを保存し、ユーザーが要求したコネクタ関数の実行に進みます。

   • 成功すると、データがTulipアプリのランタイムに提供されます。
   • 新しいトークンがOAuthエラーで失敗した場合、Tulipは処理を5回まで再試行し、そのたびにステップ1に戻ります。
   • 新しいトークンがその他のエラーで失敗すると、プレーヤーのランタイムにエラーが表示されます。

5. トークンがない場合の処理

6. 新しいトークンが提供されない場合、Tulip はプレーヤのユーザに認証を受けるよう促し、認証プロセス全体を開始します。

7. 完了すると、コネクタ関数が実行され、データが返されます。

リフレッシュ・トークンを実装することで、トークンの有効期限と更新をインテリジェントに管理し、ワークフローの中断を最小限に抑えることで、よりスムーズなユーザー・エクスペリエンスを実現します。

さらに読む

• Tulipコネクタホストの紹介
• コネクタのスナップショット
• OAuth2.0の説明