Python SDK

Keeperシークレットマネージャー向けPython SDKの詳細情報

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

PIPによるインストール

pip3 install -U keeper-secrets-manager-core

Pythonのバージョン: 3.9以降

詳細については、keeper-secrets-manager-core (PyPI)をご参照ください。

ソースコード

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

関連パッケージ

SDKの使用

初期化

トークンは、失敗した試行を含め、初回使用時に消費されます。初期化に失敗した場合、SDK (v17.3.0+) は不完全な構成ファイルを自動的に削除します (ファイルベースのストレージのみ)。KSMアプリケーションから新しいワンタイムトークンを生成して再試行してください。

初期化後、少なくとも1回のAPI呼び出し (例: get_secrets()) が必要です。これによりトークンの紐付けが完了し、構成ファイルに必要な内容が書き込まれます。2回目以降は、トークンなしで構成ファイルを直接使用できます。

SecretsManager(token, config)
# トークンの紐付けを完了するには、少なくとも1回のAPI呼び出しが必要です
get_secrets(uids=None)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
# 必須: トークンの紐付けを完了し、構成ファイルを生成します
secrets_manager.get_secrets()

パラメータ

型

必須

デフォルト

説明

token

str

オプション

None

ワンタイムアクセストークン。初回実行時にアプリケーションを紐付けるために必要。構成が紐付け済みの場合は省略

config

KeyValueStorage

オプション

FileKeyValueStorage()

ストレージバックエンド。未指定の場合、現在のディレクトリの client-config.json がデフォルト

hostname

str

オプション

None

サーバーホスト名の上書き。リージョンプレフィックスなしのトークンを使用する場合は必須

verify_ssl_certs

bool

オプション

True

送信リクエスト時のSSL証明書検証

構成ファイルは、v17.1.0以降では安全な権限で自動的に作成されます (Unix系システムでは0600)。

バインディングライフサイクル

ワンタイムトークンは、クライアント作成時ではなく、最初の get_secrets() 呼び出し時に引き換えられます。構成を外部ストア (AWS Secrets Manager、Azure Key Vault など) に保存する場合は、バインド後に読み出してから永続化します。詳しくは、バインディングライフサイクルをご参照ください。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# 初回実行: ワンタイムトークンと永続ストレージパスを指定します。
sm = SecretsManager(
    token="US:BASE64_ONE_TIME_TOKEN",
    config=FileKeyValueStorage("ksm-config.json")
)
records = sm.get_secrets()  # ここでトークンが引き換えられ、ksm-config.json が更新されます。

# 以降の実行: トークンは省略します。保存済みの認証情報が直接使用されます。
sm = SecretsManager(config=FileKeyValueStorage("ksm-config.json"))
records = sm.get_secrets()

シークレットの取得

get_secrets(uids=None)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# すべてのレコードを取得
all_secrets = secrets_manager.get_secrets()

# すべてのレコードを出力
for secret in all_secrets:
    print(secret.dict)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# シークレットを出力
print(secret.dict)

パラメータ

型

必須

デフォルト

説明

uids

String[]

オプション

None

取得するレコードのUID

戻り値

型: Record[]

Keeperのすべてのレコード、または指定されたUIDを持つレコード。

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

パスワードを取得

Keeperシークレットマネージャーからシークレットを取得すると、このショートカットでそのシークレットのパスワードを取得します。

secret.field('password', single=True)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# レコードからパスワードを取得
my_secret_password = secret.field('password', single=True)

標準フィールドを取得

secret.field(field_type, value=None, single=False)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# シークレットのログインフィールドを取得
my_secret_login = secret.field("login", single=True)

パラメータ

型

必須

デフォルト

説明

field_type

String

はい

取得するフィールドタイプ

value

String またはString[]

オプション

None

指定すると、フィールドの値を指定値に設定

single

boolean

オプション

False

最初の値のみを返す

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

カスタムフィールドを取得

secret.custom_field(label, field_type=None, value=None, single=False)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# 標準テンプレートフィールドを取得
password = secret.field('password', single=True)

# APIキーなどのカスタムフィールドを取得
api_key = secret.custom_field('API Key', single=True)

パラメータ

型

必須

デフォルト

説明

label

String

はい

カスタムフィールドのラベル

field_type

