aas

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 19, 2023 License: MIT Imports: 11 Imported by: 0

README

go-api-epgu/esia/aas

OAuth2-клиент для запроса согласия и маркера доступа ЕСИА для получателей услуг ЕПГУ — физических лиц.

Методы

  • Client.AuthURI — формирует ссылку на страницу ЕСИА для предоставления пользователем запрошенных прав
  • Client.ParseCallback — возвращает код авторизации из callback-запроса к redirect_uri
  • Client.TokenExchange — обменивает код авторизации на маркер доступа (токен)
  • Client.TokenUpdate — обновляет маркер доступа по идентификатору пользователя (OID)

Примеры

Системные требования

  • Go 1.21+
  • Для подписания запросов к ЕСИА с помощью LocalCryptoPro — КриптоПро CSP 5.0+ и сертификат для подписания запросов

Регламентные требования

  1. Информационная система (ИС) должна быть зарегистрирована на Технологическом портале ЕСИА: продуктовом или тестовом (SVCDEV)
  2. Для ИС должен быть выпущен необходимый сертификат
  3. Публичная часть сертификата должна быть загружена на Технологический портал ЕСИА
  4. Выполнены все необходимые шаги регламента подключения ИС к тестовой или продуктовой среде ЕСИА и согласована заявка на доступ ИС к необходимым скоупам

Ссылки

Руководящие документы
  1. Методические рекомендации по интеграции с REST API Цифрового профиля
  2. Методические рекомендации по использованию ЕСИА
  3. Руководство пользователя ЕСИА
  4. Руководство пользователя технологического портала ЕСИА
Адреса Технологического портала ЕСИА
Адреса Портала Госуслуг
Страница предоставленных согласий пользователя на Портале Госуслуг

Documentation

Overview

OAuth2-клиент для запроса согласия и маркера доступа ЕСИА для получателей услуг ЕПГУ — физических лиц.

Методы

  • Client.AuthURI — формирует ссылку на страницу ЕСИА для предоставления пользователем запрошенных прав
  • Client.ParseCallback — возвращает код авторизации из callback-запроса к redirect_uri
  • Client.TokenExchange — обменивает код авторизации на маркер доступа (токен)
  • Client.TokenUpdate — обновляет маркер доступа по идентификатору пользователя (OID)

Примеры

Требования

  1. Информационная система (ИС) должна быть зарегистрирована на Технологическом портале ЕСИА: продуктовом или тестовом (SVCDEV)
  2. Для ИС должен быть выпущен необходимый сертификат
  3. Публичная часть сертификата должна быть загружена на Технологический портал ЕСИА
  4. Выполнены все необходимые шаги регламента подключения ИС к тестовой или продуктовой среде ЕСИА и согласована заявка на доступ ИС к необходимым скоупам

Руководящие документы

  1. Методические рекомендации по интеграции с REST API Цифрового профиля: https://digital.gov.ru/ru/documents/7166/
  2. Методические рекомендации по использованию ЕСИА: https://digital.gov.ru/ru/documents/6186/
  3. Руководство пользователя ЕСИА: https://digital.gov.ru/ru/documents/6182/
  4. Руководство пользователя технологического портала ЕСИА: https://digital.gov.ru/ru/documents/6190/

Адреса Технологического портала ЕСИА

Адреса Портала Госуслуг

Страница предоставленных согласий пользователя на Портале Госуслуг

Index

Constants

View Source
const (
	UserEndpoint  = "/aas/oauth2/v2/ac" // URI страницы ЕСИА для предоставления пользователем запрошенных прав
	TokenEndpoint = "/aas/oauth2/v3/te" // Эндпоинт для обмена кода авторизации на маркер доступа
)

Variables

View Source
var (
	ErrAuthURI       = errors.New("ошибка при создании авторизационной ссылки")
	ErrParseCallback = errors.New("ошибка обратного вызова")
	ErrTokenExchange = errors.New("ошибка запроса токена")
	ErrTokenUpdate   = errors.New("ошибка обновления токена")
)

Ошибки первого уровня.

View Source
var (
	ErrNoState               = errors.New("отсутствует поле state")
	ErrGUID                  = errors.New("не удалось сгенерировать GUID")
	ErrSign                  = errors.New("ошибка подписания")
	ErrRequest               = errors.New("ошибка HTTP-запроса")
	ErrJSONUnmarshal         = errors.New("ошибка чтения JSON")
	ErrUnexpectedContentType = errors.New("неожиданный тип содержимого")
)

Ошибки второго уровня.

