Share on:

OpenAM Authentication via Gosuslugi Portal

Original article:“Госуслуги-РФ”-OAuth2-Identity-Provider


Register an Organization on the Gosuslugi Portal

In order to use authentication through the ESIA, you need to register your organization on the Gosuslugi portal. To do this, you need to have a confirmed account of the head of the organization on the portal.

Next, you need to register your information system on the ESIA technology portal. To do this, go to the link and authenticate with the account of the head of the organization. On the “Информационные системы” tab, click “Добавить систему” and fill in the properties on the link. The main thing to pay attention to is the system mnemonic, i.e. client_id, system URL - a list of allowed URLs to which redirection will be performed after successful or unsuccessful authentication in ESIA, as well as the algorithm of electronic signature formation - must be GOST3410_2012_256.

The process is described in more detail in document section 3.1.1

Send System Registration Application to the Ministry of Digitization

After you have registered an information system, you must obtain a certificate from an accredited certification center (List of accredited certification centers at

The algorithm of electronic signature formation is GOST R 34.10-2012. The certificate must contain the OGRN of the legal entity that is the operator of the information system and can be issued for the employee of the legal entity or for the organization.

Next, you need to fill an application to gain access to the test environment as described in paragraph 9 and send it to the e-mail address of the Ministry of Digitization.

After your system is registered in the test environment, you can proceed to OpenAM configuration.

OpenAM Installation

If you have already installed OpenAM, you can skip this section. For demonstration purposes, we will configure OpenAM in a Docker container.

Network Setup

Add the OpenAM hostname and IP address to the hosts file

On Windows systems, the hosts file is located at C:Windows/System32/drivers/etc/hosts; on Linux and Mac it is located at /etc/hosts.

Install OpenAM in Docker

Start the Docker image of OpenAM by mounting the key and certificate issued earlier to the container.

docker run -h -p 8080:8080 --name openam \
 -v ./openam-esia.key:/usr/openam/esia/openam-esia.key:ro \.
 -v ./openam-esia.pem:/usr/openam/esia/openam-esia.pem:ro openidentityplatform/openam:latest

Once the OpenAM server is running, perform the initial configuration by running the following command and wait for the configuration to complete.

docker exec -w '/usr/openam/ssoconfiguratortools' openam bash -c \
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=passw0rd" > conf.file && java -jar openam-configurator-tool*.jar --file conf.file'

OpenAM Configuration

Setup ESIA Authentication Module

Open the OpenAM administrator console at In the login field enter the amadmin value, in the password field enter the value specified in the ADMIN_PWD setting, in this case passw0rd.

In the console, select the root realm and then select Authentication → Modules from the left menu. In the opened list, click the Add Module button.

Enter the module name, for example, esia and the module type - OAuth 2.0 / OpenID Connect.

OpenAM new ESIA module

Press the Create button . Fill in the settings according to the table:

Setting Value  
Client Id Mnemonic of the information system specified in the ESIA technology portal  
Client Secret Not to be filled in, client secret is calculated dynamically for ESIA  
Authentication Endpoint URL  
Access Token Endpoint URL
User Profile Service URL  
Scope Scope of the profile, for demonstration purposes we will specify fullname birthdate gender. You can read more about the scope description in the document at  
OAuth2 Access Token Profile Service Parameter name access_token  
Proxy URL  
Account Provider org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider  
Account Mapper org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper  
Account Mapper Configuration oid=uid  
Attribute Mapper org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper  
Attribute Mapper Configuration oid=uid, remote-json=sn  
Custom Properties    
esia-key-path path to the private key file, e.g. /usr/openam/esia/openam-esia.key  
esia-cert-path the path to the certificate file, e.g. /usr/openam/esia/openam-esia.pem  
esia-org-scope organization scope if you want to get information about the organization of the ESIA user  
esia-org-info-url URL to retrieve organization information, e.g. - for test ESIA  

Configuring the ESIA Authentication Chain

Open the OpenAM admin console, select realm and from the left menu select Authentication → Chains . Click the Add Chain button and enter a name for the chain, for example esia . Click the Create button.

OpenAM new ESIA auth chain

Press the Add a Module button.

OpenAM ESIA auth chain settings

Add module esia , Criteria set to Requisite. Press the `OK button .

Test the solution

Logout the OpenAM admin console, and open the ESUA authentication chain link: If everything is configured correctly, you will be redirected to the ESIA authentication portal. Enter the user’s credentials. After successful authentication to the ESIA, the ESIA will request consent to access the data passed in the scope parameter. After accepting the consent, you will be redirected to the OpenAM console with the user’s ESIA credentials.