Аутентификация через ЕСИА

КриптоПро Ключ позволяет использовать Единую Систему Идентификации и Аутентификации (ЕСИА) Единого Портала Государственных Услуг (ЕПГУ) для аутентификации своих пользователей.

Во время процесса аутентификации Центр Идентификации КриптоПро Ключ выступает в качестве Информационной Системы (ИС), ЕСИА выступает в качестве Стороннего Центра Идентификации (СЦИ).

Исходные данные

Перед началом настройки аутентификации через ЕСИА необходимо убедиться в наличии следующих данных:

Мнемоника ИС, полученная при регистрации в ЕСИА.
Сертификат подписи запросов ИС.
В настройках ИС должны быть зарегистрированы следующие адреса перенаправления:
- https://host/appName/esia-signin-oidc,
- https://host/appName/esia-signout-callback-oidc,
host - адрес сервера КриптоПро Ключ, appName - имя приложения ЦИ.
Для ИС должна быть разрешена как минимум "область доступа" openid.

ЕСИА предоставляет два набора сервисов, отличающихся адресом сервера:

Промышленный сервер: esia.gosuslugi.ru,
Тестовый сервер (ТЕСИА): esia-portal1.test.gosuslugi.ru.

Регистрация ЕСИА как СЦИ

Для регистрации ЕСИА в качестве СЦИ необходимо выполнить следующие команды.

$addIdpArgs = @{
    IssuerName = "tesia"
    Name = "Вход через ТЕСИА"
    Description = "Вход через тестовый портал Госуслуг"
    IssuerAltNames = @(
        "http://esia-portal1.test.gosuslugi.ru/"
    )
}
Add-IdsIdentityProvider @addIdpArgs

$setEsiaArgs = @{
    IssuerName = "tesia"
    ClientId = "771301_3T"
    FilePath = "~/esia/client.pfx"
    Password = "123456"
    Scopes = "openid fullname"
    AuthorizationEndpoint = "https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v2/ac"
    TokenEndpoint = "https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v3/te"
    EndSessionEndpoint = "https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout"
    UserInfoEndpoint = "https://esia-portal1.test.gosuslugi.ru/rs/prns"
}
Set-IdsIdentityProviderEsiaEndpoint @setEsiaArgs
Set-IdsIdentityProvider -IssuerName tesia -ShowInUi $true

$addIdpCert = @{
    Id = (Get-IdsIdentityProvider -IssuerName tesia).Id
    Certificate = "~/esia/TESIA GOST 2012_new.cer"
}
Add-IdsIdentityProviderSigningCertificate @addIdpCert

В приведенных выше командах используется адрес TЕСИА. При использовании промышленного сервера структура адреса остается неизменной, меняется только адрес сервера. Соответствие адресов приведено в таблице ниже.

Конечная точка	Адрес в ТЕСИА	Адрес в ЕСИА
Получение кода авторизации	https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v2/ac	https://esia.gosuslugi.ru/aas/oauth2/v2/ac
Получение маркеров	https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v3/te	https://esia.gosuslugi.ru/aas/oauth2/v3/te
Завершение сессии	https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout	https://esia.gosuslugi.ru/idp/ext/Logout
Получение ПДн пользователя	https://esia-portal1.test.gosuslugi.ru/rs/prns	https://esia.gosuslugi.ru/rs/prns

Для обеспечения возможности корректной проверки маркеров идентификации, выпускаемых ЕСИА, при выполнении команды Add-IdsIdentityProvider обязательно указание параметра -IssuerAltNames со следующим значением:

Для ТЕСИА: http://esia-portal1.test.gosuslugi.ru/,
Для ЕСИА: http://esia.gosuslugi.ru/.

Аутентификация пользователей КриптоПро Ключ через ЕСИА/ТЕСИА работает только при использовании интерактивных вариантов взаимодействия (через страницу входа Центра Идентификации КриптоПро Ключ), поэтому параметр -ShowInUi для добавляемого СЦИ должен быть равен $true, данное значение можно указать только после настроек, выполняемых командлетом Set-IdsIdentityProviderEsiaEndpoint.

Для корректного прохождения всех шагов аутентификации необходимо обязательно указать следующие параметры командлета Set-IdsIdentityProviderEsiaEndpoint:

