📘

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

Retoolでは、ほとんどのOpenIDプロバイダー(Auth0、Azure ADなど)によるSSOの設定がサポートされています。さらに、Retoolでは、他のAPIコールでの、SSOプロセスによって取得した認証トークンの再使用もサポートされています。

シングル・サインオンの設定

RetoolのOpenID統合では認証コード・フローが利用されます。Retoolでは、少なくとも、IDトークンまたはアクセス・トークンのどちらかが、認証するユーザーの電子メールを含むことになるJWTであると想定されています。

設定を始める前に、以下の情報が必要になります。

• 自分のアプリケーションのクライアントID
• 自分のアプリケーションのクライアント・シークレット
• Retoolに付与するスコープのリスト
• 自分のOpenIDプロバイダーの「認証URL」
• 自分のOpenIDプロバイダーの「トークンURL」

また、自分のSSOプロバイダーによってIDトークンまたはアクセス・トークンがどのように書式設定されるかを確認することもできます。Retoolでは、IDトークンおよびアクセス・トークンを、それらがJWTであるかのようにデコードしようとします。ユーザーの身元情報と一致する、デコードされたJWTのパスをRetoolに提供する必要があります。

最後に、自分のアプリケーションのコールバックURLとして https://your.retool.instance/oauth2sso/callback を追加できます。

例を使った手順の説明: Google

https://retool.foocorp.com で実行されているRetoolのインスタンス用に、Auth0によるSSOを設定する必要があるとします。

1. GoogleのOAuthクライアントIDを新規作成します。

2. OAuth同意画面を構成するよう求められる場合があります。それを求められたら、「Internal」を選択します。

3. アプリケーションをWebアプリケーションとして、正しいリダイレクトURIで構成します。

4. 自分のクライアントIDとクライアント・シークレットを取得します。

5. この情報を取得し、それらをRetool用の環境変数に変換します。

SSO統合をどのように構成するか、例を以下に示します。

CUSTOM_OAUTH2_SSO_CLIENT_ID=22222222222-dq62o6pidgmgrem34fb07klc8qa1308t.apps.googleusercontent.com
CUSTOM_OAUTH2_SSO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
CUSTOM_OAUTH2_SSO_SCOPES=openid email profile https://www.googleapis.com/auth/userinfo.profile
CUSTOM_OAUTH2_SSO_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent
CUSTOM_OAUTH2_SSO_TOKEN_URL=https://oauth2.googleapis.com/token
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY=idToken.email
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=45

📘

標準外のいくつかのオプション

Googleには、リフレッシュ・トークンの取得のためにURLパラメーターaccess_type=offlineおよびprompt=consentが必要になります。これは、CUSTOM_OAUTH2_SSO_AUTH_URL変数でURLにそれら両方が含まれるためです。

また、Googleのトークンは1時間後に失効します。デフォルトでは、トークンは、2時間以上経過するとリフレッシュされます。このため、トークンをより頻繁にリフレッシュするために、CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES変数を45に設定しました。

例を使った手順の説明: Auth0

https://retool.foocorp.com で実行されているRetoolのインスタンス用に、Auth0によるSSOを設定する必要があるとします。

1. 自分のクライアントIDとクライアント・シークレットを取得します。

2. 自分のOAuth Authorization URLとOAuth Token URLを見つけます。

3. Retoolを自分のコールバックURLに追加します。

4. IDトークンのサンプルを入手し、どのようなものかを確認します。

例えば、Auth0では、IDトークンは次のようなものになります。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnaXZlbl9uYW1lIjoiRm9vIiwiZmFtaWx5X25hbWUiOiJCYXIiLCJuaWNrbmFtZSI6ImZvb2JhciIsIm5hbWUiOiJGb28gQmFyIiwicGljdHVyZSI6Imh0dHBzOi8vZm9vLmJhciIsImxvY2FsZSI6ImVuIiwidXBkYXRlZF9hdCI6IjIwMjAtMDktMjVUMDY6NTk6MzAuMjA4WiIsImVtYWlsIjoiZm9vYmFyQGZvb2NvcnAuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOi8vcmV0b29sLmF1dGgwLmNvbS8iLCJzdWIiOiJnb29nbGUtb2F1dGgyfDExMTExMTExMTExMTExIiwiYXVkIjoiWW91ckNsaWVudElEIiwiaWF0IjoxNjAxMDE3MTcwLCJleHAiOjE2MDEzNTMxNzB9.15ZdZH2R06JuCcI_rDoz55h8QIh4xCQlQWAnWcf72hg

デコードした場合は、次のようになります。