String

オプション

None

取得するフィールドタイプ

value

StringまたはString[]

オプション

None

指定すると、フィールドの値を指定値に設定

single

boolean

オプション

False

最初の値のみを返す

カスタムフィールドとは、レコードタイプの定義に含まれていないが、ユーザーが追加できるフィールドのことです。

同じカスタムタイプの複数のフィールドを1つのレコードに表示することができます。これらのフィールドを区別するには、フィールドラベルが必要です。

戻り値

型: String または String[]

フィールドの1つまたは複数の値。 single=Trueオプションを指定した場合のみ、単一の値になります。

タイトルによってシークレットを取得

# 一致するレコードをすべて取得
get_secrets_by_title(record_title)

# 最初に一致するレコードのみを取得
get_secret_by_title(record_title)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャーをセットアップ
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'))

# レコードタイトルに一致する最初のシークレットを取得する
secret = secrets_manager.get_secret_by_title("My Credentials")

# レコードタイトルに一致するすべてのシークレットを取得する
secrets = secrets_manager.get_secrets_by_title("My Credentials")

パラメータ

型

必須

説明

record_title

String

はい

検索するレコードタイトル

リンクされたレコードへのアクセス (GraphSync)

PAMレコードは認証情報レコードへのリンクを保持できます。リンクはデフォルトでは get_secrets() のレスポンスに含まれません。request_links=True を指定して get_secrets_with_options() を呼び出し、record.get_links() で型付きの KeeperRecordLink オブジェクトとして取得できます。

from keeper_secrets_manager_core.dto.payload import QueryOptions

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(link.record_uid)   # UID of the linked record
    print(link.path)         # None = credential link; "meta" = PAM settings

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.payload import QueryOptions

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(f"Linked record: {link.record_uid}  path: {link.path}")

    # Credential link flags (path is None)
    if link.path is None:
        print(f"  Admin user:         {link.is_admin_user()}")
        print(f"  Launch credential:  {link.is_launch_credential()}")
        print(f"  IAM user:           {link.is_iam_user()}")

    # PAM settings flags (path == "meta")
    if link.path == "meta":
        print(f"  Allows rotation:     {link.allows_rotation()}")
        print(f"  Allows connections:  {link.allows_connections()}")

KeeperRecordLink 属性

属性

型

説明

record_uid

str

リンク先レコードのUID

path

str または None

リンクタイプの識別子。None = 別レコードへの認証情報リンク、"meta" = PAM設定の自己リンク、"ai_settings" / "jit_settings" = 暗号化設定の自己リンク

data

str または None

Base64形式のリンクペイロード (生データ)。直接参照せず、アクセサメソッドを使用

KeeperRecordLink メソッド

メソッド

戻り値

説明

is_admin_user()

bool

リンク先が管理者ユーザー

is_launch_credential()

bool

起動用認証情報へのリンク

is_iam_user()

bool

リンク先がIAMユーザー

belongs_to()

bool

リンク先認証情報がレコードに属する

allows_rotation()

bool

ローテーション許可 (認証情報またはmetaリンク)

allows_connections()

bool

接続許可

allows_port_forwards()

bool

ポートフォワーディング許可

allows_session_recording()

bool

セッション記録の有効化

get_rotation_settings()

dict または None

ローテーションスケジュールとパスワード複雑性の設定

get_meta_data()

dict または None

PAM設定ペイロード全体 (path == "meta")

get_link_data()

dict または None

任意パスの解析済みリンクペイロード

Keeper表記法を使用して値を取得

get_notation(query)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# Keeper表記法を使用して特定の標準フィールドを取得
password = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/field/password')[0]

# Keeper表記法を使用して特定のカスタムフィールドを取得
custom_field_value = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/custom_field/my_field')

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

パラメータ

型

必須

デフォルト

説明

query

String

はい

指定したフィールドの値を取得するためのKeeper表記法を使用したクエリ

戻り値

型: string または string[]

クエリで取得したフィールドの値

TOTPコードを取得

get_totp_code(url)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import get_totp_code

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
record = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# レコードからTOTP url値を取得
url = record.get_standard_field_value('oneTimeCode', True)

# TOTP urlからコードを取得
totp = get_totp_code(url)
print(totp.code)

パラメータ

