メインコンテンツまでスキップ

シークレット

シークレットを使用すると、Squid は API キー、パスワード、証明書などの機密データを管理するためのサポートを提供します。シークレット管理は Squid Console と Squid Client SDK の両方から行えます。​

プログラムによるシークレット管理は、API キーの自動ローテーション、パスワードの定期的な更新、サービスの動的な作成などに役立ちます。Squid Client SDK は、カスタムシークレットとアプリケーションの API キーの両方を管理する方法を提供します。

注意

Squid Client SDK からシークレットを管理するには、クライアントをアプリケーションの API キーで初期化する必要があります。これは apiKey オプションを使用して行えますが、ユーザー向けアプリケーションからは 決して 行わないでください。シークレット管理は、Squid Backend などの安全な環境でのみ実行してください。

シークレットは、データ漏えいおよび不正アクセスのリスクを最小化します。Squid のシークレットは、セキュリティが重要な多くの状況で役立ちます。たとえば以下のようなケースです:

  • API リクエストに API キーやその他の認証シークレットを安全に注入する
  • クライアントから直接かつ安全に API 呼び出しを有効化する
  • API キー検証の実装
  • scheduler を用いた API キーのローテーションの実装

カスタムシークレット​

シークレットは、クライアントが提供する標準的な CRUD（create, read, update, delete）操作で管理できます。API は次のように使用できます:

シークレットを取得する​

名前でシークレットにアクセスするには get メソッドを呼び出します。メソッドはシークレットエントリを返し、そこには value と、シークレットが lastUpdated された時刻（ミリ秒）が含まれます。シークレットが存在しない場合は undefined を返します。

const result = await squid.secrets.get('SECRET_NAME');
// {
//   key: 'SECRET_NAME',
//   value: 'your_value',
//   lastUpdated: 1692306991724
// }

すべてのシークレットを取得する​

すべてのシークレットの map を取得するには getAll メソッドを呼び出します。map 内の各エントリには value と、シークレットが lastUpdated された時刻（ミリ秒）が含まれます。

const result = await squid.secrets.getAll();
// {
//   'SECRET_NAME': {
//     key: 'SECRET_NAME',
//     value: 'your_value',
//     lastUpdated: 1692306991724
//   }
// }

シークレットを作成または更新する​

新しいシークレットを作成する、または既存のシークレットを更新するには、upsert 関数を使用し、シークレットの key と value をパラメータとして渡します。シークレットは作成または更新されます。呼び出しは作成または更新されたシークレットを返します。

const result = await squid.secrets.upsert('SECRET_NAME', 'your_new_value');
// {
//   key: 'SECRET_NAME',
//   value: 'your_new_value',
//   lastUpdated: 1692306991724
// }

複数のシークレットを一度に更新するには upsertMany メソッドを使用します。この関数は更新するシークレットの配列を受け取り、各シークレットは key と value 属性を持つオブジェクトです。

const result = await squid.secrets.upsertMany([
  { key: 'SECRET_NAME', value: 'your_new_value' },
  { key: 'OTHER_SECRET_NAME', value: 'your_other_value' },
]);
// [{
//   key: 'SECRET_NAME',
//   value: 'your_new_value',
//   lastUpdated: 1692306991724
// },
// {
//   key: 'OTHER_SECRET_NAME',
//   value: 'your_other_value',
//   lastUpdated: 1692306991724
// }]

シークレットを削除する​

シークレットを削除するには、削除したいシークレット名を指定して delete メソッドを呼び出します。

await squid.secrets.delete('SECRET_NAME');

複数のシークレットを一度に削除するには deleteMany メソッドを使用します。この関数は削除するシークレット名を含む文字列の配列を受け取ります。

const result = await squid.secrets.deleteMany(['SECRET_NAME', 'OTHER_SECRET_NAME']);

API キー​

Squid の API キーも squid.secrets 属性で管理できます。ただし、Squid が API キーの生成を行うため、API キーを作成または更新する際に value を渡すことはできません。

API キーを取得する​

名前で API キーにアクセスするには apiKeys.get メソッドを呼び出します。API キーが存在しない場合、このメソッドは unefined に解決される promise を返します。キーが存在する場合、このメソッドは key、value、およびシークレットが lastUpdated された時刻（ミリ秒）からなるシークレットエントリオブジェクトに解決される promise を返します。

const result = await squid.secrets.apiKeys.get('API_KEY_NAME');
// {
//   key: 'API_KEY_NAME',
//   value: 'a123b456-cd78-9e90-f123-gh45i678j901',
//   lastUpdated: 1692306991724
// }

すべての API キーを取得する​

すべての API キーの map を取得するには apiKeys.getAll メソッドを呼び出します。map 内の各エントリには value と、キーが lastUpdated された時刻（ミリ秒）が含まれます。

const result = await squid.secrets.apiKeys.getAll();
// {
//   'API_KEY_NAME': {
//     key: 'API_KEY_NAME',
//     value: 'a123b456-cd78-9e90-f123-gh45i678j901e',
//     lastUpdated: 1692306991724
//   }
// }

API キーを作成または更新する​

新しい API キーを作成する、または既存のキーをローテーションするには apiKeys.upsert メソッドを使用します。キー名をパラメータとして渡します。Squid が新しいキーを生成し、レスポンスでキーの value を返します。

const result = await squid.secrets.apiKeys.upsert('API_KEY_NAME');
// {
//   key: 'API_KEY_NAME',
//   value: 'a123b456-cd78-9e90-f123-gh45i678j901e',
//   lastUpdated: 1692306991724
// }

API キーを削除する​

API キーを削除するには、キー名を渡して delete メソッドを呼び出します。

await squid.secrets.apiKey.delete('API_KEY_NAME');

Squid backend におけるシークレット​

Squid backend では this.secrets を使って、シークレットを含むオブジェクトに直接アクセスできます。たとえば、'SECRET_NAME' というシークレットの値には次のようにアクセスできます:

Backend code
this.secrets['SECRET_NAME']; // 'your_value'

例: スケジュールに従って API Key をローテーションする​

シークレットと API キー管理は、scheduler や trigger といった Squid の backend 関数と組み合わせることで強力になります。次の例は、プログラムによるシークレット管理のユースケースを示しています。

@scheduler("rotate-api-key", CronExpression.EVERY_DAY_AT_MIDNIGHT)
async rotateApiKey() {
  const { lastUpdated } = await this.squid.secrets.apiKeys.get('MY_API_KEY');
  // If the key is over 30 days old
  if (lastUpdated < Date.now() - (30 * 86400000)) {
    await this.squid.secrets.apiKeys.upsert('MY_API_KEY')
  }
}

scheduler について詳しくは、scheduler のドキュメント を参照してください。