In this article, I want to consider aspects of security within the REST API. This is will cover how authentication is handled, field-level security and user rights defined by security profiles.

By their very nature, RESTful APIs are designed to take advantage of existing protocols. Theoretically, the concept of REST (Representational State Transfer) can be used over nearly any protocol. Within the context of Sage CRM our API takes advantage of HTTP.

We expect developers and integrators are going to want to access the API from a wide variety of locations, both inside and outside the corporate network and that they will be accessing it using a range of different devices.

That means that when planning a development some thought will need to go into the questions

• Who can access the system?
• Where can they access the system?
• What can they see and do within the system?

We need to consider authentication of any interaction, the application security applied, network security and database security.

The REST API is a stateless communications protocol. The Sage CRM server treats each request as an independent transaction that has no link to any previous request. Each request and its response are independent of any previous or subsequent request.

Sage CRM does not keep a record of a 'session' for RESTful API calls unlike when a user logs on via the main user interface. Instead, the API passes the credentials within each request from the requesting client. The client is responsible for maintaining the connection.

Authentication in the RESTful API can be done either by passing the credentials as a result of a challenge and response or by including the credentials in the HTTP header.

The image below shows how we can pass the credentials in a request issued by a program written in C#.

You can see that the request includes within the HTTP header the base64 encoded user credentials.

Importance of always using HTTPS

Base64 encoding is not to do with security. The encoding allows us to represent (binary) data using only a limited, common-subset of the available characters and security is not the intent of the encoding step. Rather, encoding turns non-HTTP-compatible characters that may be in the user name or password into those that are HTTP-compatible.

Our REST authentication mechanism requires us to transmit the username and password in each transaction.

Note: The Sage CRM server itself doesn't know the password — it only stores a hash of the password. This area was upgraded substantially in 2019 R1 to make use of bcrypt. The hash strength is adaptive, and it's now salted. If you upgrade your Sage CRM server, the next time you save a password the hash will be stronger. The upshot of this is that if a Sage CRM database were to be stolen, it would be very difficult to figure out the stored user passwords (individual passwords are easier, but you're still talking about a concerted effort using a lot of hardware).

This transfer of the user credentials in each transaction means we must much rely on HTTPS to protect the password "in-flight".

HTTPS all the data secret by encrypting it as it moves between the client and the Sage CRM server. This ensures that anyone listening in on the conversation can't read anything. This could include your ISP, a hacker, or anyone else who manages to position themselves between you and the webserver.

Historically, SSL was the standard protocol used by HTTPS. The newest version of SSL is now called Transport Layer Security (TLS) but they are very much the same thing. If in any articles I refer to the standard as SSL technically I'm talking about the newer TLS. Modern web servers and client browsers all support TLS 1.1 or 1.2, which is all we need at present. The development team is looking to bring TLS 1.3 support into the Sage CRM as soon as possible.

Consider the image below

Over HTTP the transport is in plain text and any data can read and decoded. Over HTTPS the data is encrypted and protected.

You must only access Sage CRM on public-facing servers over HTTPS. You will need to ensure that customers have installed their Windows updates on their Sage CRM servers, and have updated their client browsers to the latest version.

I think that all pages on a public-facing server must be served over HTTPS. This includes CSS files, scripts, images, AJAX requests, POST data and third-party includes. If you don't do that this can create an opportunity for "man-in-the-middle" attacks. A hacker is going to attempt to observe, intercept and manipulate the traffic between the client and the server. An attack could prevent users from reaching the secured pages.

General Application Security

Users in Sage CRM can be set up so that they experience Sage CRM in very different ways. Individual users will authenticate using their username and passwords but because they belong to different teams, or are assigned different security profiles they will find they have very different rights.

Any valid user credentials within Sage CRM that can be used to logon through the main interface can be used with the REST API. But what that user can see or do is subject to rights defined by the security profile and field-level security. In the main interface these rights control access to functional areas of the system such as marketing or the ability to create and edit reports or to send mass emails or export data.

All requests must be authenticated and then access to the data is limited in the same way the user's access is controlled within the interface.

But most importantly for the REST API, these settings control a users ability to insert, edit or update data. A user can be denied access to any main entity within the system, for example, a user not allowed to see any cases would not be able to retrieve any data from that table. If a user can not update a record then an attempt to perform an edit will return an error. This level of control goes down to individual fields that a user may or may not access.