Регистрация расширений авторизации

Docsvision Web-клиент поддерживает авторизацию с помощью сторонних расширений. Необходимые ресурсы для работы расширений авторизации в Web-клиенте поставляются с модулем Платформа и настраиваются в конфигурационном файле модуля.

Поддерживается вход при помощи следующих учётных записей:

Microsoft Azure
Active Directory Federation Services (ADFS)
ЕСИА (Госуслуги) по почте, номеру телефона, номеру СНИЛС

Настроить расширения можно при помощи изменения записей в секции "Docsvision" "Platform" "Server" "Authentication" "Extensions" конфигурационного файла по адресу /usr/lib/docsvision/platform/appsettings.json. Также можно создать отдельный файл формата .json с произвольным названием, указать в нём настройки расширений и поместить файл в каталог /lib/docsvision/platform/config.

Данный раздел посвящён регистрации расширений авторизации в Linux версии системы 6.1. Создание собственных расширений Docsvision описывается в разделе "Разработка расширений Docsvision" руководства по разработке.

Регистрация расширения Azure

  "Docsvision": {
    "Platform": {
      "Server": {
        "Authentication": {
          "Extensions": {
            "AzureAD": {
              "Name": "AzureAD", (1)
              "TypeName": "DocsVision.Platform.Authentication.AzureAD.AzureADRootAuthenticationExtension, DocsVision.Platform.Authentication.AzureAD, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7148AFE997F90519", (2)
              "Settings": "<?xml version=\"1.0\" encoding=\"utf-16\"?><AzureADAuthenticationSettings xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><WellKnownConfigurationUrl>https://login.microsoftonline.com/common/.well-known/openid-configuration</WellKnownConfigurationUrl><ClientId>c6c5c5e8-c320-4221-bbdf-205f8ff9610e</ClientId><GroupMembershipCheckerSettings><GroupMappings><AzureADGroupMapping><GroupId>94e14c7f-dbe9-42f4-8895-ac95c3dc8910</GroupId><Role>User</Role></AzureADGroupMapping></GroupMappings></GroupMembershipCheckerSettings><Tenants><guid>94e14c7f-dbe9-42f4-8895-ac95c3dc8910</guid></Tenants><ApplicationId>c6c5c5e8-c320-4221-bbdf-205f8ff9610e</ApplicationId></AzureADAuthenticationSettings>", (3)
              "Id": "{D4A9BCC3-E897-47AE-BBA5-8F5085D231E7}" (4)
            }
          }
        },
        "Tenants": { (5)
          "CurrentDB": {
            "Extensions": "{D4A9BCC3-E897-47AE-BBA5-8F5085D231E7}", (6)
            "Name": "CurrentDB" (7)
          }
        }
      }
    }
  }

1	`Name` — задаёт отображаемое имя сервиса аутентификации в справочнике сотрудников.
2	`TypeName` — строка с именем типа, реализующего расширение.
3	`Settings` — строка настроек расширения, для AzureAD. Подробнее см. ниже.
4	`ID` — строка с идентификатором расширения в виде Guid.
5	`Tenants` — в параметре указываются расширения аутентификации для конкретных БД Docsvision.
6	`Extensions` — строка, содержащая идентификаторы расширений аутентификации для конкретной БД в виде списка Guid через `;` (точка с запятой).
7	`Name` — строка, содержащая псевдоним БД, например: `CurrentDB`.

Строка настроек Azure

В примере ниже строка настроек приведена в отформатированном виде для удобства чтения. Данный фрагмент кода не предназначен для копирования в конфигурационный файл.

<?xml version="1.0" encoding="utf-16"?>
<AzureADAuthenticationSettings
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <WellKnownConfigurationUrl>https://login.microsoftonline.com/common/.well-known/openid-configuration</WellKnownConfigurationUrl> (1)
  <ClientId>c6c5c5e8-c320-4221-bbdf-205f8ff9610e</ClientId> (2)
  <GroupMembershipCheckerSettings>
    <GroupMappings>
      <AzureADGroupMapping> (3)
        <GroupId>94e14c7f-dbe9-42f4-8895-ac95c3dc8910</GroupId> (4)
        <Role>User</Role> (5)
      </AzureADGroupMapping>
    </GroupMappings>
  </GroupMembershipCheckerSettings>
  <Tenants>
    <guid>94e14c7f-dbe9-42f4-8895-ac95c3dc8910</guid>
  </Tenants>
  <ApplicationId>c6c5c5e8-c320-4221-bbdf-205f8ff9610e</ApplicationId> (6)
