JavaScript SDK

Keeperシークレットマネージャー用Javascript SDKの詳細

ダウンロードとインストール

NPMによるインストール

npm install @keeper-security/secrets-manager-core

詳細については、https://www.npmjs.com/package/@keeper-security/secrets-manager-coreをご参照ください。

ソースコード

JavaScriptのソースコードは、GitHubリポジトリで入手できます。

SDKの使用

ストレージの初期化

トークンのみを使用して新しい構成 (後で使用するため) を生成する場合、トークンをバインドして config.jsonを完全に生成するために、少なくとも1回の読み取り操作が必要です。

シークレットを取得するには、まずマシンのローカルストレージを初期化する必要があります。

initializeStorage(storage:KeyValueStorage, clientKey:String? = null, hostName:String? = null)

パラメータ	型	必須	デフォルト	説明
storage	KeyValueStorage	はい		保存場所
clientKey	string	オプション	null	Keeperシークレットマネージャーに接続するためのトークン
hostName	string	オプション	null	シークレットを取得するサーバーの場所。 何も指定しない場合は、keepersecurity.com (米国) が使用されます

使用例

const { getSecrets, initializeStorage, localConfigStorage } = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {

    // ワンタイムトークンはストレージの初期化に一度だけ使用
    // 初回実行以降の呼び出しでは、ksm-config.jsonを使用
    const oneTimeToken = "<One Time Access Token>";
    
    const storage = localConfigStorage("ksm-config.json")
    
    await initializeStorage(storage, oneTimeToken)
    // トークンのみを使用して（後で使用するために）設定を生成するには
    // トークンをバインドするアクセス操作が少なくとも1回必要です
    // トークンをバインドするには、以下の呼び出しの行頭のコメントを外す
    // await getSecrets({storage: storage})
    
    const {records} = await getSecrets({storage: storage})
    console.log(records)

    const firstRecord = records[0]
    const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
    console.log(firstRecordPassword.value[0])
}

getKeeperRecords().finally()

シークレットの取得

getSecrets(options:SecretsManagerOptions, recordsFilter:List<String> = emptyList()):KeeperSecrets

パラメータ	型	必須	デフォルト	説明
storage	KeyValueStorage	はい		保存場所
recordsFilter	string[]	オプション	空のリスト	取得するレコードのUID

レスポンス

型: KeeperSecrets

すべてのKeeperのレコード、または指定したフィルタ条件に一致するレコードを含むオブジェクト

使用例

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

const storage = inMemoryStorage() // 初期化の例を参照
const secrets = await getSecrets({storage: storage})

タイトルでシークレットを取得

// 一致するレコードをすべて取得
getSecretsByTitle = async (options:SecretManagerOptions, recordTitle: string):Promise<KeeperRecord[]>

// 最初に一致したレコードだけを取得
getSecretByTitle = async (options:SecretManagerOptions, recordTitle: string):Promise<KeeperRecord>

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	事前に設定されたオプション
recordTitle	string	はい	検索するレコードタイトル

使用例

const {
    getSecretByTitle,
    localConfigStorage,
} = require('@keeper-security/secrets-manager-core')

const getKeeperRecord = async () => {
    const options = { storage: localConfigStorage("ksm-config.json") }
    const myCredential = await getSecretByTitle(options, "My Credential")
}

getKeeperRecord().finally()

シークレットから値を取得

パスワードを取得

パスワード取得

secret.data.fields.find(x => x.type === 'password')

用例

フィールドタイプはKeeperレコードタイプに基づきます。利用可能なフィールドの詳細な一覧については、コマンダーで record-type-info コマンドをご参照ください。

Keeper表記法を使用して他のフィールドを取得

値を取得

getValue(secrets:KeeperSecrets, query: string): any

用例

Keeper表記法の形式と機能については、Keeper表記法のページをご参照ください。

パラメータ	型	必須	デフォルト	説明
secrets	KeeperSecrets	はい		照会するシークレット
query	string	はい		Keeper表記法を使用したクエリ

戻り値

型: any

ドット記法のクエリで指定した位置にフィールド値がある場合はその値。ない場合は undefined。

TOTPコードを取得

TOTPコードを取得

getTotpCode(
    url: string,
    unixTimeSeconds?: number
): Promise<{
    code: string
    timeLeft: number
    period: number
} | null>

使用例

Keeper表記法の形式と機能については、Keeper表記法のページをご参照ください。

パラメータ	型	必須	デフォルト	説明
url	string	はい		TOTP Url