型

必須

デフォルト

説明

url

str

はい

otpauth:// 形式のTOTP URI。URIスキームが otpauth でない場合は ValueError を送出

PAMレコードタイプ

SDKが返すPAMレコードは record.type で識別できます。

for record in records:
    if record.type == "pamMachine":
        host = record.field("pamHostname")[0]  # {"hostName": ..., "port": ...}
    elif record.type == "pamUser":
        login = record.field("login")[0]
    elif record.type == "pamDatabase":
        db_type = record.field("databaseType")[0]

全11種類のPAMレコードタイプのフィールド定義は、PAMレコードタイプをご参照ください。

リンク済み認証情報

PAMレコードには認証情報レコードへのリンクを保持できます。リンクはデフォルトでは get_secrets() のレスポンスに含まれません。get_secrets_with_options() で request_links=True を指定して取得し、record.get_links() から型付きの KeeperRecordLink オブジェクトとして参照できます。

from keeper_secrets_manager_core.dto.payload import QueryOptions

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(link.record_uid)   # リンク先レコードのUID
    print(link.path)         # None = 認証情報リンク; "meta" = PAM設定

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.payload import QueryOptions

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(f"Linked record: {link.record_uid}  path: {link.path}")

    # 認証情報リンクのフラグ (path が None)
    if link.path is None:
        print(f"  Admin user:         {link.is_admin_user()}")
        print(f"  Launch credential:  {link.is_launch_credential()}")
        print(f"  IAM user:           {link.is_iam_user()}")

    # PAM設定フラグ (path == "meta")
    if link.path == "meta":
        print(f"  Allows rotation:     {link.allows_rotation()}")
        print(f"  Allows connections:  {link.allows_connections()}")

KeeperRecordLink 属性

属性

型

説明

record_uid

str

リンク先レコードのUID

path

str or None

リンク種別の判別子。None = 別レコードへの認証情報リンク、"meta" = PAM設定の自己リンク、"ai_settings" / "jit_settings" = 暗号化設定の自己リンク

data

str or None

Base64形式の生リンクペイロード。直接参照せずアクセサメソッドを使用

KeeperRecordLink メソッド

メソッド

戻り値

説明

is_admin_user()

bool

管理者ユーザー向けリンク

is_launch_credential()

bool

接続用認証情報リンク

is_iam_user()

bool

IAMユーザー向けリンク

belongs_to()

bool

レコードに所属するリンク

allows_rotation()

bool

ローテーション許可 (認証情報または meta リンク)

allows_connections()

bool

接続許可

allows_port_forwards()

bool

ポートフォワーディング許可

allows_session_recording()

bool

セッション記録有効

get_rotation_settings()

dict or None

ローテーションスケジュールと複雑性の設定

get_meta_data()

dict or None

PAM設定ペイロード全体 (path == "meta")

get_link_data()

dict or None

任意の path 向け解析済みリンクペイロード

シークレットを更新

レコード更新コマンドは、成功時にローカルのレコードデータ (特にレコードリビジョンの更新) を更新しないため、既に更新されたレコードを継続的に更新してもリビジョンの不一致により失敗となります。各更新バッチの後に、更新済みのレコードをすべてリロードするようにしてください。

変更をシークレットに保存

save(record: KeeperRecord)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret_to_update = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# フィールド値を更新
secret_to_update.field('login', value='new login')

# 非フィールド値を更新
secret_to_update.title = "New Title"
secret_to_update.notes = "New Notes"

# 更新したシークレットを保存
secrets_manager.save(secret_to_update)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャのセットアップ
secrets_manager = SecretsManager(
     config=FileKeyValueStorage('ksm-config.json')
)

# UIDを使用して特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# レコードのパスワードをローテーション
secret.field('password', value='new password')
# トランザクションを開始
secrets_manager.save(secret, 'rotation')
# リモートホストでパスワードをローテーション
success = rotate_remote_ssh_password('new password')
# トランザクションを完了 (コミットかロールバック)
secrets_manager.complete_transaction(secret.uid, rollback=not success)

record

KeeperRecord

はい

ストレージとクエリの設定

fieldメソッドを使用してフィールド値を設定します。