View Source
var (
	ErrESIA_036700 = errors.New("ESIA-036700: Не указана мнемоника типа согласия")
	ErrESIA_036701 = errors.New("ESIA-036701: Не найден тип согласия")
	ErrESIA_036702 = errors.New("ESIA-036702: Не указан обязательный скоуп для типа согласия")
	ErrESIA_036703 = errors.New("ESIA-036703: Указанные скоупы выходят за рамки разрешенных для типа согласия")
	ErrESIA_036704 = errors.New("ESIA-036704: Запрещено указывать скоупы для типа согласия")
	ErrESIA_036705 = errors.New("ESIA-036705: Необходимо указать хотя бы одно действие")
	ErrESIA_036706 = errors.New("ESIA-036706: Указанное действие не существует")
	ErrESIA_036707 = errors.New("ESIA-036707: Необходимо указать хотя бы одну цель")
	ErrESIA_036716 = errors.New("ESIA-036716: Указано некорректное время истечения срока действия согласия")
	ErrESIA_036726 = errors.New("ESIA-036726: Указанная цель не существует")
	ErrESIA_036727 = errors.New("ESIA-036727: Необходимо указать одну цель согласия")
	ErrESIA_007002 = errors.New("ESIA-007002: Несоответствие сертификата и мнемоники информационной системы или отсутствие сертификата для данной системы в ЕСИА")
	ErrESIA_007003 = errors.New("ESIA-007003: В запросе отсутствует обязательный параметр, запрос включает в себя неверное значение параметра \nили включает параметр несколько раз\n")
	ErrESIA_007004 = errors.New("ESIA-007004: Владелец ресурса или сервис авторизации отклонил запрос")
	ErrESIA_007005 = errors.New("ESIA-007005: Система-клиент не имеет права запрашивать получение маркера доступа таким методом")
	ErrESIA_007006 = errors.New("ESIA-007006: Запрошенная область доступа (scope) указана неверно, неизвестно или сформирована некорректно")
	ErrESIA_007007 = errors.New("ESIA-007007: Возникла неожиданная ошибка в работе сервиса авторизации, которая привела к невозможности выполнить запрос")
	ErrESIA_007008 = errors.New("ESIA-007008: Сервис авторизации в настоящее время не может выполнить запрос из-за большой нагрузки или технических работ на сервере")
	ErrESIA_007009 = errors.New("ESIA-007009: Сервис авторизации не поддерживает получение маркера доступа этим методом")
	ErrESIA_007011 = errors.New("ESIA-007011: Авторизационный код или маркер обновления недействителен, просрочен, отозван или не соответствует адресу ресурса, указанному в запросе на авторизацию, или был выдан другой системе-клиенту")
	ErrESIA_007012 = errors.New("ESIA-007012: Тип авторизационного кода не поддерживается сервисом авторизации")
	ErrESIA_007013 = errors.New("ESIA-007013: Запрос не содержит указания на область доступа (scope)")
	ErrESIA_007014 = errors.New("ESIA-007014: Запрос не содержит обязательного параметра")
	ErrESIA_007015 = errors.New("ESIA-007015: Неверное время запроса")
	ErrESIA_007019 = errors.New("ESIA-007019: Отсутствует разрешение на доступ")
	ErrESIA_007023 = errors.New("ESIA-007023: Указанный в запросе <redirect_uri> отсутствует среди разрешенных для ИС")
	ErrESIA_007038 = errors.New("ESIA-007038: Ошибка получения параметров из запроса")
	ErrESIA_007039 = errors.New("ESIA-007039: В изначальном запросе на /v2/ac, параметр <code_challenge> не был указан")
	ErrESIA_007040 = errors.New("ESIA-007040: Ошибка сравнения исходного и контрольного значений")
	ErrESIA_007046 = errors.New("ESIA-007046: Запрос otp невозможен, а в области доступа (scope) указано обязательное прохождение пользователем двухфакторной авторизации, недоступный пользователю")
	ErrESIA_007053 = errors.New("ESIA-007053: client_secret сформирован некорректно. client_secret не соответствует строке-сертификату, информационной системе или используемый сертификат не активен")
	ErrESIA_007055 = errors.New("ESIA-007055: Вход в систему осуществляется с неподтвержденной учетной записью")
	ErrESIA_007060 = errors.New("ESIA-007060: Значение параметра <roles> в запросе указано неверно")
	ErrESIA_007061 = errors.New("ESIA-007061: Значение параметра <obj_type> в запросе указано неверно")
	ErrESIA_007062 = errors.New("ESIA-007062: Тип или роль пользователя в запросе указана неверно")
	ErrESIA_007194 = errors.New("ESIA-007194: Запрос области доступа для организации, сотрудником которой пользователь не является ")
	ErrESIA_008010 = errors.New("ESIA-008010: Не удалось произвести аутентификацию системы-клиента")

	// Неизвестная ошибка ЕСИА
	ErrESIA_unknown = errors.New("неизвестная ошибка ЕСИА")
)

Ошибки ЕСИА.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client - OAuth2-клиент для запроса согласия и маркера доступа ЕСИА для получателей услуг ЕПГУ - физических лиц.

func NewClient

func NewClient(baseURI, clientId string, signer signature.Provider) *Client

NewClient - конструктор для Client. Параметры:

  • baseURI - URI ЕСИА
  • clientId - мнемоника ИС-потребителя
  • signer - провайдер подписи запросов

func (*Client) AuthURI

func (c *Client) AuthURI(scope, redirectURI string, permissions Permissions) (string, error)

AuthURI - формирует URI на страницу ЕСИА для предоставления пользователем запрошенных прав. Тк используется параметр Permissions, то в scope необходимо указывать "openid".