</AzureADAuthenticationSettings>",

1	`WellKnownConfigurationUrl` — URL публичной конфигурации OpenID.
2	`ClientId` — идентификатор тенанта AzureAD в котором производится привязка пользователей.
3	`AzureADGroupMapping` — задает сопоставление групп Azure AD системным группам безопасности Docsvision. Допускается на одну группу Azure AD создавать несколько групп Docsvision.
4	`GroupId` — идентификатор группы Azure AD.
5	`Role` — имя группы без префикса "Docsvision".
6	`ApplicationId` — идентификатор приложения Docsvision, зарегистрированного в тенанте AzureAD, для которого включено и настроено использование OpenID Connect.

Регистрация расширения ЕСИА

Значение параметра Name задаёт отображаемое имя сервиса аутентификации в справочнике сотрудников Web-клиента на вкладке "Безопасность".

Рисунок 1. Редактирование значения для параметра "Name"

Требования для расширения ЕСИА:

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

Необходимо выполнить обязательные настройки на сервере Docsvision:

Установить КриптоПро CSP 5.0 и выше.

Установить сертификат для работы с ЕСИА. Для этого можно воспользоваться утилитой certmgr, входящей в состав КриптоПро CSP 5.0, например, так:

sudo /opt/cprocsp/bin/amd64/certmgr -install -file путь-к-файлу-сертификата -pfx -pin пин-код (1)

1	По умолчанию служба dvappserver работает от имени пользователя ROOT, поэтому сертификат необходимо устанавливать с повышением привилегий.

Установить сертификат площадки из архива esia.zip. Сертификат тестовой площадки — TESIA GOST 2012.cer/ Например, так:
```
sudo /opt/cprocsp/bin/amd64/certmgr -install -file путь-к-файлу-TESIA-GOST-2012.cer (1)
```
1 С повышением привилегий пользователя.
Добавить настройки для аутентификации через ЕСИА в конфигурационный файл модуля Платформа.

Расширение аутентификации для ЕСИА настраивается по аналогии с Azure, за исключением параметра Settings — строки настроек расширения. Строка настроек для ЕСИА описана ниже.

{
    "DocsVision": {
        "Platform": {
            "Server": {
                "Authentication": {
                    "Extensions": {
                        "ESIA": {
                            "Id": "{DC3A3469-1B9C-4281-A5EA-ECEEF5A34C35}", (1)
                            "Name": "ЕСИА", (2)
                            "TypeName": "DocsVision.Platform.Authentication.ESIA.ESIARootAuthenticationExtension, DocsVision.Platform.Authentication.ESIA, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7148AFE997F90519", (3)
                            "Settings": "<?xml version=\"1.0\" encoding=\"utf-16\"?><ESIAAuthenticationSettings xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><WellKnownConfigurationUrl>{\"token_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v3/te\",\"token_endpoint_auth_methods_supported\":[\"client_secret_post\",\"private_key_jwt\",\"client_secret_basic\"],\"jwks_uri\":\"\",\"response_modes_supported\":[],\"subject_types_supported\":[],\"id_token_signing_alg_values_supported\":[],\"response_types_supported\":[\"code\",\"token\"],\"scopes_supported\":[\"openid email mobile snils fullname id_doc\"],\"issuer\":\"http://esia-portal1.test.gosuslugi.ru/\",\"microsoft_multi_refresh_token\":true,\"authorization_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v2/ac\",\"device_authorization_endpoint\":\"\",\"http_logout_supported\":true,\"frontchannel_logout_supported\":true,\"end_session_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout\",\"claims_supported\":[],\"check_session_iframe\":\"\",\"userinfo_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/rs/prns/\",\"kerberos_endpoint\":\"\",\"tenant_region_scope\":null,\"cloud_instance_name\":\"\",\"cloud_graph_host_name\":\"\",\"msgraph_host\":\"\",\"rbac_url\":\"\",\"certificate_hash\":\"B6864B005BE2E583733DAC88CC00AF1D98EE286B4E98CD7ECA03930AB303B76B\", \"certificate_thumbprint\":\"39D17F90BC7EA873566A1CCF1E36C23DCFFA5025\",\"certificate_password\":\"P@ssw0rd\",\"ext_certificate_thumbprint\":\"9c8393817199de4364ef7569f1af8c40b120f0f7\"}</WellKnownConfigurationUrl><ClientId>DOCSVISION</ClientId><Tenants></Tenants><AccountNameClaim>snils</AccountNameClaim><ApplicationId></ApplicationId></ESIAAuthenticationSettings>" (4)
                        }
                    }
                },
                "Tenants": { (5)
                  "docsvisionDB": {
                      "Extensions": "{DC3A3469-1B9C-4281-A5EA-ECEEF5A34C35}", (6)
                      "Name": "docsvisionDB" (7)
                  }
                }
            }
        }
    }
}