利用可能なフィールドの詳細な一覧については、コマンダーで record-type-info コマンドをご参照ください。一部のフィールドは複数の値を持つことができ、その場合は値をリストとして設定できます。

標準フィールド値を更新

secret.field(field_type, value=None, single=False)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# ログインを更新
secret.field("login", value="My New Login")

# シークレットを保存
secrets_manager.save(secret)

パラメータ

型

必須

デフォルト

説明

field_type

String

はい

取得するフィールドタイプ

value

String または String[]

オプション

None

指定すると、フィールドの値を指定値に設定

single

boolean

オプション

False

最初の値のみを返す

カスタムフィールド値の更新

secret.custom_field(label, field_type=None, value=None, single=False)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# 標準テンプレートフィールドを取得
password = secret.field('password', single=True)

# カスタムフィールド「API Key」を設定
my_new_api_key = "wKridl2ULt20qGuiP3IY"
secret.custom_field('API Key', value=my_new_api_key)

# 変更をシークレットに保存
secrets_manager.save(secret)

パラメータ

型

必須

デフォルト

説明

label

String

はい

カスタムフィールドのラベル

field_type

String

オプション

None

取得するフィールドタイプ

value

StringまたはString[]

オプション

None

指定すると、フィールドの値を指定値に設定

single

boolean

オプション

False

最初の値のみを返す

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

generate_password(length, lowercase, uppercase, digits, special_characters, special_characterset)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import generate_password

# シークレットマネージャーを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# ランダムなパスワードを生成
password = generate_password(special_characterset="@!#$%^&*<>?")
# 新しいパスワードでレコードを更新
secret.field('password', value=password)

# 変更をシークレットに保存
secrets_manager.save(secret)

パラメータ

型

必須

デフォルト

説明

length

int

オプション

パスワードの最小文字数

lowercase

int

オプション

None

小文字の最小数 (正の値)、正確な数 (0または負)、制約なし (None)

uppercase

int

オプション

None

大文字の最小数 (正の値)、正確な数 (0または負)、制約なし (None)

digits

int

オプション

None

数字の最小数 (正の値)、正確な数 (0または負)、制約なし (None)

special_characters

int

オプション

None

特殊文字の最小数 (正の値)、正確な数 (0または負)、制約なし (None)

special_characterset

str

オプション

"!@#$%()+;<>=?[]{}^.,

特殊文字部分の生成時に使用するカスタム文字セット

各文字クラスのパラメータは、正の値なら最小文字数、0または負の値なら正確な文字数、None (デフォルト) なら制約なしを意味します。4文字クラスすべてが None の場合、または正確な文字数の合計が length 未満の場合、残りは有効な文字クラスからランダムに選ばれます。

ファイルのダウンロード

file.save_file(file_path, create_folders=False)

# すべてのファイルを/tmpフォルダに保存（存在しない場合はフォルダを作成）
for file in secret.files:
    print("file: %s" % file)
    file.save_file("/tmp/" + file.name, True)

パラメータ

型

必須

デフォルト

説明

file_path

String

はい

ファイルの保存先のパス

create_folders

boolean

いいえ

False

存在しない場合はfile_pathにフォルダを作成

ファイルのアップロード

upload_file(owner_record, file: my_file)

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

KeeperFileUpload.from_file(path, file_name=None, file_title=None, mime_type=None)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.core import KeeperFileUpload

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDによってファイルを添付するシークレットを取得
UID_FILTER = 'XXX'
owner_record= secrets_manager.get_secrets([UID_FILTER])[0]

# アップロード用のファイルデータを準備
my_file = KeeperFileUpload.from_file("./myFile.json", "myfile.json", "My File") 

# 所有者のレコードに添付されたファイルをアップロードしてUIDを取得
file_uid = secrets_manager.upload_file(owner_record, file = my_file)

ファイルのアップロード

パラメータ

型

必須

説明

owner_record

KeeperRecord

はい

アップロードされたファイルを添付するレコード

file

KeeperFileUpload

はい

アップロードするファイル

ファイルからのKeeperファイルのアップロード

パラメータ

型

必須

デフォルト

説明

path

string

はい

アップロードするファイルへのパス

file_name

string

いいえ

None

アップロード後にKeeperに格納されるファイルの名前

file_title

string

いいえ

None

アップロード後にKeeperに格納されるファイルのタイトル

