Версия: 7.0

Python-коннектор

Описание

Python-коннектор Пассворк — это инструмент, который упрощает программистам и DevOps-инженерам интеграцию Пассворка с инфраструктурой компании. Коннектор позволяет быстро и безопасно автоматизировать работу с паролями, сейфами и доступами, не погружаясь в детали низкоуровневого взаимодействия с API и криптографией.

Основные задачи и преимущества

Упрощение интеграции: Коннектор избавляет от необходимости вручную реализовывать работу с API, шифрованием и сессиями. Все основные операции сведены к простым методам.
Безопасность на клиенте: Вся клиентская криптография (шифрование, расшифровка, работа с мастер-ключом) реализована внутри коннектора. Ваши секреты всегда защищены — даже при работе с открытым API.
Управление сессией: Коннектор позволяет сохранять и восстанавливать сессию, чтобы не проходить авторизацию заново при каждом запуске скрипта.
Гибкость: Для всех методов API, которые не покрыты отдельными функциями коннектора, реализован универсальный метод call. С его помощью можно обращаться к любым конечным точкам API Пассворка, сохраняя при этом безопасность и удобство работы.

Требования

Python 3.10+
requests>=2.31.0
python-dotenv>=1.0.0
cryptography>=42.0.0
pbkdf2>=1.3

Установка

Можно установить пакет прямо из Github:

shell

pip install git+ssh://git@github.com:passwork-me/passwork-python.git

Или через HTTPS:

shell

pip install git+https://github.com/passwork-me/passwork-python.git

Возможности

Клиентское шифрование с поддержкой мастер-пароля;
Автоматическое обновление токена;
Зашифрованное хранение и восстановление сессий;
Многоуровневое шифрование (PBKDF2, RSA, AES);
Работа с вложениями;
Управление пользователями и ролями;
Управление хранилищами (vault);
Совместное использование паролей через «входящие»;
Поддержка пользовательских полей;
Система тегов;

Расширенное использование

В 7 версии Пассворка используется механизм токенов с ограниченным сроком действия:

Access Token: Основной токен для авторизации запросов. Имеет ограниченный срок действия (обычно несколько минут или часов);
Refresh Token: Долгоживущий токен, используемый для получения нового access token без повторной аутентификации;

Управление сессиями

Коннектор может сохранять и использовать токены, а также, в случае истечения срока действия ACCESS_TOKEN, выполнять автоматическое обновление токенов (если задан REFRESH_TOKEN):

Python

# Активировать использование и автоматическое обновление токенов при авторизации
passwork = PassworkClient(HOST, True, True)

# Загружать и расшифровывать токены из файла session.file для использования в текущем сценарии
passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

# Сохранить токены из текущего сценария в файл session.file в зашифрованном виде
encryption_key = passwork.save_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=", True)

Пример сценария с автоматическим обновлением токенов:

Python

import sys
import os
from passwork_client import PassworkClient

# Конфигурация
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Опционально (необходим для обновления токенов)
MASTER_KEY = "" # Мастер ключ (если клиентское шифрование активировано)
HOST = "https://passwork" # Адрес Пассворка

# Авторизация в Пассворке
try:
    # Активировать использование и автоматическое обновление токенов при авторизации
    passwork = PassworkClient(HOST, True, True)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}")
    exit(1)

# Загружать и расшифровывать токены из файла session.file для использования в текущем сценарии
#passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

# Пример: Создание сейфа
try:
    vault_name = "Python Vault"
    vault_id = passwork.create_vault(vault_name)
    print(f"Vault was created: {vault_id}")
except Exception as e:
    print(f"Error: {e}")

# Сохранить токены из текущего сценария в файл session.file в зашифрованном виде 
encryption_key = passwork.save_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=", True)

При первом запуске загрузка токенов из файла session.file должна быть закомментирована — так как токены ещё не сохранены. При последующих запусках строку необходимо раскомментировать, чтобы использовать ранее сохранённые токены:

Python

passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

Управление паролями

Создание пароля с пользовательскими полями, тегами и вложениями:

Python

import sys
import os
from passwork_client import PassworkClient

# Конфигурация
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Опционально (необходим для обновления токенов)
MASTER_KEY = "" # Мастер ключ (если клиентское шифрование активировано)
HOST = "https://passwork" # Адрес Пассворка

# Авторизация в Пассворке
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)

