Geekly Articles each Day
📜 ⬆️ ⬇️

Integration of IS with ESIA via SAML

Integration with ESIA

When executing the next state order, our team was faced with the problem of integrating the site with ESIA. There are no instructions on how to solve this problem, except for information in official documents of the Ministry of Communications and Communities (approximately 300 pages in three regulations). There are also companies that provide paid services for the integration of ESIA. We implemented, described the integration process and decided to share with the community habrahabr.


What is ESIA


EDITIONAL SYSTEM AND IDENTIFICATION AND AUTHENTICATION - Russian information system providing access (registration, authentication) to the websites of state structures and some commercial organizations. Read more on wikipedia


During the integration of the ESIA, the system will be able to send a request to the ESIA and upon successful authorization receive user data as a response


The authorization script looks like this:



Content


  1. General information
  2. Install SimpleSAMLphp
  3. Configuring SimpleSAMLphp to connect to the ESIA test environment
  4. Metadata File Configuration
  5. Sending an application to the address of MinKomSvzyai for connection of IP to the ESIA test environment
  6. Functional integration with ESIA and obtaining data from authorized users via ESIA
  7. Sending an application for connecting the IP to the ESIA production environment

General information


The MinKomSvyaz website contains a document called “Guidelines for the use of the Unified Identification and Authentication System” , the latest current version can always be found on the MinKomSvyaz website. The document itself is rather big - almost 200 pages, and, of course, few people will want to study it in detail, and it will not be understandable to everyone, so I will describe here the process in the bottom line.


It is possible to connect the IC to the ESIA in two ways:



If we compare the 2 approaches, then in fact there is no big difference between them, there are several advantages to the method based on the REST approach. There are guys who, in my opinion, connect ESIA for a lot of money and they wrote about the advantages of REST here .


But for the vast majority of cases, the first approach covers all the necessary functions. Therefore, I will talk about the implementation of ESIA through SAML 2.0


Install SimpleSAMLphp


For integration we will use SimpleSAMLphp. If the system you are setting up is not written in PHP, then you can still use this module, just on your website there will be an authentication function implemented in php, you will receive data from ESIA in xml format.


The latest official version of SimplSAMLphp is available on the official SimpleSamlPHP website. Download the archive, unpack the module in the /var folder. For security reasons, for the folder with the unzipped module, you need to set access rights only for root users. In the server configuration, you must add an alias and the following rules:


<VirtualHost *> ServerName service.example.com DocumentRoot /var/www/service.example.com SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config Alias /simplesaml /var/simplesamlphp/www <Directory /var/simplesamlphp/www> <IfModule !mod_authz_core.c> # For Apache 2.2: Order allow,deny Allow from all </IfModule> <IfModule mod_authz_core.c> # For Apache 2.4: Require all granted </IfModule> </Directory> </VirtualHost>

The bottom line is that on request ServerName/simplesaml opened the welcome page simplesaml. If you did everything correctly, then at the request of ServerName/simplesaml you will see such a page



SimpleSamlPHP

Configuring SimpleSAMLphp to connect to the ESIA test environment


Integration requires a certificate ( cert.crt ) and a key ( key.key ). It is important (!) With the Gostovskiy certificate nothing comes out, you can get a free certificate, google how it is done, or issue a certificate yourself. simplesamlphp/cert key and certificate in the folder simplesamlphp/cert


To configure SimpleSAMLphp, you need to edit the following files:



Important note - the time on the server should not differ from the ESIA time more than 1 minute.


simplesamlphp/config/config.php :


 //         simplesamlphp 'certdir' => 'cert/' //  'secretsalt' => 'defaultsecretsalt', //  'technicalcontact_name' => 'Familiya Imya', 'technicalcontact_email' => 'po4ta@domen.zone',

It is important to know if the system has an entityID, if it does not, then in the 'entityID' field you must specify the address of the system


simplesamlphp/config/authsources.php :


 esia' => array ( 'saml:SP', 'name' => 'Esia', //   'privatekey' => 'key.key', //  'privatekey_pass' => '12345678', //   'certificate' => 'cert.crt', // , 'entityID' => 'ServerName', 'discoURL' => NULL, 'redirect.sign' => TRUE, 'redirect.validate' => TRUE, 'validate.logout' => FALSE, //idp      'idp' => 'https://esia-portal1.test.gosuslugi.ru/idp/shibboleth', //idp      // 'idp' => 'https://esia.gosuslugi.ru/idp/shibboleth', //  'OrganizationName' => 'Organization Name', //url  'OrganizationURL' => 'ServerName',

Now you need to get a signature for our certificate (fingerprint). This can be done in the terminal of one of the commands.



