Product manual

26
9.1 Integration Overview
The API consists of two endpoints , which are both called by POSTing JSON-formatted text to the relevant API URLs. All responses
are also encoded as JSON-formatted text, containing the method result and any applicable error messages. The first endpoint (the
Authentication API) is for user authentication and the second endpoint (the User Management API) is for user management.
The API is available on all servers where the Authentication Core component is installed and runs over the secure HTTPS protocol
on port 8001.
The Authentication API is available on URLs of the form https://127.0.0.1:8001/auth/v1/ and the User Management API is
available on URLs of the form https://127.0.0.1:8001/manage/users/v1/. Both endpoints are protected from unauthorized access
via standard HTTP Basic Authentication, requiring a valid set of API Credentials before processing any request.
The ESET Secure Authentication installer automatically uses an appropriate SSL security certificate installed on the machine, or
generates a new self-signed certificate if another cannot be found.
9.2 Configuration
The API is disabled by default and must be enabled before use. Once enabled, API credentials must be created to authorize
requests:
1. Launch the ESET Secure Authentication Management Console and navigate to the “Advanced Settings” node for your domain.
2. Expand the “API” section and check the “API is enabled” check box. Save the changes.
3. Open the standard Windows Services Console and restart the ESET Secure Authentication Core service for the change to take
effect.
4. Navigate to the newly visible “API Credentials” node for your domain.
5. Click the “Add Credentials” action to create a new set of credentials.
6. Double-click on the newly created credentials to get the username and password that are to be used for API authentication.
7. Check the "Enabled for Auth API" check box, the "Enabled for User Management API" check box or both.
Many sets of API credentials may be created. It is recommended to create different sets for each application being protected, as
well as for testing.
If the API is enabled, all servers with the Authentication Core component installed will respond to authorized API requests after
they are restarted. There is no need to restart the Authentication Core service when credentials are created or deleted.
9.3 Replacing the SSL Certificate
The API utilizes an SSL certificate to secure API communications from eavesdropping. The installer automatically selects an
appropriate certificate installed on the machine, or generates a new self-signed certificate if another cannot be found.
This section explains how to replace the certificate with another of your choosing. It will first help you to import your new
certificate into Windows, and then use it for ESA.
9.3.1 Prerequisites
In order to follow this guide you will need:
All operating systems:
o An installation of the ESET Secure Authentication Core component
o Administrator access to the computer where ESET Secure Authentication is installed
o The SSL certificate you wish to use in PKCS12 format (.pfx or .p12)
The certificate file needs to contain a copy of the private key as well as the public key
Windows 2003 only:
o The httpcfg.exe tool from the Windows Support Tools pack (either on the installation CD or downloadable from http://
www.microsoft.com/en-us/download/details.aspx?id=18546)
NOTE: The ESA Authentication API does not have to be enabled in order to replace the certificate.