Providing access to a restricted access system over the Internet comes with a variety of security challenges. The ICWS API attempts to address each aspect of security that is within its domain, including things like transport-layer data encryption, secure session handling, and protection from common web vulnerabilities like CSRF and XSS. Securing web applications that use ICWS should be considered a joint effort between the API itself and the application that uses the API. Both components must work together to protect the system from unauthorized use.
This topic contains the following sections:
ICWS uses industry standard TLS encryption to protect API communication between client and server. It is recommended that all communication between client and server use HTTPS. Securing communication between ICWS and clients is important because ICWS provides information that may be personal, secret, or protected by law depending on the industry and jurisdiction. Securing the entire communication channel is necessary because applications built on ICWS APIs may be used in environments where network traffic can be passively observed or even actively manipulated (e.g. unsecured wireless networks). Eavesdropping and man-in-the-middle attacks are prevented by using encrypted HTTP communication for all API access.
In order for clients to access the API via HTTPS, the ICWS host must have a valid SSL/TLS server certificate. In general, clients will only accept the server's certificate if it: is signed by a trusted Certificate Authority, is not expired, has not been revoked, and matches the domain(s) in use by the host(s). Acquiring and configuring server certificates is a step that is unique to each deployment since a certificate is only applicable to specific domains and may be issued by one of many different certificate authorities.
Web applications that proxy calls through a content server to ICWS may opt to use HTTPS between client and reverse proxy while using normal unencrypted HTTP between the proxy and the ICWS host(s). This configuration provides the benefit of an encrypted communication channel over the untrusted network (e.g. the Internet), while avoiding the performance overhead of serving HTTPS on the ICWS hosts themselves. It's important to note that the internal communication between reverse proxy and ICWS is vulnerable to eavesdropping and/or man-in-the-middle attacks by someone with access to the internal network. In this type of deployment, it's also important to use HTTPS for all content served by the reverse proxy web server to ensure that API calls from the browser are trustworthy since the content they received is trustworthy.
Nearly all of the API provided by ICWS requires user authentication via the Connection namespace. Once a user is authenticated, ICWS provides an HTTP cookie to the client that is the user's token representing the session on the server. The cookie's content is not the server's session ID; it's a randomly generated token to be used for that session. There is no pattern or repeatability to how the cookies are generated, so it's not possible to predict another user's session cookie value given a cookie from another session on the same machine.
The client must supply the session cookie with all API requests that require an authenticated session. If an API request is made without a valid session cookie, the ICWS host will refuse to process the request and indicate that authentication is required. The cookie is only good for the session from which it was acquired; it cannot be reused by another user or by the same user for another session at a later time.
An ICWS session cookie becomes invalid when the corresponding session on the server is disconnected. A session will be disconnected if the connection resource is deleted via API request. A session may also be disconnected on the server for other reasons, like if the same user account begins a session from another client or if the ICWS service is restarted. If a session is active but the client is not making regular requests to the API, the session will eventually expire and be disconnected on the server. Subsequent API access will require a new authenticated session to be started.
Though not directly implemented by ICWS, Interaction Center password policies are enforced for user accounts that connect via ICWS just as they would be otherwise. This means the Interaction Center password policy configuration options related to account lockout are in effect when connecting via ICWS, including the number of failed logon attempts allowed, the lockout duration, and the failed logon count reset timeout.
It is recommended that the password policy for any user accounts accessing ICWS enforce a maximum failed logon attempts limit with a lockout period. This ensures that a malicious party cannot make unlimited password guesses for a specific user. That said, using account lockout makes it possible to lock someone else out of their account as a form of denial-of-service if the other person's user ID is known. It may be important to balance the configuration of failed logon attempts and lockout duration so that legitimate users can't be denied access by another user.
Neither ICWS nor Interaction Center itself provides a password self-recovery option. Users must always contact an administrator to reset their Interaction Center password. Interaction Center may use email to inform the user of a password reset, but that feature is provided by Interaction Center itself, independent of ICWS.
Without proper security measures in place, it's possible for a malicious third party to hijack a user's session to steal data or modify the system by tricking the user into visiting a specially formed URL or even just by being on the same unsecured WiFi network as the user. Since there are many ways a session might be hijacked, there are several steps that must be taken to avoid it both by the API itself and by applications that use the API.
ICWS takes two important steps to prevent session hijacking: it requires HTTPS for all requests, and it marks the session cookie with the HttpOnly flag. Using encrypted communication via HTTPS is extremely important because it prevents the loss of sensitive information by network snooping. Without HTTPS a user on an unsecured WiFi network would have no recourse against someone on the same network stealing their credentials or authentication token to impersonate them. The HttpOnly flag is important because it prevents XSS vulnerabilities that stem from cookie theft made possible by JavaScript's document.cookie. Without JavaScript access to the session cookie, it is much more difficult to steal the session cookie using specially formed URIs or reflected API content.
Cross-site Request Forgery is a type of web vulnerability that exploits the behavior of HTTP cookies in web browsers to allow 3rd party content to issue requests on behalf of an authenticated user without their knowledge or consent. A complete explanation of CSRF is outside the scope of this document, but the idea is relatively simple: web applications that use cookies to track authenticated sessions have no way of preventing third party content from making requests against a user's session because the browser will always send the cookies no matter who originates the request.
In addition to the session cookie, ICWS issues a second token when the session is created that must be used by clients for CSRF prevention. The CSRF token is provided in the ININ-ICWS-CSRF-Token HTTP response header for a successful connection request. It is a long string of random characters that is not predictable from one session to another. This header must be supplied by the client on subsequent HTTP requests for API resources.
Using the additional non-cookie token helps to prevent CSRF because it introduces a secondary proof of authenticity into API requests. Browsers will always send cookies automatically, but a custom HTTP header must be added explicitly to each request. The malicious third party won't know the HTTP header value to send because it's only accessible to the application itself. Additionally, authenticated API requests include the session ID in the URL, which makes simple broad-based exploits less likely due to the API URLs being unique per session.
Cross-site scripting (XSS) is arguably the most commonly exploited vulnerability in web applications. It is a persistent problem because of the nature of HTML web pages, which process document markup and interactive script content together. ICWS uses the HttpOnly flag on its session cookie to prevent cookie stealing via XSS, but cookie stealing isn't the only attack made possible by XSS.
API content is generally sent and received in JSON, a serialized object format. JSON content has the interesting property of sometimes being valid JavaScript. In the early days of JSON, web developers capitalized on this by using JavaScript's eval function to deserialize content from the web. Executing JSON content via eval welcomes code injection exploits, and is entirely unnecessary. All modern web browsers provide functions for JSON serialization and deserialization in JSON.stringify and JSON.parse that should be used instead of eval, and there are safe JSON libraries available for older browsers that don't have it natively.
Using safe JSON deserialization and avoiding JavaScript eval don't completely remove the threat of XSS. The possibility remains that API content that is inserted into HTML could contain text that would be interpreted and executed automatically by the browser, even if malice was not the intent. For this reason, it's important that applications always escape API content that is displayed via HTML. API content is not HTML, so it must be properly escaped to make sure the browser renders it as text, not HTML.
The API itself cannot prevent all types of session hijacking, cookie theft, or XSS. It's important for application developers to be mindful of the risks and to take a proactive approach to application security.
One of the best aspects of a web API is the ability to provide access to the system on potentially any Internet-connected device, anywhere in the world. Providing that level of access to users unfortunately means the system is open to attack as well. One way to reduce that risk is to add an extra layer between the ICWS host machine and the external network (e.g. the Internet). Using a reverse proxy web server (also sometimes called a "gateway") is a common and effective way to isolate an internal application server, protecting it from certain types of attacks that could come from the external network (e.g. probing, denial-of-service, etc). In a typical deployment, a reverse proxy web server would be deployed in the DMZ or perimeter network with the ICWS host machine isolated in a firewalled internal network. The reverse proxy would be exposed to the external network, accepting all incoming requests and passing them through to the ICWS host on the internal network.
The recommended configuration for HTML web applications that use ICWS is to host application content (HTML, JavaScript, CSS, etc.) on a web server that also functions as a reverse proxy to an internal ICWS host. In addition to providing network isolation for ICWS, this avoids browser restrictions related to cross origin resource sharing.
See the Web Proxies topic for more information about configuring a reverse proxy with ICWS.
It's important to configure a reverse proxy server to only serve proxied ICWS content via HTTPS to ensure that the communication on the untrusted network is encrypted, even if the internal request to ICWS is allowed to proceed without HTTPS for performance reasons. In other words, requests from a client to the reverse proxy should always start with https:// to make sure the API content is encrypted over the Internet. This often means it will be necessary to acquire and configure a SSL/TLS certificate for the domain used by the reverse proxy server.
As discussed in the Cross-site Scripting (XSS) section, XSS is one of the most common types of web vulnerabilities, and it's something that ICWS can't totally prevent. It's important for web applications to include safeguards that prevent XSS vulnerabilities in web applications.
The two most important things to remember to prevent XSS vulnerabilities are:
eval it!Making sure JSON content is not eval'd, and making sure API content is treated as text and instead of HTML (by escaping it) will help to prevent XSS vulnerabilities in any web application that uses ICWS.
Applications that use ICWS APIs have access to a lot of information that is potentially sensitive. The API may take measures to protect the security and privacy of users' data, but the application itself must also be mindful of how it stores and transmits data once it is retrieved from the API. Here are some things applications can do to protect users' data:
<script>s from untrusted hosts in a web application.The API service itself can go to great lengths to protect data in transit and to prevent unauthorized API use, but applications must be cautious with data retrieved from the API or provided by the user.