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

秘密

シークレットを使用すると、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
// }

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

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

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

シークレットの作成または更新​

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

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 キーの作成または更新時に値を渡すことはできません。

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 キーのマップを取得するには、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 キーの作成または更新​

新しい API キーを作成するか、既存の API キーをローテーションするには、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 キーの削除​

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 キーのローテーション​

シークレットおよび API キーの管理は、schedulers や triggers などの 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')
  }
}

schedulers について詳しくは、documentation on schedulers をご覧ください。