Возвращает URI на страницу ЕСИА либо цепочку ошибок из ErrAuthURI и других:

  • ErrSign - ошибка подписи ссылки
  • ErrGUID - при невозможности сформировать GUID

Подробнее см "Методические рекомендации по использованию ЕСИА", раздел "Получение авторизационного кода (v2/ac)".

func (*Client) ParseCallback

func (c *Client) ParseCallback(query url.Values) (string, string, error)

ParseCallback - возвращает код авторизации code и state из query-параметров callback-запроса к redirect_uri от ЕСИА.

Подробнее см "Методические рекомендации по использованию ЕСИА", раздел "Получение авторизационного кода (v2/ac)".

В случае ошибки возвращает цепочку из ErrParseCallback и других:

Пример сообщения об ошибке:

ESIA-007014: Запрос не содержит обязательного параметра [error='invalid_request', error_description='ESIA-007014: The request does not contain the mandatory parameter' state='48d1a8dc-0b7d-418a-b4ef-2c7797f77dc9']'

func (*Client) TokenExchange

func (c *Client) TokenExchange(code, scope, redirectURI string) (*TokenExchangeResponse, error)

TokenExchange обменивает код авторизации на маркер доступа. Параметры scope и redirectURI должны быть такими же, как и при вызове Client.AuthURI.

Подробнее см "Методические рекомендации по использованию ЕСИА", раздел "Получение маркера доступа в обмен на авторизационный код (v3/te)".

Возвращает ответ от ЕСИА TokenExchangeResponse либо цепочку ошибок из ErrTokenExchange и других:

Пример сообщения об ошибке:

HTTP 400 Bad request: ESIA-007014: Запрос не содержит обязательного параметра [error='invalid_request', error_description='ESIA-007014: The request does not contain the mandatory parameter' state='48d1a8dc-0b7d-418a-b4ef-2c7797f77dc9']'

func (*Client) TokenUpdate

func (c *Client) TokenUpdate(oid, redirectURI string) (*TokenExchangeResponse, error)

TokenUpdate обновляет маркер доступа по идентификатору пользователя (OID), используя scope="prm_chg". Параметр redirectURI должен быть таким же, как и при вызове AuthURI.

Подробнее см "Методические рекомендации по интеграции с REST API Цифрового профиля" раздел "Online-режим запроса согласий".

Возвращает ответ от ЕСИА TokenExchangeResponse либо цепочку ошибок из ErrTokenUpdate и ошибок аналогичных TokenExchange.

func (*Client) WithDebug

func (c *Client) WithDebug(logger utils.Logger) *Client

WithDebug - включает логирование запросов и ответов Формат лога:

>>> Request to {url}
...
{полный HTTP-запрос}
...
<<< Response from {url}
...
{полный HTTP-ответ}
...

func (*Client) WithHTTPClient

func (c *Client) WithHTTPClient(httpClient *http.Client) *Client

WithHTTPClient - устанавливает http-клиент для запросов к ЕСИА

type ErrorResponse

type ErrorResponse struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description"`
	State            string `json:"state"`
}

ErrorResponse - ответ от ЕСИА при ошибке

type Permission

type Permission struct {
	ResponsibleObject string              `json:"responsibleObject,omitempty"` // Ответственный объект (название организации)
	Sysname           string              `json:"sysname"`                     // Мнемоника типа согласия
	Expire            int                 `json:"expire,omitempty"`            // Срок, на который будет выдано согласие после утверждения (в минутах)
	Actions           []PermissionAction  `json:"actions"`                     // Перечень мнемоник действий
	Purposes          []PermissionPurpose `json:"purposes"`                    // Перечень мнемоник целей согласия
	Scopes            []PermissionScope   `json:"scopes"`                      // Перечень мнемоник областей доступа
}

Permission - разрешение на доступ к ресурсу.

Подробнее см "Методические рекомендации по интеграции с REST API Цифрового профиля", раздел "Структура JSON-объекта параметра «permissions»".

type PermissionAction

type PermissionAction struct {
	Sysname string `json:"sysname"`
}

PermissionAction - мнемоника действия объекта Permission.

type PermissionPurpose

type PermissionPurpose struct {
	Sysname string `json:"sysname"`
}

PermissionPurpose - мнемоника цели согласия объекта Permission.

type PermissionScope

type PermissionScope struct {
	Sysname string `json:"sysname"`
}

PermissionScope - мнемоника области доступа объекта Permission.

type Permissions

type Permissions []Permission

Permissions - список запрашиваемых прав доступа.

Подробнее см "Методические рекомендации по интеграции с REST API Цифрового профиля", раздел "Структура JSON-объекта параметра «permissions»".

func (Permissions) Base64String

func (p Permissions) Base64String() string

Base64String - кодирует список запрашиваемых разрешений в строку base64

type TokenExchangeResponse

type TokenExchangeResponse struct {
	AccessToken string `json:"access_token"`
	IdToken     string `json:"id_token"`
	State       string `json:"state"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"`
}

TokenExchangeResponse - ответ от ЕСИА при успешном обмене кода на маркер доступа

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL