Connect

Services for websites owners

E-NUM - is a system used to log in to closed online resources. E-NUM provides extra protection with a security key (unique code book) stored on the user's mobile device.

You can easily integrate the E-NUM authorization on your resource.

There are two ways of integration: OAuth2 and Soap.



OAuth2 integration method

OAuth 2.0 allows third parties access to secured resources without providing them with the user's authentication details such as challenge-question/challenge-answer.

E-NUM supports the OAuth 2.0 standard specification.


E-NUM

Instruction on how to authorize on the bank website using ENUM.


E-NUM Flow

Flow chart explaining in detail how to authorize on the bank website using E-NUM (top down)

  1. A client of the bank requests access to the secured online-banking area
  2. In order to grant access the bank redirects the client to the E-NUM system website so that he/she may complete authorization
  3. In case the authorisation is successful, the E-NUM system will provide a one-time code to the client
  4. In turn, the client's browser will transmit the authorization code to the bank's website
  5. The bank website uses the authorisation code to request E-NUM to provide a temporary access token
  6. This access token is then used to access API E-NUM methods which provide client identification.


OAuth2 API methods description

  • Authorization code request
  • Authorization code response
  • Access token request
  • Access token response
  • Getting the user identification details

Authorization code request

URL - https://auth.e-num.com/OAuth/Authorize

HTTP protocol method - GET

Parameters format - application/x-www-form-urlencoded

Request parameters
Name Description
response_type Value must be set to "code"
client_id The service ID received from the E-NUM system
redirect_uri URL, where the request response will be sent to (must be specified in the service settings of the E-NUM account)
scope A scope of the requested details about the client from the E-NUM system, divided by a space, e.g.: email phone
state An opaque value used by the client to maintain state between the request and callback.

Example
curl -i "https://auth.e-num.com/OAuth/Authorize?client_id=cd2068a8-cb18-4d24-bc85-dab0b3d3baf7&redirect_uri=https%3A%2F%2Fenumdemobank.e-num.com%2Fsignin-enum&scope=email%20phone&response_type=code&state=random-state"
HTTP/1.1 302 Found
Location: https://auth.e-num.com/Account/Login?ReturnUrl=%2FOAuth%2FAuthorize%3Fclient_id%3Dcd2068a8-cb18-4d24-bc85-dab0b3d3baf7%26redirect_uri%3Dhttps%253A%252F%252Fenumdemobank.e-num.com%252Fsignin-enum%26scope%3Demail%2520phone%26response_type%3Dcode%26state%3Drandom-state
                    


Authorization code response

URL address – the redirect_uri parameter set when calling the authorization code request method

HTTP protocol method - GET

Parameters format - application/x-www-form-urlencoded

Response parameters
Name Description
code one-time authorization code, valid only for a short period of time
state The exact value received from the client on request.

Example
GET https://enumdemobank.e-num.com/signin-enum?code=db8cea2e8bea4328b1ed&state=random-state
                    


Response parameters in case of error
Name Description
error One of the following: [invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable]
error_description Error description (Optional parameter)
error_uri Error description URL (Optional parameter)
state The exact value received from the client on request.


Access token request

Method URL address - https://auth.e-num.com/OAuth/Token

HTTP protocol method - POST

Parameters format - application/x-www-form-urlencoded

Request parameters
Name Description
client_id ID received from the E-NUM system.
client_secret Secret key received from the E-NUM system.
redirect_uri URL, where the request response will be sent to (must be specified in the service settings of the E-NUM account)
grant_type Value must be set to "authorization_code"
code One-time authorization code, received via the authorization code request

Example
curl -i -d "client_id=cd2068a8-cb18-4d24-bc85-dab0b3d3baf7&client_secret=0e919552-1122-3344-5566-197f151bc349&redirect_uri=https%3A%2F%2Fenumdemobank.e-num.com%2Fsignin-enum&grant_type=authorization_code&code=db8cea2e8bea4328b1ed" "https://auth.e-num.com/OAuth/Token"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":900,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}
                    


Access token response

Parameters format - application/json

Response parameters
Name Description
access_token Access token
token_type Value will be set to "bearer"
expires_in Token validity period, in seconds
refresh_token A token to reobtain the access token


Getting the user identification details

Method Url address - https://auth.e-num.com/api/Me

HTTP protocol method - GET

Request HTTP header - Authorization: Bearer {access token}

Example
$ curl -i -H "Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA" "https://auth.e-num.com/Api/Me"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"email":"test@example.com","phone":"00000000000"}
                    




Soap integration method

Soap integration method requires the redirection of a client for the first time only to https://auth.e-num.com. All subsequent requests do not require redirection.


