Python SDK

Keeper Secrets Manager用Python SDKの詳細なドキュメント

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

PIPによるインストール

pip3 install -U keeper-secrets-manager-core

ソースコード

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

SDKの使用

初期化

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

Secrets Manager

SecretsManager(token, config)
# トークンのみを使用して（後で使用するために）設定を生成するには、
# トークンをバインドするアクセス操作が少なくとも1回必要です
#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')
)
# トークンのみを使用して設定を生成するには 
# トークンをバインドするアクセス操作が少なくとも1回必要です
#secrets_manager.get_secrets(uids=None)

パラメータ	必須	説明	型
token	はい	ワンタイムアクセストークン	String
config	はい	ストレージの設定	KeyValueStorage

シークレットの取得

シークレットの取得

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 Secrets Managerから取得すると、このショートカットでそのシークレットのパスワードを取得します。

パスワードを取得

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, single=False, value=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')
)

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

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

パラメータ	型	必須	デフォルト	説明
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

フィールドはタイプで検索されます。フィールドタイプの一覧は、記録タイプのドキュメントをご参照ください。

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

カスタムフィールド

secret.custom_field(label, field_type=None, single=False, value=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')
)

# 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	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

カスタムフィールドは、記録タイプ定義の一部ではありませんが、ユーザーが追加できるフィールドです。 各標準記録タイプのフィールドの一覧は、記録タイプのドキュメントをご参照ください。

同じカスタムタイプの複数のフィールドを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

# setup secrets manger
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'))

# get the first secret matching the record title
secret = secrets_manager.get_secret_by_title("My Credentials")

# get all secrets matching the record title
secrets = secrets_manager.get_secrets_by_title("My Credentials")

パラメータ	型	必須	説明
record_title	String	はい	検索する記録タイトル

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

Get Notation

get_notation(query)

Example Usage

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 or string[]

照会したフィールドの値

TOTPコードを取得

Get TOTP Code

get_totp_code(url)

Example Usage

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

# 記録からTOTP url値を取得
url = record.get_standard_field_value('oneTimeCode', True)

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

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

シークレットを更新

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

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

シークレットを保存

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', 'new login')

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', '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メソッドを使用してフィールド値を設定します。

フィールドはタイプで検索されます。フィールドタイプの一覧は、記録タイプのドキュメントをご参照ください。複数の値を持つフィールドもあります。このような場合は、値をリストに設定できます。

標準フィールド値を更新

フィールド

secret.field(field_type, single=False, value=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')
)

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

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

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

パラメータ	型	必須	デフォルト	説明
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

フィールドはタイプで検索されます。フィールドタイプの一覧は、記録タイプのドキュメントをご参照ください。

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

カスタムフィールド

secret.custom_field(label, field_type=None, single=False, value=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')
)

# 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', single=True, my_new_api_key)

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

パラメータ	型	必須	デフォルト	説明
label	String	はい		カスタムフィールドのラベル
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

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

パスワードを生成

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

例

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を設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

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

# ランダムなパスワードを生成
password = generate_password()
# 新しいパスワードで記録を更新
secret.field('password', value=password)

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

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

各パラメータは、使用する文字の種類の最小数を示します。たとえば、「uppercase」は、使用する大文字の最小数を示します。

ファイルのダウンロード

ファイルを保存

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") 

# 所有者の記録に添付されたファイルをアップロード
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

シークレットの作成

前提条件:

• 共有フォルダのUID

  • 共有フォルダには、Secrets Managerアプリケーションからアクセスできる必要があります

  • あなたとSecrets Managerアプリケーションには編集権限が必要です

  • 共有フォルダには、少なくとも1つの記録が存在する必要があります

• 作成された記録と記録のフィールドは正しく書式設定されている必要があります

  • 記録タイプごとの適切なフィールド形式については、このドキュメントをご参照ください。

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

• 記録の作成後は、upload_fileを使用して添付ファイルをアップロードできます

記録を作成

secrets_manager.create_secret(folder_uid, record)

パラメータ	型	必須	デフォルト
folder_uid	String	はい
record	KeeperRecord	はい

サブフォルダに記録を作成

secrets_manager.create_secret_with_options(create_options, record)

パラメータ	型	必須	デフォルト
create_options	CreateOptions	はい
record	KeeperRecord	はい

ログインの記録の例

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

例にある「[FOLDER UID]」をSecrets Managerがアクセスできる共有フォルダのUIDに置き換えます。

# 新しいログイン記録を作成
new_login_record = RecordCreate('login', "Sample KSM Record:Python")
# ログインフィールドとパスワードフィールドに入力
new_login_record.fields = [
    RecordField(field_type='login', value='[e-mail]'),
    RecordField(field_type='password', value=generate_password())
]
# メモに入力
new_login_record.notes = 'This is a Python record creation example'
# 新しい記録を作成 
secrets_manager.create_secret('[FOLDER UID]', new_login_record)

カスタムタイプの例

この例では、カスタムの記録タイプの記録を作成します。

例にある「[FOLDER UID]」をSecrets Managerがアクセスできる共有フォルダのUIDに置き換えます。

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='[e-mail]',
                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:[e-mail]?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_uid)

パラメータ	型	必須
record_uid	string	はい

例

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.delete_secret('EG6KdJaaLG7esRZbMnfbFA')

キャッシュ

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

キャッシュの設定と構成

Python SDKでキャッシュを設定するには、SecretsManagerオブジェクトを作成するときにPOSTキャッシュ関数を指定します。

Python SDKには、クエリをキャッシュしてファイルに保存するデフォルトのキャッシュ関数KSMCacheが含まれています。

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json'),
    custom_post_function=KSMCache.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.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
co = CreateOptions(folder_uid="[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)