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)