パラメータ	型	必須	デフォルト	説明
url	string	はい		TOTP URL
unixTimeSeconds	number	オプション	現在のタイムスタンプ	秒単位のUnixタイムスタンプ (テストや検証用)

• 表記法のクエリで指定するレコードUIDは、secrets パラメーターに渡したシークレットに含まれる必要があります。含まれない場合、クエリでは見つかりません。

戻り値

型: Promise<{code: string, timeLeft: number, period: number} | null>

次のプロパティを持つオブジェクト。

• code - TOTPコード (6〜8桁)

• timeLeft - コードが失効するまでの残り秒数

• period - TOTPの周期 (秒)。通常は30

TOTP URLが無効な場合や処理できない場合は null を返します。

シークレットを更新

レコードを更新するコマンドは、成功してもローカルのレコード情報 (特に更新後のレコードのリビジョン) が自動では更新されません。そのため、すでに更新済みのレコードに続けて更新を行うと、リビジョンの不一致で失敗します。各更新バッチの後に、更新したレコードをすべて再読み込みしてください。

シークレットの更新

updateSecret(options, record)

使用例

トランザクションによる更新

パラメータ	型	必須	デフォルト	説明
options	SecretManagerOptions	はい
record	KeeperRecord	はい

戻り値

型: Promise<void>

ランダムなパスワードを生成

パスワードを生成

generatePassword(length, lowercase, uppercase, digits, specialCharacters)

使用例

パラメータ	型	必須	デフォルト
length	int	オプション	64
lowercase	int	オプション	0
uppercase	int	オプション	0
digits	int	オプション	0
specialCharacters	int	オプション	0

各パラメーターは、それぞれの文字タイプを最低何文字含めるかを指定します。たとえば、uppercase は「大文字を最低何文字含めるか」を示します。

戻り値

型: String

ファイルのダウンロード

downloadFile(file:KeeperFile):ByteArray

パラメータ	型	必須	デフォルト	説明
file	KeeperFile	はい		ダウンロードするファイル

レスポンス

型: Promise<Uint8Array>

ダウンロード用のファイルのバイト列

サムネイルのダウンロード

downloadThumbnail(file:KeeperFile):ByteArray

パラメータ	型	必須	デフォルト	説明
file	KeeperFile	はい		ダウンロードするサムネイル付きファイル

レスポンス

型: Promise<Uint8Array>

ダウンロード用サムネイルのバイト列

ファイルのアップロード

ファイルのアップロード:

uploadFile = async (options:SecretManagerOptions, ownerRecord:KeeperRecord, file:KeeperFileUpload):Promise<string>

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	ストレージとクエリの設定
ownerRecord	KeeperRecord	はい	アップロードされたファイルを添付するレコード
file	KeeperFileUpload	はい	アップロードするファイル

Keeperファイルアップロードオブジェクトを作成:

type KeeperFileUpload = {
    name: string
    title: string
    type?: string
    data:Uint8Array
}

パラメータ	型	必須	説明
name	string	はい	アップロード後にKeeperに格納されるファイルの名前
title	string	はい	アップロード後にKeeperに格納されるファイルのタイトル
type	string	オプション	ファイルのデータのMIMEタイプ。何も指定しない場合は、「application/octet-stream」が使用されます
data	Uint8Array	はい	バイト型のファイルデータ

使用例

// ファイルを添付するレコードを取得
const {records} = await getSecrets({storage: storage}, ['XXX'])
const ownerRecord = records[0]

// アップロードするファイルデータを取得
const fileData = fs.readFileSync('./assets/my-file.json')

// 選択したレコードにファイルをアップロード
await uploadFile(options, ownerRecord, {
    name: 'my-file.json',
    title:'Sample File',
    type: 'application/json',
    data: fileData
})

シークレットの作成

要件

• 共有フォルダのUID

  • 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできること

  • ユーザーとシークレットマネージャーアプリケーションには編集権限が付与されていること

  • 共有フォルダには、少なくとも1つのレコードが存在すること

• 作成されたレコードとレコードのフィールドは正しい形式で設定されていること

  • 各レコードタイプのフィールド形式については、こちらのページをご参照ください

• TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます

• レコード作成後、添付ファイルは uploadFile でアップロードできます

レコードを作成

createSecret(options, folderUid, record)

パラメータ	型	必須	デフォルト
options	SecretManagerOptions	はい
folderUid	string	はい
record	JSON Object	はい

サブフォルダでレコードを作成

ログイン情報レコードの例

カスタムタイプの例

シークレットの削除

JavaScript KSM SDKでKeeperボルトのレコードを削除できます。

シークレットの削除

deleteSecret(smOptions, recordUids);

