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

ЕСИ разрабатывается на основе стандарта OpenID Connect. Подробнее о стандарте можете узнать в его официальной документации. Посмотреть, как работает стандарт вы можете здесь.

Стандарт определяет несколько способов получения Access Token'a и ID Token'а. Как наиболее безопасный, ЕСИ использует алгоритм получение Access Token'а через авторизационный код с PKCE (Authorization code flow with PKCE).

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

Предварительно госпортал регистрируется в ЕСИ — получает свой уникальный номер клиента (client_id), своё секретное значение (client_secret) для аутентификации при обращении к Token Endpoint и указывает соответствующие для него адреса, куда будет перенаправлен пользователь после аутентификации (redirect_uri).

Предположим, что госпортал имеет следующие параметры:

client_id=gosportal
client_secret=fe4e82fc74b7518d509b4bfc37a3624e41fbb709631c896c652533e61c89b147
redirect_uri=https://e.gov.kg/

Также, допустим, что для оказания электронных услуг, госпорталу требуется следующие данные от пользователя: персональный номер (pin), имя (given_name), фамилия (family_name), отчество (middle_name), дата рождения (birthdate).

Эти данные можно получить, указав стандартный scope profile. (Подробнее смотрите Протокол работы ЕСИ)

В таком случае, весь процесс работы ЕСИ будет выглядеть следующим образом:

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

2. Пользователь выбирает «Вход через ЕСИ» и нажимает на соответствующую кнопку.

3. Госпортал формирует запрос на аутентификацию (Authentication request) и перенаправляет браузер пользователя к ЕСИ:

Запрос на аутентификацию:

https://{базовый-адрес-ЕСИ}/connect/authorize?
response_type=code
&scope=openid%20profile
&client_id=gosportal
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fe.gov.kg%2F
&code_challenge=eA2fKK-Yk4O5sU8A0yWDY_tXG3rl29iKffhY-N6Lyew
&code_challenge_method=S256

4. Пользователь аутентифицируется в ЕСИ - вводит свой пин/пароль и код со второго этапа аутентификации либо же использует вход через паспорт/SmartId.

5. ЕСИ аутентифицирует пользователя и запрашивает разрешение от пользователя на то, что госпортал может обработать его данные.

6. После получения разрешения ЕСИ перенаправляет пользователя по redirect_uri (см. пункт 3) вместе с авторизационным кодом (code):

https://e.gov.kg/?
code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj

7. Госпортал формирует запрос (Token Request), включающий в себя полученный авторизационный код (code), redirect_uri, client_id, client_secret, сгенрированный на 3ем шаге code_verifier и отправляет его в Token endpoint ЕСИ для получения ID Token'а и Access Token'а.

Запрос к Token Endpoint:

POST https://{базовый-адрес-ЕСИ}/connect/token?
grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&client_id=gosportal
&client_secret=fe4e82fc74b7518d509b4bfc37a3624e41fbb709631c896c652533e61c89b147
&redirect_uri=https%3A%2F%2Fe.gov.kg%2F
&code_verifier=lRkPFWNm6vgz5qVgyWCk_vwBV69bYQ-JimaU5UB9yG7LoCF_

8. ЕСИ валидирует запрос от госпортала.

9. Если всё верно, ЕСИ отправляет госпорталу ID Token и Access Token в ответ.

