Page tree
Skip to end of metadata
Go to start of metadata

API Security

In Setup > System > Manage Web Services, there are some options to configure the security of SOAP and REST Web Services. 

Manage Web Services

Group Permissions

Below the enabling web services section, you can select the groups that are permitted to use the SOAP and REST interfaces. If a user does not belong to a group that is selected in these drop-down lists, they will be restricted with a 403 access error, even if they have create/edit/delete permissions on the affected records. 

IP Address Restrictions

Four global variables allow you to define a set of IP addresses for SOAP and REST blacklisting/whitelisting:

  • Security: REST IP Blacklist
  • Security: REST IP Whitelist
  • Security: SOAP IP Blacklist
  • Security: SOAP IP Whitelist

IP addresses should be comma separated, and address ranges should be indicated with a dash. 

Example

10.168.6.102, 10.169.7.132-10.169.7.150

REST Authentication

The REST client application must log in using valid credentials for a knowledgebase. Agiloft verifies these credentials and if valid creates an HTTP session that the client can use in subsequent calls.

Every REST call should contain the user’s credentials in the form login={login}&password={password}.

Passing Credentials in the Parameter Body with POST

If you are in a production system and do not wish to expose user credentials as plain text, you can avoid passing the login or password in REST calls by using POST instead of GET to pass the parameters in the request body. POST requests support the /ewws/EWRead, /ewws/EWSelect, /ewws/EWCreate, /ewws/EWUpdate, /ewws/EWDelete methods. For more information on constructing a REST request via POST, see URL Conventions

Access Permissions

Call permissions are based on the authorized user's permissions in the  Agiloft KB, so it will return only the data that the API user has access to. Please note that in addition to the user's group permissions, it is necessary to grant REST access to the group via Setup System > Manage Web Services > Groups allowed for REST. Any operation that the user doesn't have access to will be rejected.

Encryption

SOAP and REST calls can be encrypted by system admins. For example, consider a call to read data from a contract record: http://\{localhost}/ewws/EWRead?$kb=KBNAME&$table=contract 

Omit the variables likely to change, such as the ID value, from the string. 

  1. Go to Setup > Access > Automatic Login Hotlinks.
  2. Enter the string constructed above into the input box, select an expiration time, and click Encrypt. 
  3. The encrypted URL can be used in the same way as the standard URL, and parameters can be added to it in the standard way. 

    The system trusts the encrypted URL, so no password is required.


Statefulness

Though stateless in appearance Agiloft Web Services are stateful by nature. A certain set of information can be shared as a "session" between multiple calls and there is usually no good reason to re-create it on every call. 

A typical integration scenario obeys the pattern of "login, do multiple calls, logout". 

The statefulness is supported via a widely used pattern of obtaining a session token first via the EWLogin method and explicitly passing it with each subsequent call performed. 

Once the session is finished it is advisable to destroy the session with a call to EWLogout to ensure proper freeing of server resources.

For more information, see https://nordicapis.com/defining-stateful-vs-stateless-web-services/

Failed Logins

The SOAP API handles a series of failed logins in the same fashion as the GUI, i.e. it will produce an error if the account becomes blocked due to multiple unsuccessful login attempts.

SSL Support

The  Agiloft SOAP API relies on the underlying application server and front-end web server (if present) for SSL support.