Перейти к основному содержимому
Версия: Privileged Access Manager 3.4

Python SDK

Python SDK предоставляет API для получения паролей и SSH-ключей учетных записей Indeed PAM. Решение подходит для интеграции PAM в CI/CD-автоматизации, Python-скрипты, системы оркестрации и в другие процессы, где требуется безопасно управлять учетными данными.

Все запросы на получение и просмотр учетных данных записываются в журнал События.

Требования

Для работы с Python SDK требуется Python 3.9 и выше.

Примечание

Работа с параметрами retry (повтор запросов) и rate limit (ограничение частоты запросов) не поддерживается.

Предварительные действия​

Чтобы настроить работу с Python SDK:

  1. Перейдите в папку с пакетом AAPM для Python SDK и выполните команду:

    pip install pam_aapm-3.4.0-py3-none-any.whl
  2. Перейдите в консоль администратора Indeed PAM и добавьте приложение.
  3. Для приложения добавьте разрешение с включенной опцией Разрешить просмотр учетных данных.
    Разрешение позволит приложению использовать пароли и SSH-ключи учетных записей PAM.
  4. Назначьте администраторов приложения, которые могут просматривать его пароль.
  5. Откройте консоль пользователя Indeed PAM и перейдите на вкладку Приложения.
  6. Просмотрите пароль от приложения и сохраните его.

Далее откройте любую среду для работы с Python и настройте доступ к серверу Indeed PAM.

Быстрый старт​

from pam_aapm import PamClient

# Использование контекстного менеджера (рекомендуется)
with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    # Получение пароля
    db_password = client.get_password("DB-SERVER/admin")

    # Получение SSH-ключа
    ssh_key = client.get_ssh_key("LINUX-SERVER/deploy")

    # Получение списка доступных учетных записей
    accounts = client.get_accounts()
    for account in accounts:
        print(f"{account.display_name}: password={account.has_password}, key={account.has_key}")

Аутентификация​

PamClient — основной класс Python SDK для взаимодействия с Indeed PAM. Он предоставляет API для аутентификации и получения учетных данных. Чтобы установить соединение с сервером PAM и получить токены доступа, укажите для класса PamClient параметры из таблицы.

Параметры PamClient
ПараметрПеременная окруженияТребование
Описание
idp_urlPAM_IDP_SERVERОбязательныйURL-адрес компонента Indeed PAM IdP
core_urlPAM_CORE_SERVERОбязательныйURL-адрес компонента Indeed PAM Core
usernamePAM_USERNAMEОбязательныйНазвание приложения
passwordPAM_PASSWORDОбязательныйПароль указанного приложения. Администратор приложения может просмотреть пароль в консоли пользователя.
client_id
—
НеобязательныйИдентификатор клиентского приложения, которое запрашивает токен.
Значение по умолчанию: "aapm-tool".
scope
—
НеобязательныйЗапрос на доступ к API по протоколу OAuth2.
Значение по умолчанию: "pam-api".
verify_sslPAM_VERIFY_SSLНеобязательныйПроверка SSL-сертификата сервера:
  • True — требуется;
  • False — не требуется.
Значение по умолчанию: True.

Примечание: Включенная проверка уменьшает риск перехвата данных. Если вы отключили проверку — рекомендуется обратить на это внимание в скрипте и оставить комментарий.
ca_certPAM_CA_CERTНеобязательныйПуть к сертификату для проверки SSL-соединения. Укажите, если сервер PAM использует сертификат, подписанный внутренним УЦ. Сертификат должен быть в формате PEM.
Пример: ca_cert="/path/to/ca.crt".
Значение по умолчанию: None.
timeout
—
НеобязательныйВремя ожидания ответа на запрос, сек.
Значение по умолчанию: 30.0.
accounts_cache_ttl
—
НеобязательныйВремя жизни (TTL) кеша учетных записей, сек.
Значение по умолчанию: 300.

После настройки доступа вызовите один из методов, чтобы получить учетные данные.

Примечание

Рекомендуется использовать контекстный менеджер with.
В таком случае соединение с PAM закрывается автоматически, а токены доступа удаляются.