# Пример: Создание записи
try:
    VAULT_ID = ""
    COLOR = 8
    
    # Пример дополнительных полей
    custom_fields = [
        {
            "name": "Text Field",
            "value": "Field value",
            "type": "text"
        },
        {
            "name": "Custom Password",
            "value": "Secret123!",
            "type": "password"
        },
        {
            "name": "TOTP",
            "value": "ABCDEFGHIJKLMNOP",
            "type": "totp"
        }
    ]
    
    # Подготовка данных записи
    item_data = {
        "vaultId": VAULT_ID,
        "name": "New Item",
        "login": "test_user",
        "password": "Test_password123!",
        "url": "https://example.com",
        "description": "Item description",
        "color": COLOR,
        "tags": ["tag1", "tag2"],
        "customs": custom_fields
    }
    
    # Создание записи
    item_id = passwork.create_item(item_data)
    print(f"Item created with ID: {item_id}")
    
    # Получить данные созданной записи
    item = passwork.get_item(item_id)
    print(f"Created item: {item}")

except Exception as e:
    print(f"Error: {e}") 

Обновление существующего пароля:

Python

import sys
import os
from passwork_client import PassworkClient

# Конфигурация
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Опционально (необходим для обновления токенов)
MASTER_KEY = "" # Мастер ключ (если клиентское шифрование активировано)
HOST = "https://passwork" # Адрес Пассворка

# Авторизация в Пассворке
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)

# Пример: Обновление записи
try:
    # ID записи для обновления
    ITEM_ID = ""
    VAULT_ID = ""
    
    # Получить текущую запись
    item = passwork.get_item(ITEM_ID)
    print(f"Current item: {item}")
    
    # Данные для обновления записи
    updated_data = {
        "vaultId": VAULT_ID,
        "name": "Updated Item Name",
        "login": "updated_user",
        "password": "Updated_Password_456!",
        "url": "https://updated-example.com",
        "description": "Updated description",
        "tags": ["updated", "tag2", "tag3"],
        "customs": [
            {
                "name": "Updated Custom Field",
                "value": "Updated value",
                "type": "text"
            },
            {
                "name": "Updated Password Field",
                "value": "NewSecret456!",
                "type": "password"
            }
        ]
    }
    
    # Обновление записи
    passwork.update_item(ITEM_ID, updated_data)
    
    # Получить обновлённую запись
    updated_item = passwork.get_item(ITEM_ID)
    print(f"Updated item: {updated_item}")

except Exception as e:
    print(f"Error: {e}") 

Удаление пароля:

Python

import sys
import os
from passwork_client import PassworkClient

# Конфигурация
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Опционально (необходим для обновления токенов)
MASTER_KEY = "" # Мастер ключ (если клиентское шифрование активировано)
HOST = "https://passwork" # Адрес Пассворка

# Авторизация в Пассворке
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}")
    exit(1)

# Пример: Удаление записи
try:
    # ID записи для удаления
    ITEM_ID = ""
    
    # Удаление записи
    bin_item_id = passwork.delete_item(ITEM_ID)
    print(f"Item deleted. Bin item ID: {bin_item_id}")
    
except Exception as e:
    print(f"Error: {e}")

Управление пользователями

Создание нового пользователя:

Python

import sys
import os
from passwork_client import PassworkClient

# Конфигурация
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Опционально (необходим для обновления токенов)
MASTER_KEY = "" # Мастер ключ (если клиентское шифрование активировано)
HOST = "https://passwork" # Адрес Пассворка

# Авторизация в Пассворке
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)


# Пример: Создание пользователя
try:
    # Получение доступных ролей пользователей
    roles_response = passwork.call("GET", "/api/v1/user-roles", {"includeUserRole": '1', "isOnlyManageable": '1'})
    if not roles_response or not roles_response.get("items"):
        print("Error: Could not fetch user roles or no manageable roles found.")
        exit(1)

    # Поиск роли «Сотрудник» (при необходимости изменить)
    user_role_items = [r for r in roles_response["items"] if r.get("code") == "user"]
    if not user_role_items:
        print("Error: Default 'user' role not found.")
        exit(1)
    default_user_role_id = user_role_items[0]["id"]
    
    # Определение пользовательских данных
    user_data = {
        "email": "test_user_python@example.com",
        "fullName": "Python Test User",
        "login": "python_test_user",
        "userRoleId": default_user_role_id,
    }
    
    # Создание пользователя
    new_user = passwork.create_user(user_data)

    # Сообщение об успехе
    message = f"User '{user_data['fullName']}' created with ID: {new_user['user_id']}"
    if 'password' in new_user and new_user['password']:
         message += f", password: {new_user['password']}"
    if 'master_password' in new_user and new_user['master_password']:
        message += f", master password: {new_user['master_password']}"

    print(message)

except Exception as e:
    print(f"Error: {e}") 

Прямые вызовы к API

Для операций, не покрытых вспомогательными методами:

Python

# Прямой вызов к API
response = client.call("DELETE", f"/api/v1/folders/{folder_id}")

Документация

Подробные примеры расположены в директории examples репозитория.

Описание​

Основные задачи и преимущества​

Требования​

Установка​

Возможности​

Расширенное использование​

Управление сессиями​

Управление паролями​

Управление пользователями​

Прямые вызовы к API​

Документация​