API認証

Retoolでは、ほぼすべての種類の認証をサポートしています。弊社は、すべての標準タイプの認証をサポートし、ネイティブにサポートしていない自社開発の認証をサポートするための拡張可能な方法を開発する企業と連携してきました。

静的な認証トークンを使用したり、エンド・ユーザーがアプリケーションにアクセスするたびに資格情報を入力するよう求める認証を作成したりできます。

このページでは、APIを認証する方法について説明します。途中で分からなくなった場合は、このページにあるインターコムまたはエディター内のヘルプ・アイコンでサポートにご連絡ください。

API認証

APIの認証の詳細を追加するには、リソース・ページに移動して(またはオンボード時にモーダルを使用して)、下部にある「Authentication」セクションまで下にスクロールします。

ここでは、ネイティブにサポートしているすべての認証タイプ、およびカスタムまたは複数ステップのフローを作成する「Custom Auth」がリストされます。

認証を追加するドロップダウン認証を追加するドロップダウン

認証を追加するドロップダウン

承認ベアラー・トークン

Retoolでは、ベアラー・トークン認証スキームを使用するAPIの追加が簡単です。リソース設定画面でグローバル・ヘッダーとしてこれを追加すると、リソースを使用するすべてのAPIリクエストで適切な認証ヘッダーが送信されます。

基本認証

基本認証スキームを有効にするには、AuthenticationドロップダウンでBasic Authを選択して、ユーザー名とパスワードを入力します。

OAuth 2.0

Retoolでは、OAuth 2.0認証スキームもサポートしています。前の例とは異なり、「Share OAuth2.0 credentials between users」オプションを有効にしなければ、認証の詳細はエンド・ユーザー間で共有されません

資格情報共有オプションが無効である場合、各エンド・ユーザーは、OAuth認証フローを介して認証することが必要になります。OAuth IDプロバイダーから返されるアクセス/リフレッシュ・トークンが暗号化され、Retoolでのユーザーの現在のセッションと関連付けられます。これによって、承認と認証をOAuth IDプロバイダーに委任できるようになります。

以下に、GoogleのOAuth 2.0 APIに接続するRetoolのサンプル構成を示します。注意点は、次のとおりです。

  • Authorization: Bearer OAUTH2_TOKENというヘッダーを追加しました。OAUTH2_TOKENは、実行時にアクセス・トークンに置き換わる、マジック・プレースホルダー文字列です。このマジック文字列をヘッダーまたはクエリーのURLパラメーターで使用することができます。
  • OAuthコールバックURLは静的で、変更することはできません。このURLを使用して、これをOAuth構成に指定する必要があります。
  • ログイン・テストURLを使用して、ユーザーが現在認証されているかどうかをテストします。RetoolではURLに対してGETリクエストを実行します。レスポンスが20xでない場合、モーダルを表示し、ユーザーにAPIに対して認証するよう求めます。

Retoolの同意画面

OAuth2フローを開始すると、ユーザーはRetoolの同意画面にリダイレクトされ、同意すると、IDプロバイダーの同意画面にリダイレクトされます。Retoolオンプレミスを実行している場合、「Skip Retool consent screen & attempt login」を切り替えると、特定のリソースに対してRetoolの同意画面を無効にすることができます。

これは、?prompt=none URLパラメーターを設定して承認リクエストを送信することと同じです。このリクエストでエラー(例えば、「user interaction required」)が返されると、Retoolは同意ベースのフローに戻ります。

IDプロバイダーに直接リダイレクトIDプロバイダーに直接リダイレクト

IDプロバイダーに直接リダイレクト

📘

OAUTH2_TOKENマジック文字列

上記のスクリーンショットでのOAUTH2_TOKEN文字列の使用方法によく注意してください。Retoolでは、実行時にその文字列をOAuthアクセス・トークンに置き換えます。このように、APIで認証するためにアクセス・トークンを使用する方法がRetoolに指示されます。

同様に、openidスコープが含まれていて、ユーザー間でのOAuth資格情報の共有が無効になっている場合、Oauth IDトークン用に置き換えるOAUTH2_ID_TOKENを使用できます。

CookieベースのAPI

Retoolでは、認証にCookieを使用するAPIもサポートしています。このシナリオでは、APIは、承認トークンを含むSet-Cookieヘッダーで応答することによりセッションを承認します。次に、APIでは、将来の認証されたすべてのリクエストがCookiesヘッダーで同じ承認トークンを送信することが必要になります。

RetoolではバックエンドですべてのHTTPリクエストに対してプロキシを実行しますが、Retoolは、有効期限などの属性も含めて、APIによって設定されたCookieをユーザーのブラウザーに転送することをサポートしています。Cookieは、ユーザーの現在のセッションのライフサイクルに関連付けられている、ユーザーのブラウザーのHTTPOnly Cookieに格納されます。ユーザーがAPIに対して実行する将来のすべてのリクエストには、同じCookieが追加されます。

これを構成するには、ユーザーのブラウザーに転送するCookieの名前をRetoolに指示します。OAuth 2.0 APIインテグレーションと同様に、URLを指定してユーザーの認証ステータスを確認することもできます。

これを構成したら、Retoolでログイン・ページの作成が必要になります。これによって、ユーザーに認証の詳細が要求され、ログイン・エンドポイントへのAPIリクエストが実行されます。ログインが成功すると、認証Cookieがレスポンスから解析され、ユーザーのセッションに転送されます。

二重のCookieの送信パターン

二重のCookieの送信パターンは、次のように、ヘッダーでCOOKIE_your_csrf_tokenを使用することで実装できます。

ドメインで事前に設定されたCookieの転送

📘

Retoolのオンプレミス・ユーザーのみ利用可能

Retoolを実行しているドメインで事前に設定されている特定のCookieを自動的に転送できます。例えば、Retoolがretool.yourdomain.comでホストされていて、yourdomain.comドメインで設定されているsomeCookie1およびsomeCookie2という名前のCookieを自動的に転送したいとします。

最初に、これらのCookieを環境変数で許可リストに追加する必要があります。複数のCookieの転送を許可する場合、次のように、これらをカンマ区切りの文字列として追加します。

FORWARDABLE_SAME_DOMAIN_COOKIES_ALLOWLIST=someCookie1,someCookie2

次に、これらのCookieを転送するリソースのリソース設定ページで、次のように、CookieをList of cookies to forwardセクションで追加します。

これで終了です。リクエストを実行すると、常にsomeCookie1someCookie2がこのリソースで自動的に転送されます。ヘッダーにどちらかのCookieを含める場合は、ここで説明されているCOOKIE_someCookie1パターンに従います。

AWS v4シグネチャ・ベースの認証

Amazonのv4シグネチャ署名プロセスを使用して、APIリクエストに署名することもできます。これを行うには、AWSリージョン、サービス・アカウント・キー、秘密鍵および自分のAWSサービスを指定する必要があります。

AWSサービスはAPIのサブドメインに対応します。例えば、 https://xyzabc.execute-api.us-east-1.amazonaws.com でホストされているサービスにリクエストを実行する場合、サービスはxyzabc.execute-apiである必要があります。

カスタムおよび複数ステップのAPIフロー

どちらのオプションも利用できるようになりませんか。問題ありません。カスタム認証に関するガイドを参照してください。