Пример с параметрами аутентификации
from pam_aapm import PamClient

with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    password = client.get_password("SERVER/account")
Пример с переменными окружения (рекомендуется для CI/CD-автоматизаций)
import os
from pam_aapm import PamClient

with PamClient(
    idp_url=os.environ["PAM_IDP_SERVER"],
    core_url=os.environ["PAM_CORE_SERVER"],
    username=os.environ["PAM_USERNAME"],
    password=os.environ["PAM_PASSWORD"],
    verify_ssl=os.environ.get("PAM_VERIFY_SSL", "true").lower() == "true",
    ca_cert=os.environ.get("PAM_CA_CERT"),
) as client:
    password = client.get_password("SERVER/account")

Методы​

Примечание

Асинхронный вызов функций не поддерживается.

Методы Python SDK позволяют получить из Indeed PAM:

get_password()​

Метод отправляет API-запрос к Indeed PAM и возвращает пароль указанной учетной записи.

get_password(account_name, reason=None)
Параметры get_password()
ПараметрТребование
Описание
account_nameОбязательныйИмя учетной записи в формате:
  • LOCATION/username — рекомендуемый формат;
  • LOCATION\username — требует экранирования в Python-скриптах, например "DB-SERVER\\admin".
reasonНеобязательныйПричина получения учетных данных. Указание причины определяется политикой, действующей на учетную запись.
Значение по умолчанию: None.
from pam_aapm import PamClient

with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    # Получение пароля
    password = client.get_password("DB-SERVER/db_admin")

    # Получение пароля, если требуется указать причину
    password = client.get_password(
        "PROD-SERVER/admin",
        reason="Плановое обслуживание"
    )

get_ssh_key()​

Метод отправляет API-запрос к Indeed PAM и возвращает SSH-ключ указанной учетной записи.

get_ssh_key(account_name, decrypt=True, reason=None)
Параметры get_ssh_key()
ПараметрТребование
Описание
account_nameОбязательныйИмя учетной записи в формате:
  • LOCATION/username — рекомендуемый формат;
  • LOCATION\username — требует экранирования в Python-скриптах, например "DB-SERVER\\admin".
decryptНеобязательныйВернуть расшифрованный SSH-ключ:
  • True — вернуть;
  • False — не возвращать.
Значение по умолчанию: True.
reasonНеобязательныйПричина получения учетных данных. Указание причины определяется политикой, действующей на учетную запись.
Значение по умолчанию: None.
Параметры ответа
ПараметрОписание
Если в запросе decrypt=True
keySSH-ключ учетной записи в формате PEM
Если в запросе decrypt=False
keyЗашифрованный SSH-ключ
passphraseПароль зашифрованного ключа
file_nameИмя файла ключа
from pam_aapm import PamClient

with PamClient(
   idp_url="https://pam.company.com/idp",
   core_url="https://pam.company.com/core",
   username="my-app",
   password="app-password",
) as client:
   # Расшифрованный ключ
   key = client.get_ssh_key("LINUX-SERVER/automation")

   # Зашифрованный ключ с паролем
   key_data = client.get_ssh_key("LINUX-SERVER/automation", decrypt=False)
   print(f"Key: {key_data.key}")
   print(f"Passphrase: {key_data.passphrase}")

get_accounts()​

Метод используется для получения списка доступных учетных записей PAM. Список аккаунтов кешируется в соответствии с настроенным параметром accounts_cache_ttl в классе PamClient.

get_accounts(force_refresh=False)
Параметры get_accounts()
ПараметрТребование
Описание
force_refreshНеобязательныйПринудительное обновление кеша:
  • True — сбросить кеш;
  • False — не сбрасывать.
Значение по умолчанию: False.
Параметры ответа
Параметр
Описание
idИдентификатор учетной записи
display_nameИмя учетной записи
requires_reasonТребуется указать причину просмотра учетных данных:
  • true — требуется;
  • false — не требуется.
Указание причины определяется политикой, действующей на учетную запись.
has_passwordПароль учетной записи:
  • true — установлен;
  • false — не установлен.
