OAuth 2.0

Prev Next

概要

Tulipの世界において、強力でありながらしばしば誤解されがちな認証プロトコル「OAuth 2.0」について、詳しく解説していきます。本記事では、その基礎を解き明かし、Tulipがサポートする認証フローを順を追って説明し、初期コネクタの設定方法をわかりやすく解説するとともに、スムーズに開始するための簡単なヒントをご紹介します。

Tulipにおけるリフレッシュトークンの処理、スコープおよびオーディエンスの管理、カスタムコネクタの設定については、「技術的な詳細」セクションを参照してください。

認証の種類

Tulipは、OAuth 2.0(サービスアカウント)、OAuth 2.0(ユーザー認証情報)、OAuth 2.0(クライアント認証情報)の3つのOAuth 2.0認証タイプをサポートしています。 主な違いは、ユーザー間で認証情報がどのように共有されるか、およびOAuth仕様に基づいて実行されるフローにあります。各OAuthフローの完全な一覧と説明は、こちらからご覧いただけます:https://frontegg.com/blog/oauth-flows。

Note

In older Tulip versions, OAuth2.0 (Service Account) was called OAuth2 (Admin), and OAuth2.0 (User Credentials) was called OAuth2 (Operator).

認可コードフロー:

  • **OAuth 2.0(サービスアカウント):**Tulip Player の全ユーザーに対して、コネクタのテスト時に提供された認証情報を使用します。組織内で認証情報を共有する場合に最適です。認証情報の有効期限が切れた場合は、管理者の再認証が必要となります。
  • **OAuth 2.0(ユーザー認証情報):**Tulip Player にログインしているユーザーに基づいて認証を区分します。ユーザーがまだ認証していない場合や認証が期限切れになった場合、そのユーザーは Tulip Player 内で OAuth フローを実行します。

クライアント認証情報フロー:

  • **OAuth 2.0(クライアント認証情報):**このグラントタイプは、Tulipがクライアントの認証情報(クライアントIDおよびクライアントシークレット)を使用して認証サーバーで認証を行い、アクセストークンを取得するために使用されます。通常、ユーザーに代わってではなく、クライアント自身に代わってリソースにアクセスする場合に用いられます。

詳細に入る前に、「環境」について理解を深め、コネクタホストとその機能の概要を把握しておくことをお勧めします。

OAuth 2.0 は、Tulip(クライアント)がお客様のビジネスシステムに対して自身の身元を証明するための仕組みとして機能します。

オーソリゼーションコードフロー

:::(警告) (警告)
ユーザー認証プロセスを完了するには、お使いのブラウザでポップアップが許可されている必要があります。connector に複数の環境が設定されている場合、認証中に各環境ごとに個別のポップアップウィンドウが開きます。

Chromeでポップアップが有効になっているか確認する方法:

  1. Chromeを開き、ウィンドウの右上隅にある3つのドットのメニューをクリックします。
  2. ドロップダウンメニューから [設定] を選択します。
  3. 画面を下にスクロールし、「プライバシーとセキュリティ」をクリックします。
  4. 「プライバシーとセキュリティ」セクションで、「サイト設定」をクリックします。
  5. 画面を下にスクロールし、「ポップアップとリダイレクト」をクリックします。
  6. トグルスイッチが「ポップアップを許可」に設定されていることを確認するか、ポップアップの表示を許可するサイトのリストにそのウェブサイトを手動で追加してください。

ポップアップがブロックされている場合、Chrome はポップアップがブロックされるたびにアドレスバーに小さなアイコンを表示します。このアイコンをクリックすると、Tulip からのポップアップをすばやく許可できます。
:::

アクセスはハンドシェイクを通じて許可され、Tulip は主に最も一般的な OAuth フローである「認証コードフロー」をサポートしています。このフローの概要を以下に簡潔にまとめます:

  1. ユーザーがコネクタを保存する前に「テスト」ボタンをクリックすることで、フローが開始されます。
  2. Tulipは、OAuthプロバイダーの認証サーバーと通信し、クライアントID、スコープ(アクセスを試みている対象)、その他の関連情報などの特定のパラメータを共有します。
  3. 認証サーバーは、以下に示すように、ユーザーにアクセス許可を求めるプロンプトを表示します:

  1. ユーザーの同意を得ると、認証サーバーは認証コードを生成し、認証ウィンドウを閉じます。
  2. Tulipは、この認証コードを用いて、トークンエンドポイントにアクセスし、認証コード、クライアントID、クライアントシークレット、およびその他のプロパティを指定して、安全にトークンをリクエストします。
  3. 認証コードの検証後、サーバーはトークン、および場合によってはリフレッシュトークンを返します。このトークンは、ユーザーが承認したリクエストに使用されます。
  4. Tulipは、提供されたトークンを認証情報として使用し、ユーザーに代わってリクエストを実行できるようになります。

実行の流れについては、以下の図を参照してください:Token Request

OAuth2 Graphic

クライアント認証情報フロー

クライアント認証情報フローは、主に2つの業務システム間の連携に使用されます。このフローは一度設定すれば、すべてのユーザーが共有して利用できます。

  1. ユーザーは、コネクタを保存する前に「テスト」ボタンをクリックして、このフローを開始します。
  2. Tulipは、OAuthプロバイダーの認証サーバーと通信し、クライアントID、スコープ(アクセスを試みている対象)、およびその他の関連情報などの特定のパラメータを共有します。
  3. 認証サーバーは、クライアントIDとクライアントシークレットが正確であることを前提として、アクセストークンを返します。オプションで、リフレッシュトークンが返される場合もあります。このトークンは、ユーザーによって承認されたリクエストに使用されます。
  4. これにより、Tulipは提供されたトークンを認証情報として使用し、ユーザーに代わってリクエストを実行できるようになります。