パラメータ	型	必須
smOptions	SecretManagerOptions	はい
recordUids	string[]	はい

使用例

キャッシュ

ネットワークへのアクセスが失われた際にシークレットへのアクセスも失うという事態を避けるため、JavaScript SDKでは、シークレットを暗号化されたファイルとしてローカルマシンにキャッシュすることができます。

SecretManagerOptions に queryFunction: cachingPostFunction を追加

使用例:

const options:SecretManagerOptions = {    
    storage: kvs,
    queryFunction: cachingPostFunction // `cachingPostFunction` をインポートする
}

フォルダ

フォルダは完全なCRUD (作成、読み取り、更新、削除操作) に対応しています。

フォルダの読み取り

フォルダの完全な階層構造をダウンロードします。

getFolders = async (options:SecretManagerOptions):Promise<KeeperFolder[]>

レスポンス

型: KeeperFolder[]

使用例

const storage = localConfigStorage("ksm-config.json")
const folders = await getFolders({storage: storage})

フォルダの作成

作成には CreateOptions とフォルダ名の指定が必要です。CreateOptions に含まれる folder UID パラメータは必須で、これは共有フォルダのUIDを指定します。sub-folder UID は任意で、省略された場合は、指定された共有フォルダの直下に通常のフォルダが新規作成されます。なお、sub-folder UID は必ずしも親の共有フォルダの直下である必要はなく、何階層も深い位置を指定することも可能です。

createFolder = async (options:SecretManagerOptions, createOptions:CreateOptions, folderName: string):Promise<string>

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	事前に設定されたオプション
createOptions	CreateOptions	はい	親およびサブフォルダのUID
folderName	string	はい	フォルダ名

type CreateOptions = {
    folderUid: string
    subFolderUid?: string
}

使用例

const storage = localConfigStorage("ksm-config.json")
const folderUid = await createFolder({storage: storage}, {folderUid: "[PARENT_SHARED_FOLDER_UID]"}, "new_folder")

フォルダの更新

フォルダのメタデータ (現在はフォルダ名のみ) を更新します。

updateFolder = async (options:SecretManagerOptions, folderUid: string, folderName: string):Promise<void>

パラメータ	型	必須	説明
options	SecretsManagerOptions	はい	事前に設定されたオプション
folderUid	string	はい	フォルダのUID
folderName	string	はい	新しいフォルダ名

使用例

const storage = localConfigStorage("ksm-config.json")
await updateFolder({storage: storage}, "[FOLDER_UID]", "new_folder_name")

フォルダの削除

フォルダのリストを削除します。空でないフォルダを削除するには、forceDeletionフラグを使用します。

forceDeletion を使用する際は、親フォルダとその子フォルダのUIDを同時に送信しないように注意してください。削除の順序によっては、エラーが発生する可能性があります (例: 親が先に削除され、その後で子フォルダを削除しようとした場合など)。UIDのリストが常にFIFO (先入れ先出し) 順に処理される保証はありません。

ボルトに存在しないフォルダのUIDやKSMアプリケーションで共有されていないフォルダのUIDはエラーになりません。

deleteFolder = async (options:SecretManagerOptions, folderUids: string[], forceDeletion?: boolean):Promise<SecretsManagerDeleteResponse>

パラメータ	型	必須	デフォルト	説明
options	SecretsManagerOptions	はい		事前に設定されたオプション
folderUids	string[]	はい		フォルダUIDリスト
forceDeletion	bool	いいえ	false	空でないフォルダを強制的に削除

使用例

const storage = localConfigStorage("ksm-config.json")
await deleteFolder({storage: storage}, ["[FOLDER_UID1]", "[FOLDER_UID2]"], true)

プロキシ対応

プロキシを使用するには、@keeper-security/secrets-manager-core に含まれる setCustomProxyAgent を使用して、プロキシエージェントをインストールおよび設定する必要があります。

使用例

const {
    getSecrets,
    initializeStorage,
    localConfigStorage,
    setCustomProxyAgent
} = require('@keeper-security/secrets-manager-core')
const { HttpsProxyAgent } = require('https-proxy-agent')

const getKeeperRecords = async () => {
    // プロキシのURLを設定
    setCustomProxyAgent(new HttpsProxyAgent('http://user:password@127.0.0.1:3128'))

    const storage = localConfigStorage("config.json")
    
    await initializeStorage(storage, 'US:EXAMPLE_ONE_TIME_TOKEN', 'keepersecurity.com')
    const {records} = await getSecrets({storage: storage})

    console.log(records)
}

setCustomProxyAgent は Node.js 環境でのみ動作し、ブラウザでは使用できません。