Security settings

Authentication

Request authentication using HTTP Basic Auth or JWT tokens is supported. Both make use of secrets to store security credentials. JWT allows you to require authorization by requiring a specific scope. You can use JSON or TypeScript to set the required scope. The blog post on access control using scopes introduces this topic.

Cross Origin Request Sharing

CORS headers are used to control access to a resource (endpoints) from a web application at a different origin. There are some exceptions, but if your API targets web applications, you likely need to configure CORS headers.

You can configure CORS in the start block configuration of any HTTP endpoint flow. Change the CORS option to Allow from selected domains. New fields will appear to configure the domains and allowed headers. Both fields may contain multiple values separated by commas (and optionally a space). The allowed domains field may contain wildcards as part of the domain. That simplifies the CORS model, where this header must have a single domain without wildcards. The response depends on the domain that is provided in the Origin header. For example, setting "*.example.com" as the allowed domain will result in the following response for "test.example.com".

* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
HTTP/2 204
Access-Control-Allow-Origin: test.example.com
Access-Control-Allow-Methods: PUT, GET
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 300
Vary: Origin

You don't set the allowed methods explicitly. These are automatically derived from the HTTP endpoints created in your Flowlet workspace. However, note that all methods share the same CORS headers. That is a technical limitation of the CORS standard. When two methods have similar requirements, the least strict requirement is used in the response. For example, when the POST method allows the X-Foo header, and the PUT method (for the same path) the X-Bar header, then both headers are allowed on both methods.

Check the Allow Credentials field when reading credentials from cookies or HTTP Basic Authentication. This also requires that you provide the includeCredentials flag in the fetch call on the front end. An exception is when you explicitly set the "Authorization" header in the fetch call. The Allow Credentials option and includeCredentials flag are not required in that case. You may read more details in our blog on CORS-headers.

CSRF tokens

The HTTP endpoint configuration form contains a checkbox labeled "Required CSRF token". This activates a mechanism to prevent CSRF attacks.

To make a request with CSRF protection enabled, the client must first execute a GET request to /api/csrf. This is a build-in endpoint that will set a cookie and respond with a token:

HTTP/2 200
Content-Type: application/json
Set-Cookie: csrf=ARm-yhF4hW5laF4yd_3agnSvI3ql0bc6BdnRHFZ8eZU; Domain=flowlet.app; Path=/api; SameSite=Strict; Secure; HttpOnly

{"token":"EBh9dSQVUA3cLSBAIovJNz_978VNfDVpj9rdnduTrPU"}

The subsequent request must provide the token in the X-CSRF-TOKEN header. The server checks the existence of the token and cookie and verifies if they match. If not, the following error is returned:

HTTP/2 400
Content-Type: application/json

{"error":"CSRF token missing or invalid"}

You may use the code below as a boilerplate to construct CSRF-protected requests on the front end.

try {
  const { token } = await (await fetch('https://WORKSPACE.flowlet.app/api/csrf')).json();
  const response = await fetch('https://WORKSPACE.flowlet.app/api/ENDPOINT', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-TOKEN': token
    },
    body: JSON.stringify({
      "...": "..."
    })
  });
} catch (err) {
  setError('Something went wrong...');
}

Flowlet uses the double submit cookie technique for CSRF protection. A few techniques are used to defend against attacks on these mechanisms. These include the use of TLS (with HSTS), SameSite cookies, hashed cookie value, and a custom header name. You may read our blog post on preventing CSRF in APIs for in-depth information.