外部認証
サードパーティサービスコネクタ向けの OAuth2 トークンを管理
External Authentication モジュールは、Google Drive、Google Calendar、および その他の OAuth 対応コネクタ などのサードパーティサービスに対する OAuth2 認証フローを統一的に扱う方法を提供します。認可コード（authorization code）、アクセストークン（access token）、および自動トークンリフレッシュを管理し、ユーザーに安全でシームレスな認証体験を提供します。
概要
External Auth は、OAuth2 ベースのコネクタのトークンライフサイクルを処理します。
- 安全なトークン保存: トークンは暗号化され、ユーザーごとに安全に保存されます
- 自動リフレッシュ: アクセストークンは期限切れになると自動的にリフレッシュされます
- マルチユーザー対応: 各ユーザーのトークンは一意の識別子を用いて分離されます
- コネクタ非依存: OAuth2 準拠の任意のサービスで動作します
OAuth2 認証を理解する
OAuth2 の認証フローは、主に次の 3 ステップで構成されます。
- ユーザー認可: ユーザーをサードパーティの OAuth 同意（consent）画面に誘導し、アプリケーションを認可してもらいます。ユーザーが同意すると、認可コードが返されます。
- トークン交換: 認可コードを Squid に保存すると、Squid がそれをアクセストークンとリフレッシュトークンに交換します。
- 自動トークン管理: Squid はユーザーごとに一意の識別子（例: user id）を使ってトークンを安全に保存します。トークンは期限切れになると自動的にリフレッシュされます。
あなたが実装するのはステップ 1 で、ステップ 2 と 3 は Squid が処理します。
基本的な使い方
前提条件
External Auth を使用する前に、以下が必要です。
- OAuth2 を必要とするコネクタが Squid Console で設定済みであること（例: Google Drive、Google Calendar）
- サードパーティサービスからの OAuth2 資格情報（Client ID、Client Secret）
- 必要な権限に対する適切な OAuth2 scopes
- 各ユーザーの一意の識別子（例: user ID）
External Auth を初期化する
import { Squid } from '@squidcloud/client';
const squid = new Squid({
appId: 'your-app-id',
apiKey: 'your-api-key', // Required for External Auth
region: 'us-east-1.aws',
environmentId: 'prod',
});
// Get the external auth client for your connector
const externalAuth = squid.externalAuth('your_connector_id');
External Auth を使用するには、Squid を API key 付きで初期化する必要があります。これにより、トークンを安全に保存・取得するために必要な権限が付与されます。
サードパーティサービスから認可コード（Authorization Code）を取得する
ユーザーをサードパーティの OAuth2 同意画面に誘導し、必要な権限でアプリケーションを認可してもらいます。
-
OAuth2 パラメータを使用して認可 URL を構築します
- Client/App ID: OAuth provider から発行されたアプリケーションの識別子
- Redirect URI: 認可後にユーザーが戻る URL
- Response Type: 認可コードフローの場合は
codeに設定 - Scopes: アプリケーションに必要な権限
- Access Type: リフレッシュトークンを受け取るため
offlineに設定（provider により異なります）
-
ユーザーを認可 URL に誘導します。ユーザーは OAuth 同意画面で、要求された権限への承認を求められます
-
ユーザーが同意した後のリダイレクトを処理し、成功時に auth code を保存します。
OAuth2 provider によって要件が多少異なる場合があります。上記はあくまで例です。 正確な要件については、必ず各 provider の OAuth2 ドキュメントを参照してください。
認可コードは使い捨てで、通常は数分以内に期限切れになります。次のステップを使って速やかに交換してください。
認可コードを保存する
ユーザーが OAuth フローを完了し、認可コードを受け取ったら:
// Exchange authorization code for tokens and store them
const response = await externalAuth.saveAuthCode(
authCode, // The authorization code from the auth provider's callback
userId // User that the authorization code belongs to
);
console.log('Access token:', response.accessToken);
console.log('Expires at:', response.expirationTime);
saveAuthCode メソッドは次を行います:
- auth code を受け取り、外部 API と交換してアクセストークンとリフレッシュトークンを取得します
- トークンを Squid のストレージに安全に保存します
- アクセストークンと有効期限（expiration time）を返します
- 複数ユーザーがアカウントを接続できるよう、トークンを user id に紐づけます
- ユーザーごとに 1 回だけ呼び出す必要があります
アクセストークンを取得する
API 呼び出しに使用する有効なアクセストークンを取得します。Squid がトークンのリフレッシュを自動的に処理します。
const response = await externalAuth.getAccessToken(userId);
console.log('Access token:', response.accessToken);
console.log('Expires at:', response.expirationTime);
// Use the token for API calls
const apiResponse = await fetch('https://api.example.com/data', {
headers: {
'Authorization': `Bearer ${response.accessToken}`
}
});
getAccessToken メソッドは次を行います:
- コネクタ向けの有効なアクセストークンを取得します
- トークンが期限切れ、または期限切れが近い場合に自動的にリフレッシュします
ベストプラクティス
- ユーザー識別子の管理: アプリケーション全体で一貫した一意の識別子を使用してください
- HTTPS のみ: 本番環境では OAuth フローに必ず HTTPS を使用してください
- スコープの最小化: アプリケーションに必要な最小限の OAuth scopes のみを要求してください
- トークンのキャッシュ: キャッシュは External Auth に任せ、アプリケーション側でトークンを保存しないでください
- レート制限: トークン使用時はサードパーティ API の rate limits に注意してください
対応コネクタ
External Auth は現在、以下をサポートしています。
- Google Drive: ドキュメントおよびファイルへのアクセス
- Google Calendar: カレンダーイベント管理