1	`ID` — строка с идентификатором расширения в виде Guid.
2	`Name` — задаёт отображаемое имя сервиса аутентификации в справочнике сотрудников.
3	`TypeName` — строка с именем типа, реализующего расширение.
4	`Settings` — строка настроек расширения, для ЕСИА. Подробнее см. ниже.
5	`Tenants` — в параметре указываются расширения аутентификации для конкретных БД Docsvision.
6	`Extensions` — строка, содержащая идентификаторы расширений аутентификации для конкретной БД в виде списка Guid через `;` (точка с запятой).
7	`Name` — строка, содержащая псевдоним БД, например: `docsvisionDB`.

В зависимости от того, что указано в настройках: СНИЛС, телефон или почта, в справочнике сотрудников Web-клиента, на вкладке "Безопасность" для способа аутентификации ЕСИА отображается соответствующее поле ввода.

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

После изменения параметра в конфигурационном файле необходимо перезапустить dvappserver и dvwebclient.

Строка настроек для ЕСИА

<?xml version=\"1.0\" encoding=\"utf-16\"?>
<ESIAAuthenticationSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema\" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance\">
<WellKnownConfigurationUrl>{
\"token_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v3/te\", (1)
\"token_endpoint_auth_methods_supported\":[\"client_secret_post\",\"private_key_jwt\",\"client_secret_basic\"],
\"jwks_uri\":\"\",
\"response_modes_supported\":[],
\"subject_types_supported\":[],\"id_token_signing_alg_values_supported\":[],
\"response_types_supported\":[\"code\",\"token\"],
\"scopes_supported\":[\"openid email mobile snils fullname id_doc\"], (2)
\"issuer\":\"http://esia-portal1.test.gosuslugi.ru/\", (3)
\"microsoft_multi_refresh_token\":true,
\"authorization_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/aas/oauth2/v2/ac\", (4)
\"device_authorization_endpoint\":\"\",
\"http_logout_supported\":true,
\"frontchannel_logout_supported\":true,
\"end_session_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/idp/ext/Logout\", (5)
\"claims_supported\":[],
\"check_session_iframe\":\"\",
\"userinfo_endpoint\":\"https://esia-portal1.test.gosuslugi.ru/rs/prns/\", (6)
\"kerberos_endpoint\":\"\",
\"tenant_region_scope\":null,
\"cloud_instance_name\":\"\",
\"cloud_graph_host_name\":\"\",
\"msgraph_host\":\"\",
\"rbac_url\":\"\",
\"certificate_hash\":\"B6864B005BE2E583733DAC88CC00AF1D98EE286B4E98CD7ECA03930AB303B76B\", (7)
\"certificate_thumbprint\":\"39D17F90BC7EA873566A1CCF1E36C23DCFFA5025\", (8)
\"certificate_password\":\"Password\", (9)
\"ext_certificate_thumbprint\":\"9c8393817199de4364ef7569f1af8c40b120f0f7\", (10)
}
</WellKnownConfigurationUrl>
<ClientId>DOCSVISION</ClientId> (11)
<Tenants></Tenants>
<AccountNameClaim>snils</AccountNameClaim> (12)
<ApplicationId></ApplicationId>
</ESIAAuthenticationSettings>