Client Credentials Flow

OAuthの設定

On-Prem Services

The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors.

image.png

認証コード URL

これは、認証コードフローのステップ2でTulipがアクセスするURLです。OAuthプロバイダーのAPIドキュメントに記載されており、通常は/authまたは/authorizeで終わります。

注:このフィールドは、クライアント認証情報(Client Credentials)では表示されません。

アクセストークン URL

認証サーバーからの応答後、認証用のトークンを取得するためにアクセス トークン URL へのリクエストが行われます。通常、URL は/token で終わります。

クライアント ID およびクライアントシークレット

OAuthプロバイダーのUIで生成されるクライアントIDは、認証コードの初期リクエストとともに送信されます。クライアントIDとクライアントシークレットは、すべてのトークンリクエストに添付されます。

デフォルトの有効期限(秒)

このフィールドは、有効期限が明示的に指定されていない場合、またはexpires_inフィールド以外の別の仕組みを通じて定義されていない場合に、トークンが更新されるまでのデフォルトの時間(秒単位)を指定します。

オーディエンスとスコープ

オーディエンスは、ユーザーがアクセスを求める特定の資産を指定し、スコープはこれらの資産に対して行いたい操作を定義します。これらはいずれも、ステップ2の認証コードリクエストの際に伝達されます。

追加オプション

  • **トークンリクエストデータを JSON 形式で送信:**トークン URL に送信されるリクエストのエンコード形式を変更します。特定の統合で必要な場合に有効にしてください。
  • **更新リクエストに認証ヘッダーを送信:**有効にすると、更新リクエストに追加のヘッダーが追加されます。
  • **ユーザーの同意プロンプトをスキップ:**認証コードリクエストの「*prompt」*属性を制御します。「無効」に設定すると「consent」に設定され、「有効」に設定すると「login」に設定され、表示するログイン画面をOAuthプロバイダーが決定できるようになります。
Note

For some integrations, exclude or set the prompt attribute to none. Reach out to support@tulip.co for further functionality.

技術的な詳細

ここでは、Tulipがサポートする機能の詳細と、コネクタ認証におけるOAuthの統合方法について説明します。

NOTE

The Client Credentials flow differs some from the authorization code flow. Steps 1 and 2 are not relevant for the Client Credential flow.

Tulipの認証コードフロー

On-Prem Services

The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors

Tulipは、コネクタのテストやアプリケーション内でのコネクタ関数の実行時に、認証プロセスを開始します。

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

Tulipアプリケーションは、response_type(オーソリゼーションコードフローの場合は「code」に設定)、 client_id(コネクタ UI で割り当てられたもの)、redirect_uri(Tulip によって事前定義されたもの)、scope および audience(UI で設定されたもの)、state(クロスサイトリクエストフォージェリ(CSRF)攻撃を防ぐためのランダムな文字列)などの特定のパラメータを添えて、ユーザーを認証サーバー(AS)にリダイレクトします。

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

2. ユーザーによる同意の付与

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

:::(警告) (注)
特定のconnector の設定において、「ユーザー同意プロンプトをスキップ」コントロールを使用すると、認証リクエストのprompt属性を制御できます。このコントロールを無効にすると、値としてconsentが使用され、有効にするとloginが使用されます。

prompt属性に追加の値が必要な場合は、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、および認証コードを含めます。

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


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": "SCOPE"}`

:::(Warning) (Services Not Using `expires_in`)
  
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.  
:::

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

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

**APIリクエストの例:**`GET /api/resourceAuthorization: Bearer ACCESS_TOKEN`

## リフレッシュトークンを用いたトークンの有効期限管理

認証サーバーは通常、アクセスを管理するためにトークンの有効期限を設定しており、その有効期限は連携するシステムによって異なります。しかし、有効期限が短いトークンは、絶え間ないユーザー認証がTulipアプリケーションのユーザー体験を損なうため、課題となります。

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

### Tulipはトークンの更新をどのように管理するのでしょうか?

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

![Token Refresh Flow](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/image%28399%29.png)

**1. 有効期限の検出:** - Tulipは、認証フローの[ステップ5](/r230/docs/oauth20-configuration-and-technical-details#5-access-token-response)で受け取った`expires_in属性`に基づいて、有効期限が切れたトークンを特定します。

:::(Warning) (Services Not Using `expires_in`)
  
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.  
:::

**2. トークンフローの試行:** - Tulipは、初期の認証フローで使用されたグラントタイプに代わって、`refresh_token`グラントタイプを使用してトークンフローを開始します。

**3. トークンの検証:** - 新しいトークンを取得できた場合、Tulipはそれを保存し、ユーザーがリクエストしたconnector function の実行に進みます。 - 成功した場合、データがTulipアプリランタイムに提供されます。 - 新しいトークンの取得が OAuth エラーにより失敗した場合、Tulip はこのプロセスを最大 5 回まで再試行し、その都度ステップ 1 に戻ります。 - 新しいトークンの取得がその他のエラーにより失敗した場合、プレイヤーランタイムにエラーが表示されます。

**4. トークン未提供時の処理:** - 新しいトークンが提供されない場合、Tulipはプレイヤー内でユーザーに認証を行うよう促し、認証プロセス全体を開始します。 - 完了後、connector function が実行され、データが返されます。

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

---

お探しの情報は見つかりましたか?

[community.tulip.co](https://community.tulip.co/?utm_source=intercom&utm_medium=article-link&utm_campaign=all)にアクセスして、質問を投稿したり、他のユーザーが同様の質問を投稿していないか確認することもできます!