simplesamlphp/metadata/saml20-idp-remote.php :


 // idp      $metadata['https://esia-portal1.test.gosuslugi.ru/idp/shibboleth'] = array( 'name' => array( 'en' => 'Esia', 'no' => 'ESIA', ), //idp SignOn   'SingleSignOnService' => 'https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SSO', //idp LogOut   'SingleLogoutService' => 'https://esia-portal1.test.gosuslugi.ru/idp/profile/SAML2/Redirect/SLO', //Fingerprint  'certFingerprint' => 'f17393ae5927293ae5927261b6515c44501e4450', );

Metadata File Configuration


Now you need to configure the metadata file in order to send it along with the application to the ESIA


The metadata file is available at the link: ServerName/simplesaml/module.php/saml/sp/metadata.php/esia?output=xhtml


Sample metadata file:


 <?xml version="1.0"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="ServerName"> <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate> // </ ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:KeyDescriptor use="encryption"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate> // </ ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="ServerName/simplesaml/module.php/saml/sp/saml2-logout.php/esia"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="ServerName/simplesaml/module.php/saml/sp/saml2-acs.php/esia" index="0"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="ServerName/simplesaml/module.php/saml/sp/saml1-acs.php/esia" index="1"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="ServerName/simplesaml/module.php/saml/sp/saml2-acs.php/esia" index="2"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="ServerName/simplesaml/module.php/saml/sp/saml1-acs.php/esia/artifact" index="3"/> </md:SPSSODescriptor> <md:Organization> <md:OrganizationName xml:lang="en">Organization Name</md:OrganizationName> <md:OrganizationDisplayName xml:lang="en">Organization Name</md:OrganizationDisplayName> <md:OrganizationURL xml:lang="en">ServerName</md:OrganizationURL> </md:Organization> <md:ContactPerson contactType="technical"> <md:GivenName>Imya</md:GivenName> <md:SurName>Familiya</md:SurName> <md:EmailAddress>po4ta@domen.zone</md:EmailAddress> </md:ContactPerson> </md:E</ntityDescriptor>

But, unfortunately, SimpleSaml generates a metadata file, which is slightly different from the ESIA requirement, so you need to correct it in accordance with the recommendations of paragraph A.6. Metadata file template


An example of a metadata file that meets the requirements of the ESIA can be downloaded at example.xml


Sending an application to the address of MinKomSvzyai for connection of IP to the ESIA test environment


Now we form an application in the form “E” of the Regulations for Informational Interaction between the Participants and the Operator of the ESIA . The application form in docx format can be downloaded from our website by the link .


Now you need to send a request for esia@minsvyaz.ru mail with the subject “Integration of test ESIA” and you need to attach three files to the letter:



After receiving the answer from the service provider (ESIA) with the status “Solved” and the attached files for testing, proceed to the next step.


Perhaps you will receive a reply with the subject “Additional information is required by request #”, in this case the letter will contain information about what needs to be corrected.


Functional integration with ESIA and obtaining data from authorized users via ESIA


Check the connection of the IC to the test environment can be on the link
ServerName/simplesaml/module.php/core/authenticate.php?as=esia .


If all previous points are correctly executed, a page with the ESIA test environment will open. For authentication in a test environment, data obtained from ESIA in a letter with the “Resolved” status are used. After authentication, you will be transferred to the SimpleSAML page with a table with the received data from ESIA.


xml answer ESIA
')

Now we will write a script that will process the data. To begin, add a button for authorization on the site.


 //  action         <form action="inc/esia.php" method="POST"> <input name="esia" type="submit" value="  "/> </form>

Handler inc/esia.php . Here we get the data and we can write it to the database, add it to the session, etc. In general, you need to properly parse xml. Now just display the data on the screen.



 if (isset($_POST['esia'])){ //   simplesamlphp/lib/_autoload.php require_once('../../simplesamlphp/lib/_autoload.php'); $as = new SimpleSAML_Auth_Simple('esia'); $as->requireAuth(); $attributes = $as->getAttributes(); foreach($attributes as $key => $value) { echo ($key . ' ' . $value . '<br/>'); } }

Sending an application for connecting the IP to the ESIA production environment


Now we form an application in the form “M” of the Regulations for information interaction of the Participants with the Operator ESIA . It is not much different from form E, but carefully study the form, it is necessary to add the requested data in the form and no longer need to attach the certificate file.


In the files simplesamlphp/config/authsources.php , simplesamlphp/metadata/saml20-idp-remote.php you must replace the idp of the service provider from the Test environment with the productive one:


 //idp      // 'idp' => 'https://esia-portal1.test.gosuslugi.ru/idp/shibboleth', //   idp      'idp' => 'https://esia.gosuslugi.ru/idp/shibboleth',

Now we create a new metadata file, in fact only the links in the Service fields change.


We send an email to esia@minsvyaz.ru and attach 2 files:



Now you should receive a response with the status “Reshen”, after that you can enter the entry function through the ENIA into operation.


At the time of writing, the current version of the Regulation is 2.7. When updating the regulations, some changes in the interaction of the EC with the ESIA are possible.


Source: https://habr.com/ru/post/326008/

More articles:


All Articles