mime_type

string

いいえ

None

ファイル内のデータの種類。何も指定しない場合は、「application/octet-stream」が使用されます。

戻り値

型: string

添付ファイルのファイルUID

添付ファイルの削除

secrets_manager.save(record, links_to_remove=['<FILE_UID>'])

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDを指定してシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# レコードに含まれるファイルのUIDを取得
file_uids = [file.file_uid for file in secret.files]
print(f"Files to remove: {file_uids}")

# UIDを指定して特定のファイルを削除
secrets_manager.save(secret, links_to_remove=file_uids)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDを指定してシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# 複数の特定ファイルを削除
files_to_remove = ['<FILE_UID_1>', '<FILE_UID_2>']
secrets_manager.save(secret, links_to_remove=files_to_remove)

# すべてのファイルを削除
all_file_uids = [file.file_uid for file in secret.files]
secrets_manager.save(secret, links_to_remove=all_file_uids)

パラメーター

タイプ

必須

説明

record

KeeperRecord

はい

更新対象となるレコード

links_to_remove

String または List[String]

いいえ

レコードから削除するファイルのUID

ファイルを削除したあとに同じレコードへ続けて更新する場合は、レコードのリビジョンが更新されているため、get_secrets() でレコードを取り直してください。

シークレットの作成

要件

共有フォルダのUID
- 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできること
- あなたとシークレットマネージャーアプリケーションに編集権限が付与されていること
- 共有フォルダには、少なくとも1つのレコードが存在すること。
作成されたレコードとレコードのフィールドが正しく書式設定されていること。
- 各レコードタイプで想定されるフィールド形式については、レコードタイプをご参照ください。
TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます。
レコードの作成後は、upload_fileを使用して添付ファイルをアップロードできます。

from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

secrets_manager.create_secret(folder_uid, record)

パラメータ

型

必須

デフォルト

folder_uid

String

はい

record

KeeperRecord

はい

from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

from keeper_secrets_manager_core.dto.payload import CreateOptions

create_options = CreateOptions(
    folder_uid='shared_folder_uid',
    subfolder_uid='user_folder_uid'
)

secrets_manager.create_secret_with_options(create_options, record)

パラメータ

型

必須

デフォルト

create_options

CreateOptions

はい

record

KeeperRecord

はい

この例では、ログイン値と生成されたパスワードを含むログインタイプのレコードを作成します。

例にある [FOLDER UID] をシークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えます。

# 新しいログインレコードを作成
new_login_record = RecordCreate('login', "Sample KSM Record: Python")
# ログインフィールドとパスワードフィールドに入力
new_login_record.fields = [
    RecordField(field_type='login', value='username@email.com'),
    RecordField(field_type='password', value=generate_password())
]
# メモに入力
new_login_record.notes = 'This is a Python record creation example'
# 新しいレコードを作成し、新規レコードのUIDを取得
record_uid = secrets_manager.create_secret('[FOLDER UID]', new_login_record)

この例では、カスタムのレコードタイプのレコードを作成します。

例にある[FOLDER UID]をシークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えます。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.dtos import RecordCreate, RecordField
from keeper_secrets_manager_core.utils import generate_password

# setup secrets manger
secrets_manager = SecretsManager(
  # token='US:XXXXXX',
    config=FileKeyValueStorage('ksm-config.json')
)

custom_login = RecordCreate(record_type='Custom Login', title='Sample Custom Type KSM Record: Python')
custom_login.fields = [
    RecordField(field_type='host',
                value={'hostName':'127.0.0.1', 'port':'8080'},
                label="My Custom Host lbl",
                required=True),
    RecordField(field_type='login',
                value='login@email.com',
                label='My Custom Login lbl',
                required=True),
    RecordField(field_type='password',
                value=generate_password(),
                label='My Custom Password lbl',
                required=True),
    RecordField(field_type='url',
                value='http://localhost:8080/login',
                label='My Login Page',
                required=True),
    RecordField(field_type='securityQuestion',
                value={
                    'question':'What is one plus one (write just a number)',
                    'answer':'2'
                },
                label='My Question 1',
                required=True),
    RecordField(field_type='phone',
                value={
                  'region':'US',
                  'number':'510-444-3333',
                  'ext':'2345',
                  'type':'Mobile'},
                label='My Phone Number'),
    RecordField(field_type='date',
                value=1641934793000,
                label='My Date Lbl',
                required=True),
    RecordField(field_type='name',
                value={
                  'first':'John',
                  'middle':'Patrick',
                  'last':'Smith'},
                label="My Custom Name lbl",
                required=True),
    RecordField(field_type='oneTimeCode',
                value='otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example',
                label='My TOTP',
                required=True)
]