ClientId - мнемоника ИС, зарегистрированная в ЕСИА (как правило, в ТЕСИА регистрируется мнемоника, отличная от промышленного сервера).
FilePath - путь до PFX с сертификатом и ключом подписи запросов ИС.
Password - пароль для доступа к ключу подписи запросов ИС.
Scopes - требуемые "области доступа", разрешенные ИС. Для корректной работы требуется указать как минимум значение openid.
AuthorizationEndpoint - адрес конечной точки получения кодов авторизации (поддерживается только работа с конечной точкой версии v2).
TokenEndpoint - адрес конечной точки получения маркеров (поддерживается только работа с конечной точкой версии v3).
EndSessionEndpoint - конечная точка завершения сессии пользователя.
UserInfoEndpoint - конечная точка получения информации о пользователе.

Командлет Set-IdsIdentityProviderEsiaEndpoint позволяет указать следующие необязательные параметры:

RequireTrustedAccount - значение $true указывает, что доступ к КриптоПро Ключ разрешен только для подтвержденных учетных записей ЕСИА.

Сертификаты проверки маркера идентификации распространяются через zip-архив с сайта ЕСИА, набор сертификатов пополняется. Перед началом настройки требуется получить актуальный перечень сертификатов, адрес для распространения zip-архива можно найти в документе "МЕТОДИЧЕСКИЕ РЕКОМЕНДАЦИИ ПО ИСПОЛЬЗОВАНИЮ ЕСИА".

КриптоПро Ключ позволяет указывать несколько сертификатов проверки, для этого каждый сертификат может быть добавлен отдельным вызовом командлета Add-IdsIdentityProviderSigningCertificate.

Особенности использования областей доступа ЕСИА

После успешного завершения аутентификации Центр Идентификации КриптоПро Ключ получает сведения об учетной записи пользователя. Объем сведений, доступный для дальнейшей обработки, определяется так называемыми областями доступа (scope).

Каждой области доступа соответствуют некоторые данные из учетной записи пользователя ЕПГУ, которые помещаются в утверждения (claim) результирующего маркера, к утверждениям можно применять правила преобразования (claims transformation rules).

КриптоПро Ключ поддерживает работу со следующими областями доступа:

Область доступа	Данные пользователя	Утверждения
openid	OID*	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
fullname	ФИО	esia.identity.firstName esia.identity.lastName esia.identity.middleName
snils	СНИЛС	esia.identity.snils
inn	ФИО	esia.identity.inn
email	Электронная почта	esia.contacts.MBT.value
mobile	Номер мобильного телефона	esia.contacts.EML.value

Минимальная область доступа, позволяющая проводить аутентификацию пользователей - openid.

*OID - это уникальный идентификатор пользователя на портале Госуслуг, представляющий собой последовательность цифр.

Для успешной аутентификации пользователя в КриптоПро Ключ из СЦИ требуется передать два утверждения: имя (логин) и роль пользователя, поэтому настройка правил преобразования утверждений является обязательной при использовании ЕСИА.

Пример

В данном примере в качестве логина пользователя настраивается ИНН и безусловно считается, что все пользователи имеют роль Пользователи (Users). Содержимое файла с правилами преобразования утверждений:

[
    {
        "Name":"INN as unique_name",
        "Rules" : [
            "c:[type==\"esia.identity.inn\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name\", value=c.value);"
        ]
    },
    {
        "Name":"Role Users",
        "Rules" : [
            "=>issue(type=\"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\", value=\"Users\");"
        ]
    }

Путь к данному файлу требуется указать при настройке СЦИ:

Set-IdsIdentityProvider -IssuerName tesia -ClaimsTransformRulesFile ~/esia/claims.txt"

Для составления правил следует использовать типы утверждений, указанные таблице выше. В примере используется тип утверждения esia.identity.inn:

...
"c:[type==\"esia.identity.inn\"]...
...

Ограничение доступа для неподтвержденных учетных записей

При аутентификации через ЕСИА можно разрешить доступ только пользователям с подтвержденными учетным записями на портале ЕПГУ, для этого необходимо выполнить следующую команду.

Set-IdsIdentityProviderEsiaEndpoint -IssuerName tesia -RequireTrustedAccount $true