Аутентификация через сторонние ЦИ

СЭП поддерживает аутентификацию в сторонних ЦИ по двум протоколам:

  1. WS-Federation (далее WsFed)
  2. OpenId Connect 1.0 (далее Oidc)

Настройка доверия к стороннему ЦИ

Настройка доверия к стороннему ЦИ осуществляется Администратором через PowerShell с помощью следующих командлетов:

  • Add-IdsIdentityProvider - добавление нового доверенного ЦИ.
  • Set-IdsIdentityProvider - изменение параметров существующего доверенного ЦИ.
  • Get-IdsIdentityProvider - отображение списка доверенных ЦИ.
  • Remove-IdsIdentityProvider - удаление доверенного ЦИ из списка.
  • Disable-IdsIdentityProvider - отключение довернного ЦИ.
  • Enable-IdsIdentityProvider - включение доверенного ЦИ.
  • Set-IdsIdentityProviderOidcEndpoint - изменение настроек аутентификации протокола Oidc.
  • Set-IdsIdentityProviderWsDedEndpoint - изменение настроек аутентификации протокола WsFed.

Настройка аутентификации по протоколу OpenId Connect 1.0

Для подключения стороннего ЦИ по протоколу Oidc необходимы следующие данные:

  1. URL-адрес конечной точки авторизации (AuthorizationEndpoint).
  2. URL-адрес конечной точки распространения набора ключей (JwksUri).
  3. Самоназвание стороннего ЦИ (Issuer).
  4. Идентификатор клиента (ClientId).
  5. Секрет клиента (ClientSecret).
  6. Запрашиваемые области использования (Scopes).

Использование Google в качестве стороннего ЦИ

Для примера подключим в качестве стороннего ЦИ Google.

Сначала необходимо зарегистрировать сервер, как Oauth-клиент в сервисе Google. Для этого требуется зайти в консоль разработчика Google и создать новый проект, нажав на кнопку Create Project:

После создания проекта нужно включить API, к которому СЭП в качестве OAuth 2.0 клиента будет запрашивать доступ. Таким API является Google+. Для включения API нужно нажать кнопку ENABLE APIS AND SERVICES

и найти в поиске Google+ API

Следующим шагом является добавление учетных данных клиента для доступа к API. Для добавления необходимо нажать на кнопку CREATE CREDENTIALS

В появившемся мастере можно сразу перейти к настройке Client Id, нажав на ссылку client ID в первом пункте

Прежде чем ввести параметры OAuth клиента, требуется задать данные, отображаемые на экране согласия (consent screen). На этом экране пользователю будет предложено предоставить доступ серверу к запрашиваемым данным при аутентификации. Обязательными для заполнения являются адрес электронной почты владельца сервера и отображаемое название сервиса.

После указания данных для экрана согласия можно указать параметры сервиса для протокола OAuth. Из обязательных полей имя клиента (отображается в списке подключенных клиентов в консоли разработчика) и адрес перенаправления. Также необходимо указать тип клиента Web Application. Адрес перенаправления имеет вид https://<host>/<sts_appname>/Authentication/External.

После создания клиента появится диалог, отображающий присвоенный client_id и client_secret, данный диалог можно игнорировать. Вместо этого удобно скачать параметры подключения в виде JSON-документа.

Внутри JSON-документ содержит параметры OAuth клиента и адреса конечных точек, из которых интересует конечная точка авторизации (параметр auth_uri) https://accounts.google.com/o/oauth2/auth и URL для получения сертификатов подписи маркеров безопасности (параметр auth_provider_x509_cert_url) https://www.googleapis.com/oauth2/v1/certs.

По ссылке auth_provider_x509_cert_url можно получить список сертификатов в формате BASE64. Их необходимо установить в хранилище Доверенные лица локального компьютера, а их отпечатки прописать в параметрах подключенного стороннего ЦИ.