{
  "given_name": "Foo",
  "family_name": "Bar",
  "nickname": "foobar",
  "name": "Foo Bar",
  "picture": "https://foo.bar",
  "locale": "en",
  "updated_at": "2020-09-25T06:59:30.208Z",
  "email": "[email protected]",
  "email_verified": true,
  "iss": "https://retool.auth0.com/",
  "sub": "google-oauth2|11111111111111",
  "aud": "YourClientID",
  "iat": 1601017170,
  "exp": 1601353170
}

ここでは、emailフィールドはユーザーの識別に使用するものであり、given_nameとfamily_nameは、ユーザーの名と姓に相当します。

5. この情報を取得し、それらをRetool用の環境変数に変換します。

Auth0アプリケーションをどのように構成するか、例を以下に示します。

CUSTOM_OAUTH2_SSO_CLIENT_ID = yypLZ44LxEz0XlQZBu5k2Nq9XsdOv4f5 
CUSTOM_OAUTH2_SSO_CLIENT_SECRET = xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
CUSTOM_OAUTH2_SSO_SCOPES = openid email profile offline_access 
CUSTOM_OAUTH2_SSO_AUTH_URL = https://retool.auth0.com/authorize 
CUSTOM_OAUTH2_SSO_TOKEN_URL = https://retool.auth0.com/oauth/token 
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY = idToken.email 
CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY = idToken.given_name 
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY = idToken.family_name

必要な場合は、CUSTOM_OAUTH2_SSO_AUDIENCE環境変数を使用してカスタム・オーディエンスを指定することもできます。

6. それらの環境変数でRetoolコンテナーを再起動します。これで、SSOの設定が完了しました。

7. (オプション)管理者である場合、ユーザーを手動でプロビジョニングしたくない場合は、Organization settings -> Advancedで、ジャストインタイム(JIT)ユーザー・プロビジョニングを有効にすることができます。

8. (オプション)ユーザーにOauth 2.0認証画面によるプロンプトが自動的に表示されるようにする場合は、環境変数TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=trueを設定します。

ロール・マッピング

環境変数を使用して、OpenIDレスポンスから返されたロールを、Retoolのアクセス許可グループにマップすることができます。

devopsロールとsupportロールを、Retoolの特定のアクセス許可グループにマップする例を以下に示します。

CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=roles_key_in_your_JWT
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

ロール・マッピングの仕組みの例

Oktaグループ要求でロール・マッピングを使用する方法のガイド

1. 従来のOkta管理UIの使用に切り替えます。

2. Securityナビゲーション・ドロップダウンからAPIを選択して、APIダッシュボードに移動します。

3. 鉛筆のアイコンをクリックして、Retool統合先の認証サーバーを編集します。

4. Scopesタブを選択し、「Add Scopes」を押します。

5. 新しいスコープについてのフォームにすべて入力します。

6. Claimsタブに移動し、Add Claimを押します。

7. Add Claimフォームにすべて入力します。

「Filter」オプションには、好きな値を指定できます。このスクリーンショットでは、名前が「Retool」で始まるすべてのグループを含めています。Oktaの「Starts with」フィルターでは大文字と小文字が区別されることを覚えておいてください。

8. 自分のSSO構成を変更します。

groupsスコープをCUSTOM_OAUTH2_SSO_SCOPES環境変数に追加します。

CUSTOM_OAUTH2_SSO_SCOPES=openid email profile offline_access groups

そのグループをidTokenで読み取リ可能であると指定します。

CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups

追加で行いたい再マッピングがあれば、それを指定します。例えば、次のように、「Retool devops」グループのメンバーをRetool内のadminにもしたい場合です。

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=Retool devops -> admin

リソースで以下の構文を使用して、これらのトークンを参照できます。

%USER_OAUTH2_ACCESS_TOKEN%は、認証フローで取得したアクセス・トークンに置き換えられます
%USER_OAUTH2_ID_TOKEN%は、認証フローで取得したIDトークンに置き換えられます

9. テストしましょう。

別のユーザーとしてログインし、アクセス許可が自動的に正しく更新されたかどうかを確認してみてください。

リソースでの認証フローから取得したJWTの使用

この統合を使用する利点の1つは、これによって、SSOプロセスで取得したトークンを、Retoolからバックエンド・サービスへのAPIコールで再使用できるようになることです。

以下に、これらの変数を使用してヘッダーを設定する方法の例を示します。

👍

トークンのリフレッシュ

自分のOpenIDプロバイダーから最初のログイン・フローでrefresh tokenが返された場合、デフォルトでは、Retoolによって自動的にそれが使用されて2時間ごとにアクセス・トークンとIDトークンがリフレッシュされます。CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES環境変数を使用して、カスタムのリフレッシュ時間を設定できます。