認証を追加する

Squid はさまざまな認証プロバイダーと統合できます。それらを Squid に接続することで、ユーザーの操作を認可し、プロジェクトにセキュリティを追加できます。

なぜ認証を使うのか

ほとんどのアプリケーションでは、ユーザーが誰であるかを把握し、各ユーザーが何をできるかを制御する必要があります。Squid は既存の認証プロバイダーに接続するため、認証システムをゼロから構築することなく、ユーザーの本人確認とアクセス制御の強制を行えます。

概要

Squid はトークンを発行しません。代わりに、認証プロバイダーがトークンを発行し、クライアントがそれを Squid に渡し、Squid が検証して、バックエンドコードで認証情報を利用できるようにします。

Squid は 2 つの認証方法をサポートします:

• Bearer tokens（ユーザー認証）: 認証プロバイダーがユーザーごとに JWT を発行します。クライアントは Squid へのすべてのリクエストにこのトークンを付与します。Squid はトークンを検証し、ユーザー詳細（ユーザー ID、有効期限、カスタム属性）を抽出します。どのユーザーがリクエストしているかを把握する必要がある機能に使用します。
• API keys（サーバー間認証）: ユーザー識別情報なしでアクセスを許可する共有キーです。バックエンド間通信、管理スクリプト、ユーザー識別が不要な自動プロセスに使用します。

サポートされているプロバイダー

Squid は以下の認証プロバイダーをサポートします:

Provider	Description	Docs
Auth0	OpenID Connect provider	Auth0 セットアップ
AWS Cognito	AWS user pool service	Cognito セットアップ
Okta	Enterprise identity platform	Okta セットアップ
Keycloak	Open-source identity management	Keycloak セットアップ
Firebase Auth	Google Firebase auth	Firebase セットアップ
Descope	No-code CIAM platform	Descope セットアップ
JWT RSA	Custom RSA-signed JWTs	JWT RSA セットアップ

Note

上記のプロバイダーの多くは OpenID Connect（OIDC）プロトコルを使用します。これは OAuth 2.0 の上に構築されたアイデンティティ層で、アプリケーションがユーザーの本人確認を行い、プロフィール情報を取得する方法を標準化します。OIDC を理解することで、プロバイダーを正しく設定し、トークン関連の問題を切り分けるのに役立ちます。詳しくは こちら を参照してください。

クイックスタート

前提条件

• Squid アプリケーション（backend と client）
• 上記のサポートされている認証プロバイダーのいずれかのアカウント

Step 1: Squid Console で auth connector を追加する

Squid Console でアプリケーションに移動し、アプリケーション概要の Add auth provider をクリックします。使用する connector を選択し、必要な設定項目を入力します。

プロバイダー固有の設定詳細は、上の Supported providers 表にリンクされている各プロバイダーページを参照してください。

Step 2: クライアントを設定する

Console で connector を設定したら、すべてのリクエストに認証トークンを付与して送信するよう Squid クライアントを設定します:

Client code

import { Squid, SquidAuthProvider } from '@squidcloud/client';

const squid = new Squid({ ... });

const authProvider: SquidAuthProvider = {
  // Must match the connector ID you set in the Squid Console
  integrationId: 'your_auth_connector_id',
  getToken: () => {
    // Return the token from your auth provider (e.g., Auth0, Firebase, Cognito)
    return yourAuthLibrary.getAccessToken();
  },
};

squid.setAuthProvider(authProvider);

Step 3: バックエンドで auth を使う

auth provider を設定すると、バックエンドへのすべてのリクエストに検証済みトークンが含まれます。どのバックエンドサービスメソッドでも、認証済みユーザーの詳細にアクセスできます:

Backend code

import { executable, SquidService } from '@squidcloud/backend';

class MyService extends SquidService {
  @executable()
  getProfile(): { userId: string } | null {
    const userAuth = this.getUserAuth();
    if (!userAuth) {
      return null;
    }
    return { userId: userAuth.userId };
  }
}

クライアント側の設定

SquidAuthProvider インターフェース

SquidAuthProvider インターフェースは、Squid がクライアントから認証トークンを取得する方法を定義します:

interface SquidAuthProvider {
  /** Must match the connector ID configured in the Squid Console. */
  integrationId: string;

  /**
   * Returns a valid access token, or undefined if there is no active session.
   * Called by Squid every time the client makes a request to the backend.
   * Can be synchronous or asynchronous.
   */
  getToken(): Promise<string | undefined> | string | undefined;
}

• integrationId - Squid Console で設定した integration ID と完全に一致する必要があります。
• getToken() - 各リクエストごとに呼び出されます。string、undefined、またはそれらに解決される Promise を返せます。undefined が返されると、リクエストには認可情報が送信されません。

auth provider は Squid のコンストラクターオプションで設定するか、setAuthProvider を呼び出して設定できます:

Client code

// Option 1: Set in the constructor
const squid = new Squid({
  appId: 'your_app_id',
  region: 'us-east-1',
  authProvider: {
    integrationId: 'auth0',
    getToken: () => getAccessToken(),
  },
});

// Option 2: Set after initialization
squid.setAuthProvider({
  integrationId: 'auth0',
  getToken: () => getAccessToken(),
});

トークンのキャッシュ

Squid はリクエストごとに getToken() を呼び出すため、トークンをキャッシュし、有効期限が近づいたときにのみ更新してください:

Client code

let cachedToken: string | undefined;
let tokenExpiry = 0;

const authProvider: SquidAuthProvider = {
  integrationId: 'auth0',
  getToken: async () => {
    const now = Date.now();
    // Renew the token 60 seconds before it expires
    if (!cachedToken || now >= tokenExpiry - 60_000) {
      const result = await yourAuthLibrary.getAccessToken();
      cachedToken = result.token;
      tokenExpiry = result.expiresAt;
    }
    return cachedToken;
  },
};