Однако следует отметить, что Google меняет свои сертификаты достаточно часто (примерно раз в 3 недели), поэтому можно настроить динамическое обновление ключей проверки маркеров. Для этого в параметрах ЦИ следует указать адрес распространения набора ключей подписи маркеров JwksUri, для Google этот адрес имеет значение https://www.googleapis.com/oauth2/v3/certs.

Для проверки маркера СЭП пытается найти сертификат ключа проверки среди зарегистрированных сертификатов, если это не удается сделать, из маркера извлекается "самоназвание" ЦИ (для Google это accounts.google.com) и по нему находится зарегистрированный ЦИ. Если в настройках ЦИ задан JwksUri, то СЭП загрузит текущие ключи подписи и с помощью них осуществит проверку пришедшего маркера.

У стороннего ЦИ можно запросить поместить в выпускаемый маркер определенные утверждения при помощи параметра Scope. В данном случае имеет смысл запрашивать у Google добавление в маркер утверждения, содержащего адрес электронной почты (обратите внимание, что для Oidc протокола в Scope обязаетльно наличие значения openid).

С учетом всего вышеизложенного команда по настройке аутентификации через Oidc примет вид:

Set-IdsIdentityProviderOidcEndpoint `
-IssuerName google `
-AuthorizationEndpoint https://accounts.google.com/o/oauth2/auth `
-JwksUri https://www.googleapis.com/oauth2/v3/certs `
-Issuer accounts.google.com `
-ClientId 23459005498-m89eo2br5q92nooqongdnm98qs8e5e4n.apps.googleusercontent.com `
-ClientSecret 1O2M4R6M8m9b9uF76XijOB `
-Scopes "openid email"

ЦИ ожидает, что в маркере будет сожержаться определенный набор утверждений, но во многих случаях на срдержимое маркера, возврашаемого сторонним ЦИ, повлиять нельзядаже с помощью параметра Scopes. Лля решения этой проблемы можно использовать правила преобразования утверждений. Подробно они рассматриваются в разделе Правила преобразования утверждений. Для Google в качестве уникального идентификатора можно использовать Email пользователя, а роль Users добавлять безусловно, тогда правила преобразования будут задаваться следующим образом:

[
    { 
        "Name":"Pass through email",
        "Rules" : [
            "c:[type==\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name\", value=c.value);",
            "=>issue(type=\"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\", value=\"Users\");",
        ]
    }
]

Настройка аутентификации по протоколу WS-Federation

Для подключения стороннего ЦИ по протоколу WsFed необходимы URL адрес конечной точки для обработки пассивного сценария (WsFedEndpointUri).

Настройка Microsoft ADFS в качестве стороннего ЦИ

Для ADFS адрес WsFedEndpointUri имеет вид https://<adfs-host>/adfs/ls. Тогда команда по настройке ADFS в качестве стороннего ЦИ примет вид

Set-IdsIdentityProviderWsFedEndpoint -IssuerName ADFS -WsFedEndpointUri "https://<adfs-host>/adfs/ls"

Настройка аутентификации через Госуслуги (ЕСИА)

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

Для настройки требуются следующие данные:

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

Ознакомиться с регламентом по подключению информационной системы к ЕСИА можно по ссылке.

Процесс подключения СЭП к ЕСИА состоит из следующих шагов.

Шаг 1. Добавление ЦИ.

Сначала необходимо добавить сторонний ЦИ с помощью командлета Add-IdsIdentityProvider.

Add-IdsIdentityProvider -IssuerName esia -Title "Вход через Госуслуги" -Description "Единая система идентификации и аутентификации" -AuthEndpointType Esia

Шаг 2. Настройка адресов конечных точек ЕСИА и имени издателя.

После успешного добавления стороннего ЦИ необходимо настроить адреса конечных точек, задать требуемые области использования маркера доступа.

Задать адреса конечных точек и имя издателя маркера доступа можно с помощью командлета Set-IdsIdentityProviderEsiaEndpoint.

Set-IdsIdentityProviderEsiaEndpoint -IssuerName esia -Issuer http://esia-portal1.test.gosuslugi.ru/ `
-AuthorizationEndpoint https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac `
-TokenEndpoint https://esia-portal1.test.gosuslugi.ru/aas/oauth2/te `
-UserInfoEndpoint https://esia-portal1.test.gosuslugi.ru/rs/prns `
-EndSessionEndpoint https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout

В таблице ниже приведены адреса для продуктивной и тестовой среды ЕСИА:

Параметр Описание Значение в тестовой среде Значение в продуктивной среде
Issuer Имя издателя http://esia-portal1.test.gosuslugi.ru/ http://esia.gosuslugi.ru/
AuthorizationEndpoint Конечная точка авторизации https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac https://esia.gosuslugi.ru/aas/oauth2/ac
TokenEndpoint Конечная точка получения маркера https://esia-portal1.test.gosuslugi.ru/aas/oauth2/te https://esia.gosuslugi.ru/aas/oauth2/te
UserInfoEndpoint Конечная точка получения сведений о пользователе https://esia-portal1.test.gosuslugi.ru/rs/prns https://esia.test.gosuslugi.ru/rs/prns
EndSessionEndpoint Конечная точка завершения сессии https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout

Шаг 3. Настройка учетных данных прикладной системы.

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

Сертификат подписи запроса необходимо предварительно установить в хранилище Личное (My) локального компьютера (Local Machine) с привязкой к закрытому ключу. Требуется выдать полные права на закрытый ключ для пула приложений, под которым работает веб-приложение ЦИ на сервере IIS.

Идентификатор клиента и отпечаток сертификата настраиваются с помощью командлета Set-IdsIdentityProviderEsiaEndpoint.

Set-IdsIdentityProviderEsiaEndpoint -IssuerName esia -ClientId MNEMONIC `
-ClientCertificateThumbprint 77fa2b8d646f3f8ee8b11b1c3b4f59e9610de615`

здесь

  • MNEMONIC - идентификатор прикладной системы, зарегистрированный в ЕСИА.
  • 77fa2b8d646f3f8ee8b11b1c3b4f59e9610de615 - отпечаток сертификата подписи запросов.

Шаг 4. Настройка областей использования маркера.

Прикладная система может получить доступ к учетным данным пользователя только после того, как пользователь предоставит явное разрешение. Требуемые данные указываются с помощью областей использования (scope). В СЭП поддерживаются следующие области использования:

Области использования, содержащие личные данные пользователя