custom_login.custom = [
    RecordField(field_type='phone',
                value={'region':'US', 'number':'510-222-5555', 'ext':'99887', 'type':'Mobile'},
                label='My Custom Phone Lbl 1'),
    RecordField(field_type='phone',
                value={'region':'US', 'number':'510-111-3333', 'ext':'45674', 'type':'Mobile'},
                label='My Custom Phone Lbl 2'),
]

custom_login.notes = "\tThis custom type record was created\n\tvia Python SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/python-sdk"

record_uid = secrets_manager.create_secret('[FOLDER UID]', custom_login)

戻り値

型: string

新規レコードのレコードUID

シークレットの削除

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

secrets_manager.delete_secret(record_uids)

パラメータ

型

必須

説明

record_uids

str または List[str]

はい

削除するレコードのUID、またはUIDのリスト

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャーを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを削除
secrets_manager.delete_secret('EG6KdJaaLG7esRZbMnfbFA')

キャッシュ

ネットワークアクセスが失われたときにシークレットにアクセスできなくなる状況を避けるため、Python SDKを使用してシークレットを暗号化されたファイルでローカルマシンにキャッシュできます。

キャッシュの設定と構成

Python SDKでキャッシュを設定するには、SecretsManager オブジェクトを作成するときにキャッシュポスト関数を含める必要があります。

Python SDKには、KSMCache クラスにデフォルトのキャッシュ機能が含まれており、キャッシュされたクエリをローカルファイルに保存し、復旧機能として使用できます (ネットワーク接続がある場合は常にネットワークデータを優先し、ウェブボルトにアクセスできない場合にのみキャッシュを使用します)。独自のキャッシュ機能を作成することも可能で、KSMCache を出発点として利用できます。例えば、ネットワークアクセスよりもローカルキャッシュを優先し、独自のキャッシュ管理を行う (例: キャッシュデータを5分ごとに更新する) 機能を作成できます。

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json'),
    custom_post_function=KSMCache.caching_post_function
)

デフォルトの KSMCache は直近のレスポンスのみを保存します。get_secrets(['<uid>']) の後、オフライン時に引数なしで get_secrets() を呼び出すと、キャッシュ済みの1件のみが返り、ボルト全体は取得できません。

キャッシュからのレコード更新 (または新しいレコードの作成) は、キャッシュされたレコードデータを無効にし、同じレコードを連続して更新する操作は失敗します。異なるレコードを修正する場合、バッチ更新は機能します。キャッシュされたレコードを更新した後は、常に get_secrets 関数を呼び出してキャッシュをリフレッシュし、ボルトから新しいレコードリビジョンなどの更新されたメタデータを取得するようにしてください。

独自のキャッシュ関数の作成

まず、以下の引数を使用してキャッシュ関数を作成し、post_function を呼び出します。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )
    # ここにカスタムキャッシュ処理を記述 ...

    # 常に KSMHttpResponse オブジェクトを返すようにする
    return ksm_rs

次に、KSMCacheを使用して任意のキャッシュ処理ロジックを実装できます。

以下は基本的なサンプルです。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from http import HTTPStatus

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )

    if ksm_rs.status_code < 400:
        KSMCache.save_cache(transmission_key.key + ksm_rs.data)
        return ksm_rs

    # KSMCache が空の場合がある    
    cached_data = KSMCache.get_cached_data()
    cached_transmission_key = cached_data[:32]
    transmission_key.key = cached_transmission_key
    data = cached_data[32 : len(cached_data)]

    new_rs = KSMHttpResponse(HTTPStatus.OK, data, None)
    return new_rs


secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    verify_ssl_certs=False,
    custom_post_function=caching_post_function
)

フォルダ

フォルダは完全なCRUD (作成、読み取り、更新、削除操作) が利用できます。

