Documentation ¶
Overview ¶
OAuth2-клиент для запроса согласия и маркера доступа ЕСИА для получателей услуг ЕПГУ — физических лиц.
Методы ¶
- Client.AuthURI — формирует ссылку на страницу ЕСИА для предоставления пользователем запрошенных прав
- Client.ParseCallback — возвращает код авторизации из callback-запроса к redirect_uri
- Client.TokenExchange — обменивает код авторизации на маркер доступа (токен)
- Client.TokenUpdate — обновляет маркер доступа по идентификатору пользователя (OID)
Примеры ¶
- github.com/ofstudio/go-api-epgu/examples/esia-token-request — запрос согласия пользователя и получения маркера доступа
- github.com/ofstudio/go-api-epgu/examples/esia-token-update — обновление маркера доступа
Требования ¶
- Информационная система (ИС) должна быть зарегистрирована на Технологическом портале ЕСИА: продуктовом или тестовом (SVCDEV)
- Для ИС должен быть выпущен необходимый сертификат
- Публичная часть сертификата должна быть загружена на Технологический портал ЕСИА
- Выполнены все необходимые шаги регламента подключения ИС к тестовой или продуктовой среде ЕСИА и согласована заявка на доступ ИС к необходимым скоупам
Руководящие документы ¶
- Методические рекомендации по интеграции с REST API Цифрового профиля: https://digital.gov.ru/ru/documents/7166/
- Методические рекомендации по использованию ЕСИА: https://digital.gov.ru/ru/documents/6186/
- Руководство пользователя ЕСИА: https://digital.gov.ru/ru/documents/6182/
- Руководство пользователя технологического портала ЕСИА: https://digital.gov.ru/ru/documents/6190/
Адреса Технологического портала ЕСИА ¶
- Тестовая среда (SVCDEV): https://esia-portal1.test.gosuslugi.ru/console/tech
- Продуктовая среда: https://esia.gosuslugi.ru/console/tech/
Адреса Портала Госуслуг ¶
- Тестовая среда (SVCDEV): https://svcdev-beta.test.gosuslugi.ru
- Продуктовая среда: https://lk.gosuslugi.ru
Страница предоставленных согласий пользователя на Портале Госуслуг ¶
- Тестовая среда (SVCDEV): https://svcdev-betalk.test.gosuslugi.ru/settings/third-party/agreements/acting
- Продуктовая среда: https://lk.gosuslugi.ru/settings/third-party/agreements/acting
Index ¶
- Constants
- Variables
- type Client
- func (c *Client) AuthURI(scope, redirectURI string, permissions Permissions) (string, error)
- func (c *Client) ParseCallback(query url.Values) (string, string, error)
- func (c *Client) TokenExchange(code, scope, redirectURI string) (*TokenExchangeResponse, error)
- func (c *Client) TokenUpdate(oid, redirectURI string) (*TokenExchangeResponse, error)
- func (c *Client) WithDebug(logger utils.Logger) *Client
- func (c *Client) WithHTTPClient(httpClient *http.Client) *Client
- type ErrorResponse
- type Permission
- type PermissionAction
- type PermissionPurpose
- type PermissionScope
- type Permissions
- type TokenExchangeResponse
Constants ¶
const ( UserEndpoint = "/aas/oauth2/v2/ac" // URI страницы ЕСИА для предоставления пользователем запрошенных прав TokenEndpoint = "/aas/oauth2/v3/te" // Эндпоинт для обмена кода авторизации на маркер доступа )
Variables ¶
var ( ErrAuthURI = errors.New("ошибка при создании авторизационной ссылки") ErrParseCallback = errors.New("ошибка обратного вызова") ErrTokenExchange = errors.New("ошибка запроса токена") ErrTokenUpdate = errors.New("ошибка обновления токена") )
Ошибки первого уровня.
var ( ErrNoState = errors.New("отсутствует поле state") ErrGUID = errors.New("не удалось сгенерировать GUID") ErrSign = errors.New("ошибка подписания") ErrRequest = errors.New("ошибка HTTP-запроса") ErrJSONUnmarshal = errors.New("ошибка чтения JSON") ErrUnexpectedContentType = errors.New("неожиданный тип содержимого") )
Ошибки второго уровня.
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 ¶
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 и других:
Подробнее см "Методические рекомендации по использованию ЕСИА", раздел "Получение авторизационного кода (v2/ac)".
func (*Client) ParseCallback ¶
ParseCallback - возвращает код авторизации code и state из query-параметров callback-запроса к redirect_uri от ЕСИА.
Подробнее см "Методические рекомендации по использованию ЕСИА", раздел "Получение авторизационного кода (v2/ac)".
В случае ошибки возвращает цепочку из ErrParseCallback и других:
- ErrNoState - отсутствует параметр state
- ErrParseCallback - ошибка разбора параметров
- ошибка ЕСИА: ErrESIAxxxxxx (ErrESIA_007003 и др.)
Пример сообщения об ошибке:
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 и других:
- ErrSign - ошибка подписи запроса
- ErrGUID - при невозможности сформировать GUID
- ErrRequest - ошибка HTTP-запроса
- ErrJSONUnmarshal - ошибка разбора ответа
- ErrUnexpectedContentType - неожидаемый Content-Type ответа
- ошибок ЕСИА ErrESIA_xxxxxx (ErrESIA_007004 и др.)
Пример сообщения об ошибке:
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.
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 - ответ от ЕСИА при успешном обмене кода на маркер доступа