HTTP/1.1 200 OK
Content-Type: application/json
{
   "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNhZzBDYk1UYzh4d293MDVaVDRpRFEiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODQ0NDExNTAsImV4cCI6MTU4NDQ0NDc1MCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTg0NDQxMTQ4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSJdLCJhbXIiOlsibWZhIl19.KC-_Ua4k3rbRAVEkWF_NffnlGqInfSsSiD-zEk5dmLn5a7PAiiptDNqGpmSJbMhl2rbyFqTrBtUDxmkSbXALDWTAvuRqagTkEvlu2uUpJSQ9c_aYLsW4QdUdR2uAKliRlNAQFygWkN4xsXPSaB6E0B71YKmQcYutssBBcP3tBu_E4EDMW30Vky_osQeB8moHkPthMxXkpBxLSKieY77FOQDJzbaVmzrm9wmIor7OuwFtp0b9yKdpAsg9cGbgcmqW5pYNSa2GdhEzYrf6tkfF7tyuw-LYbJjCklfPwIQNk-RT1TicSwdZzsBWoAS8pWiBfwN4MAaA6TP4O6LA7hcdZw",
   "id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6ImNhZzBDYk1UYzh4d293MDVaVDRpRFEiLCJ0eXAiOiJKV1QifQ.eyJuYmYiOjE1ODQ0NDExNTAsImV4cCI6MTU4NDQ0MTQ1MCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibXZjLWNsaWVudCIsIm5vbmNlIjoiNjM3MjAwMzc5MzYyNjEzMzE0LlkyTmtZVGN3T0dFdFl6Y3pNaTAwTURreUxUbGhPVFF0T0RJd1pXVmxPVGMxTURVeFpXUTJNemd3TXpJdE9XTmlZaTAwWVROakxUZzFaREV0WkdFMU1XVTJNbVJsWVRFNCIsImlhdCI6MTU4NDQ0MTE1MCwiYXRfaGFzaCI6ImhpOWItMURYanVtSWRCeFJ1VGRlb3ciLCJzX2hhc2giOiJFNXdOMzRlMFZkVl9jSVJQREZGS0h3Iiwic2lkIjoiMjc1SEtZRE1QS0EtRGt1NXJWdjNJdyIsInN1YiI6IjEwMDAwMDAiLCJhdXRoX3RpbWUiOjE1ODQ0NDExNDgsImlkcCI6ImxvY2FsIiwiYW1yIjpbIm1mYSJdfQ.dkcyzcRHrTZAGATA2p3Q8x7PMeQRQdWYq9h0ptMD0lx_2LvKNc9ItEncBFm1Kjjtq8oY2wiIGILJTBwiyO7IGCePHCLLXTy2csxcd-gL83nXL5aosIOxOjTiIc7Wo4mCVIsnk-fHdroHmfPmB-gAEAnoEpOTbN5IZ-lpAJl_WhB-utbiNVyEVrzm03usHppbu2-ev-9vWOuiQy6Ryg-GBWTkv0Hi3Q5mnG1FBA-ac-13JXBIhSEPtKWFw6Ck3-OVi4IoTzh5uz-IPFv_1H12ervVE7Qf9tv6sEbrGj2q1x3KbAkAEeaGpJWduJfHLNthxwk99Gbl8JL710cZGGCpdQ",
   "expires_in": 86400,
   "token_type": "Bearer"
}

10. Теперь госпортал может получить нужные данные о пользователе, сформировав запрос (UserInfo request) с Access Token'ом и отправив его к UserInfo Endpoint.

Запрос к UserInfo Endpoint:

GET https://{базовый-адрес-ЕСИ}/connect/userinfo
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImNhZzBDYk1UYzh4d293MDVaVDRpRFEiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODQ0NDExNTAsImV4cCI6MTU4NDQ0NDc1MCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTg0NDQxMTQ4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSJdLCJhbXIiOlsibWZhIl19.KC-_Ua4k3rbRAVEkWF_NffnlGqInfSsSiD-zEk5dmLn5a7PAiiptDNqGpmSJbMhl2rbyFqTrBtUDxmkSbXALDWTAvuRqagTkEvlu2uUpJSQ9c_aYLsW4QdUdR2uAKliRlNAQFygWkN4xsXPSaB6E0B71YKmQcYutssBBcP3tBu_E4EDMW30Vky_osQeB8moHkPthMxXkpBxLSKieY77FOQDJzbaVmzrm9wmIor7OuwFtp0b9yKdpAsg9cGbgcmqW5pYNSa2GdhEzYrf6tkfF7tyuw-LYbJjCklfPwIQNk-RT1TicSwdZzsBWoAS8pWiBfwN4MAaA6TP4O6LA7hcdZw

11. ЕСИ валидирует запрос и, если всё верно, отправляет информацию о пользователе, соответствующую значениям scope (см. пункт 3), в ответ:

Если пользователь заходит как физическое лицо:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "sub": "248289761001",
   "pin": "22305198601234",
   "citizenship":"KGZ",
   "family_name": "Андреев",
   "given_name": "Андрей",
   "middle_name":"Андреевич",
   "name":"Андреев Андрей Андреевич",
   "gender":"male",
   "birth_date": "1986-05-23"
}

Если пользователь заходит как юридическое лицо:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "sub": "248289761001",
   "organization_tin": "ОсОО \"/Компания\"",
   "position_name": "Директор",
   "pin": "22305198601234",
   "citizenship":"KGZ",
   "family_name": "Андреев",
   "given_name": "Андрей",
   "middle_name":"Андреевич",
   "name":"Андреев Андрей Андреевич",
   "gender":"male",
   "birth_date": "1986-05-23"
}