Python SDK

Обновлено 7 апреля 2025

Общие сведения

Python библиотека для серверных приложений, упрощающая получение Access Token и UserInfo.

Установка

Python документация по установке пакетов расположена на сайте packaging.python.org

Установка через pip:

python setup.py sdist
pip install dist\pySberId-{version}.tar.gz

Установка из исходников через setuptools:

python setup.py install

Использование

Необходимый импорт

from sberid.client import Client, Consumer, Authmachine
from sberid.pkce import  PKCEData, PKCEMethod
from sberid.apiresponse import AuthorizationResponse

Создание API-клиента

Датаклассы Consumer и Authmachine

Класс Consumer описывает параметры потребителя сервиса:

1. client_id - Уникальный идентификатор потребителя
2. client_secret - Пароль доступа к API
3. client_crt - Путь к TLS сертификату (может быть None)
4. client_pass - Пароль к TLS сертификату (может быть None)

Класс Authmachine описывает параметры сервиса аутентификации:

1. issuer - URL-адрес, который сервис аутентификации утверждает в качестве своего идентификатора.
2. authorization_endpoint - URL точки аутентификации
3. token_endpoint - URL точки получения ID token, access token
4. userinfo_endpoint- URL точки получения пользовательских данных

Адреса для получения ID token, access token перечислены в Шлюзы вызова API(), для получения пользовательских данных в Шлюзы вызова API()

AUTHMACHINE = Authmachine(
    issuer = "https://online.sberbank.ru/CSAFront/index.do",
    authorization_endpoint = "https://csa-ift.testonline.sberbank.ru:9445/CSAFront/oidc/authorize.do",
    token_endpoint = "https://api.sberbank.ru/ru/prod/tokens/v2/oidc", # url на получение access token (для подключений через двусторонний TLS)
                    # https://sec.api.sberbank.ru/ru/prod/tokens/v2/oidc - для подключений через ФПСУ
    userinfo_endpoint = "https://api.sberbank.ru/ru/prod/sberbankid/v2.1/userInfo" # url на получение пользовательских данных (для подключений через двусторонний TLS)
                    # https://sec.api.sberbank.ru/ru/prod/sberbankid/v2.1/userinfo - для подключений через ФПСУ
)
CONSUMER = Consumer(
    client_id = "6a0e103b-1873-4ed5-9903-b4fb51192b23", # нужно поменять на свой
    client_secret = "oYBjtOQmQNX4cMAmnKxAnvoGrWeccGKzKxvCKqtm0jQ", # нужно поменять на свой
    client_crt = r"cert.p12",
    client_pass = "put_your_password_here"
)

Классы PKCEData и PKCEMethod

Вспомогательные классы для повышения защищенности передачи данных пользователя с использованием алгоритма PKCE.

pkce = PKCEData(PKCEMethod.S256, 64)
# code_verifier требуется сохранить для последующих запросов
session["pkce"] = pkce.code_verifier
url = client.get_authorization_url(CONSUMER_SCOPE, redirect_url, pkce)

Client и AuthorizationResponse

Абстрактный класс Client реализует основные методы для взаимодействия с сервисом аутентификации и получения пользовательских данных:

Метод get_authorization_url

Формирование URL адреса аутентификации пользователя. Принимает следующие параметры:

1. scope - Запрашиваемые наборы данных
2. redirect_uri - URL возврата к потребителю
3. pkce - PKCE верификатор (может быть None)

Метод get_userinfo

Получение данных пользователя. Возвращаемое значение - словарь с полученными параметрами. Принимает следующие параметры:

1. redirect_url: URL возврата к потребителю
2. code_verifier: PKCE верификатор (может быть None)

Полное описание параметров ответа на запрос access token, ID token можно найти в Параметры ответа().

Полное описание параметров ответа на запрос данных пользователя можно найти в Параметры ответа() документации.

Абстрактный метод get_authorization_response

Преобразование запроса с полученным пользователем AuthCode в экземпляр AuthorizationResponse. Не принимает параметров.

class AuthMachineClient(Client):

    def get_authorization_response(self):
        return AuthorizationResponse(
            code=request.args.get("code"),
            error=request.args.get("error"),
            state=request.args.get("state"),
            nonce=request.args.get("nonce")
            )

Ошибки

Все исключения, генерируемые библиотекой являются наследниками класса SberAPIException

Детализацию ошибок см. в Описание ошибок запроса access token и id token() и Описание ошибок запроса на получение данных().

AuthException

Исключение бросается при получении обратного редиректа с непустым параметром error

APIErrorResponse

Исключение бросается при неуспешном вызове конечных точек token и userinfo

Логгирование

Класс Client принимает не обязательный параметр logger в конструкторе. В случае его отсутствия используется стандартный логгер.

from logging.config import dictConfig
dictConfig({
    "version": 1,
    "formatters": {
      "default": {
        "format": "[%(asctime)s] %(levelname)s in %(module)s: %(message)s"
      }
    },
    "handlers": {
      "console": {
        "class": "logging.StreamHandler",
        "level": "DEBUG",
        "formatter": "default",
        "stream": "ext://sys.stderr"
      }
    },
    "root": {
      "level": "DEBUG",
      "handlers": ["console"]
    }
  })

Пример

Полный пример с использованием фреймворка Flask содержится в исходном коде библиотеки.

Получение адреса аутентификации пользователя:

client = AuthMachineClient(CONSUMER, AUTHMACHINE)
    pkce = PKCEData(PKCEMethod.S256, 64)
    # необходимо сохранить code_verifier для последующей проверки
    session["pkce"] = pkce.code_verifier
    url = client.get_authorization_url(CONSUMER_SCOPE, redirect_url, pkce)

Получение данных пользователя после его успешной аутентификации::

client = AuthMachineClient(CONSUMER, AUTHMACHINE)
user_info = client.get_userinfo(redirect_url, session.get("pkce"))

Файл Python SDK

Версия	Описание изменений	Файл	Дата
0.0.1	Реализовано получение Access Token и UserInfo	SberbankID_SDK_Python_v.0.0.1.zip	12.02.2020