SOAP

Driving authorization system using E-NUM by Soap method.

  • A user of an external website enters his/her email address. The website backend requests the GetChallenge2 method of E-NUM service (the soap interface) for receiving a challenge-question.
  • The website displays a challenge-question and asks a user to enter a challenge-response. The user response is checked with the CheckUserAnswer method.
  • At his/her first attempt to log into the website, a user will be redirected to https://auth.e-num.com to authorize the use of E-NUM on the website by his/her account.

To start using this authorization method a website owner should register his/her website via https://e-num.com/Account/Consumers.


Descriptions of Soap API methods

The http://service.e-num.com/Soap.asmx web service provides the basic methods: GetChallenge2 and CheckUserAnswer.


The GetChallenge2 method (receiving a challenge-question)

Request parameters
Name Description
consumerId The website identifier. To be obtained here: https://e-num.com/Account/Consumers, the value of Client ID.
email User email
userIp User IP-address
crc Parameter verification code calculated by hash-function sha256(consumerSecret + email). To be obtained here: https://e-num.com/Account/Consumers, the value of Client Secret. The hash-function result should be written in lower case without hyphens.
Response parameters
Name Description
ErrorCode The code result described below.
Challenge Challenge-question
QrUrl Challenge-question QR-code URL
SessionId The session identifier, used for automatically inserting the challenge-answer
ErrorCode result code
Code Description
0 Success
4 No account found with that email address
5 Authorization error due to the incorrect consumerId or crc parameter.
301 The user has not yet authorized E-NUM for this website. Please see below.
Other codes To receive the code description you need to use the GetErrDes method of Soap API.

When receive code 301, the site should redirect the user to: https://auth.e-num.com/permission/ask?consumerId={consumerId}&email={email}&redirectUrl={redirectUrl}&nonce={nonce}

redirectUrl the domain part must match the project url https://e-num.com/Account/Consumers
nonce an optional pass-through parameter

If a user authorises E-NUM, the user will be redirected to the specified redirectUrl with GET parameter allow=1. If a user does not authorise E-NUM, the user will be redirected with the deny=1 parameter. Other parameters provided to redirectUrl are listed below.

email User email
crc The parameter verification code and the evidence that the request is received from the E-NUM authorization server. Crc calculated by hash-function sha256(consumerSecret + email). To be obtained here: https://e-num.com/Account/Consumers, the value of Client Secret. The hash-function result should be written in lower case without hyphens.


The CheckUserAnswer method (answer check)


Request parameters
Name Description
consumerId The website identifier. To be obtained on the project page here: https://e-num.com/Account/Consumers, the value of Client ID.
email User email
userIp User IP-address
challenge Challenge-question
response Challenge-response
addname Optional service name, used in logs.
crc The parameter verification code, calculated with the sha256(consumerSecret + response) hash function. ConsumerSecret to be obtained on the project page: https://e-num.com/Account/Consumers, the value of Client Secret. The hash-function result should be written in lower case without hyphens.
Response parameters
ErrorCode The result code, outlined above in the GetChallenge2 method description.


Automatically inserting the challenge-answer

The challenge-answer can be automatically inserted into the response form on the site by sending it from the E-NUM mobile client. To do this, you need to add the following javascript code to the authorization form page:

...
<form id="login" method="post">
    ...
    <input type="text" name="response" id="response" />
    ...
</form>
...
<script src="https://signalr2.enum.ru/js/jquery.min.js"></script>
<script src="https://signalr2.enum.ru/js/signalr.min.js"></script>
<script>
    $(function () {
        // here it is necessary to pass the parameter obtained from the GetChallenge2 method
        var sessionId = '<%= SessionId %>';
        var connection = new signalR.HubConnectionBuilder()
            .withUrl('https://signalr2.enum.ru/autoResponseHub?sessionId=' + sessionId, {
                skipNegotiation: true,
                transport: signalR.HttpTransportType.WebSockets
            })
            .build();
        connection.on('response', function (response) {
            if ($.trim(response) !== '') {
                $('input#response').focus();
                $('input#response').val(response);
                $('form#login').submit();
            }
        });
        connection.start();
    });
</script>



Demonstration

A demonstration of the authorization procedure using E-NUM OAuth2 method and a fictitious bank.

Go to demonstration (working example)

Source code of the demonstration

You can implement your OAuth2-client E-NUM (in accordance with the description of the API methods above) or use ready clients libraries for your platform.

A libraly for Microsoft ASP.NET + Owin.

PHP example.


An example of the integration of E-NUM authorization Soap-method.