has_keySSH-ключ учетной записи:
  • true — установлен;
  • false — не установлен.
is_key_supportedДля учетной записи доступно добавление SSH-ключа:
  • true — доступно;
  • false — недоступно.
from pam_aapm import PamClient
with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    accounts = client.get_accounts(force_refresh=False)

    for account in accounts:
        print(f"Учетная запись: {account.display_name}")
        print(f"  - Имеет пароль: {account.has_password}")
        print(f"  - Имеет SSH-ключ: {account.has_key}")
        print(f"  - Требует причину: {account.requires_reason}")

close()​

Метод освобождает системные ресурсы и вызывается автоматически при использовании контекстного менеджера with.

Если контекстный менеджер не используется, вызовите close(), когда соединение с PAM больше не требуется.

close()
Пример без использования контекстного менеджера
from pam_aapm import PamClient

# Создание экземпляра клиента
client = PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
)

password = client.get_password("DB-SERVER/db_admin")

client.close()

Исключения и обработка ошибок​

Исключения (Exceptions) — события, которые сообщают об ошибках во время выполнения скрипта. Обработка исключений позволяет перехватить ошибку без принудительного завершения программы.

Список исключений
ИсключениеОписание
AuthenticationErrorОшибка аутентификации в Indeed PAM.
Измените учетные данные или обновите токен доступа.
AccountNotFoundErrorУчетная запись не найдена или недоступна. Убедитесь, что учетная запись не удалена в Indeed PAM или имя учетной записи в запросе указано верно.
PasswordNotSetErrorПароль для учетной записи не установлен. Возникает при вызове метода get_password(), если у учетной записи не задан пароль.
SshKeyNotSetErrorSSH-ключ для учетной записи не установлен. Возникает при вызове метода get_ssh_key(), если у учетной записи не задан SSH-ключ.
ReasonRequiredErrorСогласно политике требуется указать причину запроса.
В запросе заполните параметр reason.
ConfigurationErrorОшибка конфигурации. Убедитесь, что URL-адреса для IdP и Core указаны верно, или добавьте в запрос недостающие параметры.
ApiErrorОшибка API-сервера. Изучите код ответа HTTP.
PamConnectionErrorОшибка подключения к серверу. Проверьте доступность компонентов IdP и Core.
ValidationErrorОшибка обработки входных данных.
Убедитесь, что компоненты IdP и Core доступны, а параметры запроса указаны верно.
Пример обработки исключений
from pam_aapm import (
    PamClient,
    AuthenticationError,
    AccountNotFoundError,
    PasswordNotSetError,
    ReasonRequiredError,
    SshKeyNotSetError,
    PamConnectionError,
    PamError,
)

try:
    with PamClient(
        idp_url="https://pam.company.com/idp",
        core_url="https://pam.company.com/core",
        username="my-app",
        password="app-password",
    ) as client:
        password = client.get_password("SERVER/account")

except AuthenticationError as e:
    print(f"Ошибка аутентификации: {e}")
except AccountNotFoundError as e:
    print(f"Учетная запись не найдена: {e.account_name}")
except PasswordNotSetError as e:
    print(f"Пароль не установлен: {e.account_name}")
except ReasonRequiredError as e:
    print(f"Требуется указать причину: {e.account_name}")
except SshKeyNotSetError as e:
    print(f"SSH-ключ не установлен: {e.account_name}")
except PamConnectionError as e:
    print(f"Ошибка подключения: {e}")
except PamError as e:
    print(f"Ошибка PAM: {e}")

Рекомендации по безопасности​

  1. Не храните учетные данные в скриптах. Для повышения безопасности используйте переменные окружения или хранилища секретов.
  2. Используйте контекстный менеджер with. В таком случае соединение с Indeed PAM закрывается автоматически, а токены доступа удаляются после обработки запроса.
  3. Проверка SSL-подключения включена по умолчанию. Отключайте проверку только для тестирования в изолированных средах.
  4. При логировании исключений обходите запись учетных данных, чтобы они не сохранялись в логах.