Software Development

Python 3 Library for Connecting to ESIA — esia-connector

5 min read
15K views

Everything started when the Ministry of Communications allowed the use of the State Services Portal (Gosuslugi) for identifying and authenticating users on non-governmental websites. This is implemented via ESIA (Unified Identification and Authentication System — esia.gosuslugi.ru).

Our project’s client was among the first five applicants to request integration with ESIA, which tasked us with supporting this integration.

Since we couldn’t find any open-source solution suitable for our tech stack, we decided—after getting approval from the client—to share our implementation under the BSD license.

We present to you esia-connector, a library written in Python 3, utilizing the OpenSSL utility. It has been tested exclusively on Debian-based systems.

Package: esia-connector on PyPI
Project: esia-connector on GitHub

What is ESIA?

I won’t delve into what ESIA is or the capabilities it offers. Instead, I’ll focus on what our library, esia-connector, currently supports:

Authenticate with ESIA to receive and verify a token (usable for user identification).
Retrieve user personal data, including:
- Full name (FIO).
- Identity document details (passport, driver’s license).
- Contact information (phone numbers, email addresses).
- Taxpayer ID (INN).
- Pension insurance number (SNILS).
- Address information (residence and registration).

Usage

Prerequisites

To connect to ESIA using the library, you’ll need:

A certificate: Issued or self-signed in the format described in the official guidelines and uploaded to both the ESIA test and production servers.
- Guidelines excerpt
ESIA-provided account credentials for your organization, issued by ESIA support for both test and production environments. These should replace "YOUR_SYSTEM_ID" in the EsiaSettings object.
User accounts for the test and production servers to debug and test.
Public keys for ESIA (test and production) to verify the token. These are not publicly available and must be requested from ESIA support via email.

Running the Example

The library repository includes a minimal web application (Flask-based) as a test example.

Place the uploaded certificate into esia-connector/examples/res/test.crt.
In the same directory, include:
- Your private key as test.key.
- The ESIA public key as esia_pub.key.
Run the Flask application by navigating to the examples directory and executing:bashCopy codepython flask_app.py

Upon visiting the home page, you’ll see a correctly formatted URL to interact with ESIA. Following this link initiates the ESIA authentication flow, including:

Prompting the user for their ESIA credentials.
Requesting permission for your app to access ESIA data.
Redirecting to the test page, where the token is used to make additional API requests for the user’s personal data.
Displaying the retrieved data on the test page.

Implementation

The library’s structure is straightforward and requires little explanation. In hindsight, we realized the design could be improved to reduce the actions required by the library’s user.

Notable aspects of the current implementation:

OpenSSL Utility: Used for signing, which involves an extra step of creating a temporary file. While functional, it would be better to replace this with pyOpenSSL.

We are satisfied with the current implementation but have no plans for further development unless project requirements change.

Potential Improvements

If you’re using esia-connector in your projects and make any additions or fixes, feel free to submit a pull request—we’d be happy to merge your contributions.

Future enhancements could include:

Simplifying the library’s interface for easier usage.
Replacing OpenSSL with pyOpenSSL.
Expanding functionality to retrieve additional data from ESIA.
Supporting an alternative data exchange protocol (SAML) implemented in ESIA.
Creating wrappers for popular frameworks, such as Django or Flask, possibly as separate projects.

Python 3 Library for Connecting to ESIA — esia-connector

What is ESIA?