1	`token_endpoint` — URL для получения маркера доступа.
2	`scopes_supported` — область доступа, т.е. запрашиваемые права.
3	`issuer` — идентификатор стороны, генерирующей токен.
4	`authorization_endpoint` — URL для получения авторизационного кода.
5	`end_session_endpoint` — URL для выхода из учётной записи из ЕСИА.
6	`userinfo_endpoint` — URL для получения данных пользователя.
7	`certificate_hash` — хэш сертификата получаемый через утилиту cpverify.
8	`certificate_thumbprint` — отпечаток сертификата для работы с ЕСИА.
9	`certificate_password` — пароль сертификата для работы с ЕСИА. Пароль обычно устанавливается при импорте файла `.pfx` в Linux. Если пароль на сертификат не установлен, этот параметр можно удалить.
10	`ext_certificate_thumbprint` — отпечаток сертификата площадки. Можно посмотреть при выполнении `sudo /opt/cprocsp/bin/amd64/certmgr -list`.
11	`ClientId` — мнемоника системы получаемая при регистрации.
12	`AccountNameClaim` — параметр, который используется как ключ для авторизации. Возможные значения: `snils`, `phone`, `email`.

Ошибки при авторизации ЕСИА

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

[Error][DocsVision.Platform.WebClient.Diagnostics.Trace.TraceError] System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception.
  ---> System.Security.Authentication.AuthenticationException: The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot

Для исправления ошибки на сервере Docsvision необходимо установить корневой сертификат удостоверяющего центра, выдавшего сертификат портала ЕСИА. Корневой сертификат должен быть в формате PEM с расширением файла .crt. Установить сертификат можно поместив его в папку /usr/local/share/ca-certificates/, после чего необходимо будет выполнить команду:

sudo update-ca-certificates -v -f.

При возникновении трудностей с получением корневого сертификата, обратитесь в техническую поддержку ЕСИА.

Регистрация расширения ADFS

"Authentication": {
    "Extensions": {
	    "ADFS": {
            "Name": "ADFS", (1)
            "TypeName": "DocsVision.Platform.Authentication.ADFS.ADFSRootAuthenticationExtension, DocsVision.Platform.Authentication.ADFS, Version=6.0.0.0, Culture=neutral, PublicKeyToken=AFE7148AFE997F90519", (2)
            "Settings": "<?xml version=\"1.0\" encoding=\"utf-16\"?><ADFSAuthenticationSettings xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><WellKnownConfigurationUrl>https://551releaseVM.vmkh.org/adfs/.well-known/openid-configuration</WellKnownConfigurationUrl><ClientId>8d4612ab-c258-4f0b-ba02-d6aeab59debd</ClientId></ADFSAuthenticationSettings>", (3)
            "Id": "{36351525-8FCE-48AB-8AD3-4C1FA575FF23}" (4)
        }
     },
     "Tenants": { (5)
         "docsvision-db": {
             "Extensions":"{36351525-8FCE-48AB-8AD3-4C1FA575FF23}", (6)
             "Name": "CurrentDB" (7)
         }
     }
}

1	`Name` — задаёт отображаемое имя сервиса аутентификации в справочнике сотрудников.
2	`TypeName` — строка с именем типа, реализующего расширение.
3	`Settings` — строка настроек расширения, для AzureAD. Подробнее см. ниже.
4	`ID` — строка с идентификатором расширения в виде Guid.
5	`Tenants` — в параметре указываются расширения аутентификации для конкретных БД Docsvision.
6	`Extensions` — строка, содержащая идентификаторы расширений аутентификации для конкретной БД в виде списка Guid через `;` (точка с запятой).
7	`Name` — строка, содержащая псевдоним БД, например: `CurrentDB`.

Строка настроек для ADFS

<?xml version="1.0" encoding="utf-16"?>
<ADFSAuthenticationSettings
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <WellKnownConfigurationUrl>https://domain.company.com/adfs/.well-known/openid-configuration</WellKnownConfigurationUrl> (1)
  <ClientId>8d4612ab-c258-4f0b-ba02-d6aeab59debd</ClientId> (2)
</ADFSAuthenticationSettings>

1	`WellKnownConfigurationUrl` — URL публичной конфигурации ADFS.
2	`ClientId` — идентификатор тенанта ADFS в котором производится привязка пользователей.