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

シークレット

シークレットを使うことで、SquidはAPI keys、passwords、certificatesなどの機密データの管理をサポートします。シークレット管理は、Squid ConsoleおよびSquid Client SDKの両方から実施できます。​

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

注意

Squid Client SDKからシークレットを管理するには、クライアントをアプリケーションのAPI keyで初期化する必要があります。これは apiKey オプションを使用して行うことができ、決して ユーザーフェイシングなアプリケーションから実施すべきではありません。シークレット管理は、Squid Backendのような安全な環境でのみ行うべきです。

シークレットは、データ漏洩や不正アクセスのリスクを最小限に抑えます。Squidシークレットは、以下のようなセキュリティが重要な状況で有用です：

  • APIリクエストに対して安全にAPI keysやその他の認証シークレットを注入する
  • クライアントから直接かつ安全にAPIコールを有効にする
  • API keyの検証を実装する
  • schedulerを使用してAPI keyのローテーションを実装する

カスタムシークレット​

シークレットは、クライアントが提供する標準の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
// }

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

すべてのシークレットのマップを取得するには、getAll メソッドを呼び出します。マップの各エントリは、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 keys​

Squid API keysも squid.secrets 属性を使って管理できます。ただし、SquidがAPI keysの生成を行うため、API keyの作成や更新の際に値を渡すことはできません。

API keyの取得​

名前でAPI keyにアクセスするには、apiKeys.get メソッドを呼び出します。API keyが存在しない場合、このメソッドは undefined に解決する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 keyの取得​

すべてのAPI keyのマップを取得するには、apiKeys.getAll メソッドを呼び出します。マップの各エントリは、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 keyの作成または更新​

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

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

API keyの削除​

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

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

Squidバックエンドにおけるシークレット​

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

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

例: スケジュールに基づくAPI keyのローテーション​

シークレットおよびAPI keyの管理は、Squidのバックエンド機能（schedulersやtriggers）と組み合わせることで強力になります。以下の例は、プログラムによるシークレット管理のユースケースを示しています。

@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')
  }
}

スケジューラーについて詳しく知りたい場合は、documentation on schedulers をご覧ください。