API key 認証

API key 認証は、バックエンド間通信、管理操作、またはユーザー識別が不要な自動スクリプトで使用します。

Squid のコンストラクターオプションで API key を渡します:

Client code

import { Squid } from '@squidcloud/client';

const squid = new Squid({
  appId: 'your_app_id',
  region: 'us-east-1',
  apiKey: 'your_api_key',
});

API key 認証では userId は提供されません。個々のユーザーを識別する必要がない場合にのみ使用してください。

Squid API key は Squid Console の Application タブから確認または再作成できます。

バックエンドで auth を使う

Auth ヘルパーメソッド

SquidService は、バックエンドコードで認証を扱うために次のメソッドを提供します:

Method	Returns	Description
isAuthenticated()	boolean	リクエストに有効な auth（ユーザートークンまたは API key）がある場合に true を返します
assertIsAuthenticated()	void	リクエストが認証されていない場合に UNAUTHORIZED をスローします
getUserAuth()	AuthWithBearer | undefined	リクエストが Bearer token を使用しているときにユーザー認証詳細を返します
getApiKeyAuth()	AuthWithApiKey | undefined	リクエストが API key を使用しているときに API key の詳細を返します

Auth 型の形（shape）

リクエストが Bearer token（ユーザー認証）を使用する場合、getUserAuth() は AuthWithBearer オブジェクトを返します:

interface AuthWithBearer {
  type: 'Bearer';
  /** The unique identifier of the authenticated user. */
  userId: string;
  /** The expiration timestamp of the token, in seconds. */
  expiration: number;
  /** Additional attributes associated with the token. */
  attributes: Record<string, any>;
  /** The raw JWT token string, if available. */
  jwt?: string;
}

リクエストが API key を使用する場合、getApiKeyAuth() は AuthWithApiKey オブジェクトを返します:

interface AuthWithApiKey {
  type: 'ApiKey';
  /** The API key string used for authentication. */
  apiKey: string;
}

リクエストコンテキスト

すべてのバックエンドメソッドは this.context にアクセスでき、現在のリクエストに関する情報を含む RunContext オブジェクトを返します:

interface RunContext {
  /** Your application ID. */
  appId: string;
  /**
   * The ID of the client that initiated this request. Only available for
   * client-initiated requests (not triggers, schedulers, or webhooks).
   */
  clientId?: string;
  /** The IP address of the client that initiated this request. */
  sourceIp?: string;
  /** The headers of the request. Header keys are lowercase. */
  headers?: Record<string, any>;
}

例: 認証済みバックエンドメソッド

Backend code

import { executable, SquidService } from '@squidcloud/backend';

class UserService extends SquidService {
  @executable()
  getUserDashboard(): { userId: string; attributes: Record<string, any> } {
    // Throws UNAUTHORIZED if no valid auth is present
    this.assertIsAuthenticated();

    const userAuth = this.getUserAuth();
    if (!userAuth) {
      throw new Error('This endpoint requires user authentication, not an API key');
    }

    return {
      userId: userAuth.userId,
      attributes: userAuth.attributes,
    };
  }
}

auth をセキュリティルールに接続する

認証データは Squid のセキュリティデコレーター（@secureDatabase、@secureCollection など）に直接渡されます。セキュリティルールは、上で説明した同じ認証方法を使用してデータや API へのアクセスを制御します。

たとえば、コレクションに対するすべての操作で認証を必須にできます:

Backend code

import { secureCollection, SquidService } from '@squidcloud/backend';

class SecurityService extends SquidService {
  @secureCollection('users', 'read')
  secureUsersRead(): boolean {
    return this.isAuthenticated();
  }
}

セキュリティデコレーターとパターンの網羅的な内容は、Security rules documentation を参照してください。ロールベースのアクセスパターンについては、RBAC documentation を参照してください。

エラーハンドリング

認証に失敗すると、Squid は 401 UNAUTHORIZED レスポンスを返します。よくある原因は次のとおりです:

• 期限切れトークン: getToken() が返すトークンが有効期限を過ぎています。Token caching セクションに示したように、更新を伴うトークンキャッシュを実装してください。
• integration ID の不一致: SquidAuthProvider の integrationId が、Squid Console で設定した integration ID と一致していません。両方の値が完全一致していることを確認してください。
• auth provider のセットアップ不足: Squid Console に auth connector が追加されていない、または設定が誤っています（ドメイン、client ID などが間違っている）。
• トークンが返されない: getToken() が undefined を返すため、リクエストに auth 情報が送信されません。認証付きリクエストを行う前に、ユーザーがサインインしていることを確認してください。

認証問題をデバッグするには、次を確認してください:

1. connector が Squid Console で正しく設定されている。
2. setAuthProvider に渡している integrationId が Console の integration ID と完全一致している。
3. getToken() が有効で期限切れではないトークンを返している。

ベストプラクティス

• getToken() でトークンをキャッシュし、有効期限の少し前に更新して、認証プロバイダーへの不要な往復を避けてください。
• セキュリティルールでは常に isAuthenticated() を確認し、任意のリソースへのアクセスを許可する前提条件（ベースライン）として使用してください。
• ユーザー向け機能には Bearer tokens を使用し、バックエンドサービスやスクリプトには API keys を使用してください。
• データベース、API、ストレージ、キューなど、すべてのエントリポイントを保護してください。保護されていないエントリポイントは auth チェックを迂回します。
• assertIsAuthenticated() を使用して、手動でチェックしてスローする代わりに、明確なエラーで素早く失敗させてください。