フォルダの読み取り

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

get_folders()

レスポンス

型: List[KeeperFolder]

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
folders = secrets_manager.get_folders()

フォルダの作成

CreateOptions とフォルダ名の指定が必要です。CreateOptions はフォルダのUIDパラメータ (共有フォルダのUID) が必須ですが、サブフォルダのUIDはオプションであり、指定されていない場合は、通常の新しいフォルダが親 (共有フォルダ) の直下に作成されます。サブフォルダは、親の共有フォルダの直接の下位オブジェクトである必要はありません。親フォルダから何階層も深い位置にサブフォルダを作成することができます。

create_folder(create_options: CreateOptions, folder_name: str, folders=None)

パラメータ

型

必須

デフォルト

説明

create_options

CreateOptions

はい

親およびサブフォルダのUID

folder_name

str

はい

フォルダ名

folders

List[KeeperFolder]

いいえ

None

CreateOptionsで作成した親とサブフォルダの検索に使用するフォルダのリスト

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import CreateOptions
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
co = CreateOptions(folder_uid="[PARENT_SHARED_FOLDER_UID]", subfolder_uid="")
new_folder_uid = secrets_manager.create_folder(co, "new_folder")

フォルダの更新

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

update_folder(folder_uid: str, folder_name: str, folders=None)

パラメータ

型

必須

デフォルト

説明

folder_uid

str

はい

フォルダのUID

folder_name

str

はい

新しいフォルダ名

folders

List[KeeperFolder]

いいえ

None

親フォルダの検索に使用するフォルダのリスト

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.update_folder("[FOLDER_UID]", "new_folder_name")

フォルダの削除

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

force_deletion を使用する場合は、親フォルダと子フォルダのUIDを一緒に送信しないようにしてください。削除する順序によっては、エラーが発生する可能性があります。たとえば、親が子を先に強制削除した場合などです。リストが必ずしもFIFO順で処理される保証はありません。

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

delete_folder(folder_uids: List[str], force_deletion: bool = False)

パラメータ

型

必須

デフォルト

説明

folder_uids

List[str]

はい

フォルダUIDリスト

force_deletion

bool

いいえ

False

空でないフォルダを強制的に削除

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.delete_folder(["[FOLDER_UID1]", "[FOLDER_UID2]"], True)

プロキシのサポート

環境変数

KeeperシークレットマネージャーSDKは、デフォルトでrequestsライブラリを使用し、HTTPS_PROXY環境変数に対応しています。

HTTPS_PROXY=https://yourproxy:8888 python main.py

この設定を行うと、Keeperシークレットマネージャーへのリクエストを含むすべてのリクエストが、指定したプロキシを経由して送信されます。

プロキシ設定は、環境変数で行うことを推奨します。コードに設定を直接記述せずに済み、ツール間で同じ設定を使い回せるほか、導入や運用も容易になります。

SecretsManagerのパラメータ

SDK内でのみプロキシを使用したい場合は、SecretsManager にプロキシURLを渡すこともできます。

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    proxy_url="https://yourproxy:8888"
)

プロキシで認証が必要な場合は、プロキシURLにユーザー名とパスワードを含めて指定してください。

https://username:pass@yourproxy:8888

高度な構成

カスタムサーバー公開鍵

SDKにサーバー公開鍵を同梱できない分離環境やプライベート環境では、EC P-256公開鍵を以下の2通りで指定できます。優先順位はプログラム指定 > 既存の構成です。

プログラム指定: SecretsManager() に server_public_key と server_public_key_id を渡します。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='REGION:ONE_TIME_TOKEN',
    server_public_key='<url-safe-base64-EC-P256-public-key>',
    server_public_key_id='<numeric-key-id>',
    config=FileKeyValueStorage('ksm-config.json'),
)

構成ファイル: 初回呼び出しの前に、紐付け済みの ksm-config.json に serverPublicKey と serverPublicKeyId を追加します。これら2つのフィールドは紐付け済み構成を補完するものであり、置き換えるものではありません。

{
  "serverPublicKey": "<url-safe-base64-EC-P256-public-key>",
  "serverPublicKeyId": "<key-id>"
}

前へKSM開発者用SDK

次へJava/Kotlin SDK

最終更新 2 か月前