Область использования Получаемые данные Утверждения, возвращаемые ЕСИА
fullname Имя, фамилия, отчество esia.identity.firstName
esia.identity.lastName
esia.identity.middleName
birthDate Дата рождения в формате DD.MM.YYYY esia.identity.birthDate
birthPlace Место рождения esia.identity.birthPlace
gender Пол (один символ 'M' - мужской, 'F' - женский esia.identity.gender
citizenship Гражданство (идентификатор страны гражданства)
для РФ имеет значение RUS		 esia.identity.citizenship
snils СНИЛС (значение содержит символы '-' и ' ') esia.identity.snils
inn ИНН (без лидирующего 0) esia.identity.inn

Области использования, содержащие контактные данные пользователя

Область использования Получаемые данные Утверждения возвращаемые ЕСИА
email Адрес электронной почты esia.contacts.MBT.value
mobile Номер мобильного телефона (может содержать символы '+', '(' и ')' esia.contacts.EML.value
contacts Адрес электронной почты,
номер мобильного телефона,
номер домашнего телефона		 esia.contacts.PHN.value
esia.contacts.EML.value
esia.contacts.MBT.value

Для номера мобильного телефона, домашнего телефона и адреса электронной почты также формируются утверждения esia.contacts.MBT.vrfStu, esia.contacts.PHN.vrfStu, esia.contacts.EML.vrfStu, содержащие информацию о статусе подтверждения данных (NOT_VERIFIED не подтверждены, VERIFIED - подтверждены).

Область использования contacts также позволяет получить сведения об адресах мест проживания и регистрации пользователя. По каждому типу адреса формируются следующие утверждения:

Утверждения возвращаемые ЕСИА Описание утверждений
esia.addresses.{type}.addressStr Неструктурированный адрес места проживания
esia.addresses.{type}.countryId Код страны проживания (для РФ имеет значение RUS)
esia.addresses.{type}.house Номер дома места проживания
esia.addresses.{type}.zipCode Индекс места проживания
esia.addresses.{type}.street Название улицы места проживания
esia.addresses.{type}.region Название субъекта федерации места проживания

здесь {type} может принимать значения PLV для места проживания и PRG для места регистрации.

Области использования, содержащие сведения о документах пользователя

Область использования Получаемые данные Утверждения возвращаемые ЕСИА
id_doc Сведения о документе, удостоверяющем личность esia.documents.RF_PASSPORT.series - серия,
esia.documents.RF_PASSPORT.number - номер,
esia.documents.RF_PASSPORT.issueDate - дата выдачи,
esia.documents.RF_PASSPORT.issueId - код подразделения,
esia.documents.RF_PASSPORT.issuedBy - кем выдан,
esia.documents.RF_PASSPORT.expiryDate - срок действия документа.

Дополнительно

Все указанные выше области использования позволяют также получить следующие данные (отдельные области использования для них запрашивать не нужно):

Получаемые данные Утверждения, возвращаемые ЕСИА
esia.identity.updatedOn Дата последнего изменения учетной записи пользователя
(задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года)
esia.identity.verifying Процесс проверки данных (True/False)
esia.identity.status Статус УЗ (Registered – зарегистрирована/Deleted – удалена)
esia.identity.trusted Тип учетной записи (подтверждена (True) / не подтверждена (False)

Помимо указанных выше областей использования требуется всегда явно указывать специальное значение openid.

Пример командлета по заданию областей использования:

Set-IdsIdentityProviderEsiaEndpoint -IssuerName esia -Scopes "openid fullname mobile"

Если для доступ к сервису требуется разрешить только подтвержденным учетным записям (утверждение esia.identity.trusted имеет значение True), то необходимо выполнить команду

Set-IdsIdentityProviderEsiaEndpoint -IssuerName esia -RequireTrustedAccount $true

Шаг 5. Указания сертификата проверки маркеров ЕСИА.

Сертификаты тестовой и продуктивной сред ЕСИА, используемые для формирования электронных подписей ответов как поставщика, доступны по ссылке.

Перед использованием сертификат проверки маркеров необходимо установить в хранилище Доверенные лица (Trusted People) Локального компьютера.

Задать сертификат проверки можно с помощью следующей команды:

Add-IdsIdentityProviderSigningCertificate -Id 2 -Certificate <путь к файлу сертификата> -UseSha1AsKid

здесь Id - идентификатор стороннего ЦИ (можно увидеть в выводе командлета Get-IdsIdentityProvider).

Шаг 6. Настройка правил преобразования утверждений.

Правила преобразования утверждений позволяют:

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

В качестве примера приведены правила, которые позволяют сделать следующее.

  • Задать в качестве идентификатора пользователя его адрес электронной почты.
  • Заполнить номер телефона и адрес электронной почты.
  • Заполнить фамилию, имя, отчество пользователя.
  • Заполнить адрес пользователя (включая область и город).
  • Безусловно добавить роль пользователя Users.
  • Удалить символы '-' и ' ' из значения утверждения esia.identity.snils.
  • Изменить код страны с RUS на RU.
[
    {
        "Name":"Email as unique_name",
        "Rules" : [
            "c:[type==\"esia.contacts.EML.value\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name\", value=c.value);",
            "c:[type==\"esia.contacts.EML.value\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\", value=c.value);",
            "c:[type==\"esia.contacts.MBT.value\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone\", value=c.value);"            
        ]
    },
    {
        "Name":"Role Users",
        "Rules" : [
            "=>issue(type=\"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\", value=\"Users\");"
        ]
    },
    {
        "Name":"Replace dashes in SNILS",
        "Rules" : [
        "c:[type==\"esia.identity.snils\"]=>add(type=\"esia.identity.snils.wo-dashes\", value=REPLACE(\"-\", \"\", c.value));",
            "c:[type==\"esia.identity.snils.wo-dashes\"]=>issue(type=\"http://dss.cryptopro.ru/identity/claims/snils\", value=REPLACE(\" \", \"\", c.value));"
        ]
    },
    {
        "Name":"Pass thru INN",
        "Rules" : [
        "c:[type==\"esia.identity.inn\"]=>issue(type=\"http://dss.cryptopro.ru/identity/claims/inn\", value=c.value);"
        ]
    },
    {
        "Name":"Personal Info",
        "Rules" : [
            "c1:[type==\"esia.identity.firstName\"] && c2:[type==\"esia.identity.middleName\"] && c3:[type==\"esia.identity.lastName\"]=>issue(type=\"http://schemas.xmlsoap.org/claims/CommonName\", value=c3.value + \" \" + c1.value + \" \" + c2.value);",
            "c:[type==\"esia.identity.lastName\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname\", value=c.value);",
            "c1:[type==\"esia.identity.firstName\"] && c2:[type==\"esia.identity.middleName\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname\", value=c1.value + \" \" + c2.value);",
        ]
    },
    {
        "Name":"Address info",
        "Rules" : [
            "c:[type==\"esia.addresses.PRG.region\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/stateorprovince\", value=c.value);",
            "c:[type==\"esia.addresses.PRG.city\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality\", value=c.value);",
            "c:[type==\"esia.addresses.PRG.region\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality\", value=c.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.building\"] && c3:[type==\"esia.addresses.PRG.frame\"] && c4:[type==\"esia.addresses.PRG.flat\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", стр \" + c2.value + \", корп \" + c3.value + \", кв \" + c4.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.building\"] && c3:[type==\"esia.addresses.PRG.frame\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", стр \" + c2.value + \", корп \" + c3.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.building\"] && c3:[type==\"esia.addresses.PRG.flat\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", стр \" + c2.value + \", кв \" + c3.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.frame\"] && c3:[type==\"esia.addresses.PRG.flat\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", корп \" + c2.value + \", кв \" + c3.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c3:[type==\"esia.addresses.PRG.frame\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", корп \" + c3.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.building\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", стр \" + c2.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"] && c2:[type==\"esia.addresses.PRG.flat\"] && c3:[type==\"esia.addresses.PRG.frame\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", д \" + c1.value + \", кв\" + c2.value);",
            "c:[type==\"esia.addresses.PRG.addressStr\"] && c1:[type==\"esia.addresses.PRG.house\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress\", value=c.value + \", \" + c1.value);"
        ]
    },
    {
        "Name":"Replace RUS to RU",
        "Rules" : [
            "c:[type==\"esia.identity.citizenship\", value==\"RUS\"]=>issue(type=\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country\", value=\"RU\");"
        ]
    }
]

Сохранив приведенный JSON в текстовый файл, можно с помощью командлета Set-IdsIdentityPropvider задать правила преобразования утверждений:

Set-IdsIdentityProvider -IssuerName esia -ClaimsTransformRulesFile "полный_путь_к_файлу"

Настройка аутентификации через ADFS

СЭП позволяет использовать в качестве стороннего доверенного ЦИ службы Active Directory (ADFS).

Руководство Администратора по интеграции СЭП с ADFS