Сбер ID
Документация

Python SDK

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

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 перечислены здесь, для получения пользовательских данных - здесь.

Пример создания датаклассов
AUTHMACHINE = Authmachine(
issuer = "https://online.sberbank.ru/CSAFront/index.do",
authorization_endpoint = "https://csa-psi.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
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 можно найти здесь.

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

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

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

Реализация класса Client (пример для Flask)
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

Детализацию ошибок см. в п.1.2.4 , 1.3.4 "Описание ошибок" документации.

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