

REST Security

The Chaos Engine REST API is secured using a cookie-based Authentication System. Users can log in using preconfigured username and password combinations to grant access roles. The roles they are granted will determine which API Endpoints they are allowed to access.

Authentication Credentials

Credentials are preconfigured in Spring Properties under an array of chaos.security.users. Each user object will have a username, a password, and a comma separated list of roles. They can be configured in any location that Chaos Engine looks for properties, and follows the same relaxed-binding mechanism that other variables use.

``` json tab="Vault" { "chaos.security.users[0].username": "admin", "chaos.security.users[0].password": "admin_P@ssw0rd", "chaos.security.users[0].roles": "ADMIN", "chaos.security.users[1].username": "user", "chaos.security.users[1].password": "user_P@ssw0rd", "chaos.security.users[1].roles": "USER" }

``` shell tab="ENV Vars"
CHAOS_SECURITY_USERS_0_USERNAME=admin
CHAOS_SECURITY_USERS_0_PASSWORD=admin_P@ssw0rd
CHAOS_SECURITY_USERS_0_ROLES=ADMIN
CHAOS_SECURITY_USERS_1_USERNAME=user
CHAOS_SECURITY_USERS_1_PASSWORD=user_P@ssw0rd
CHAOS_SECURITY_USERS_1_ROLES=USER

Authentication Endpoint

Authentication can be done by sending a POST request to the /login endpoint of the Chaos Engine, and specifying a username and password in the data fields. Be sure to capture the cookies returned by this request.

```shell tab="Request" curl -vvv -s localhost:8080/login -X POST --data username=admin --data password=admin -c /dev/stdout
* Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 8080 (#0)

POST /login HTTP/1.1 Host: localhost:8080 User-Agent: curl/7.58.0 Accept: / Content-Length: 29 Content-Type: application/x-www-form-urlencoded

• upload completely sent off: 29 out of 29 bytes

  ```shell tab="Response" hl_lines="1 5 6"
  < HTTP/1.1 200 
  * cookie size: name/val 10 + 32 bytes
  * cookie size: name/val 4 + 1 bytes
  * cookie size: name/val 8 + 0 bytes
  * Added cookie JSESSIONID="2DED401442B2AC62DD15DC0B60A62BA5" for domain localhost, path /, expire 0
  < Set-Cookie: JSESSIONID=2DED401442B2AC62DD15DC0B60A62BA5; Path=/; HttpOnly
  < X-Content-Type-Options: nosniff
  < X-XSS-Protection: 1; mode=block
  < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
  < Pragma: no-cache
  < Expires: 0
  < X-Frame-Options: DENY
  < Content-Length: 0
  < Date: Fri, 01 Nov 2019 18:05:06 GMT
  < 
  * Connection #0 to host localhost left intact
  

```shell tab="Cookies" hl_lines="5"

Netscape HTTP Cookie File

https://curl.haxx.se/docs/http-cookies.html

This file was generated by libcurl! Edit at your own risk.

HttpOnly_localhost FALSE / FALSE 0 JSESSIONID 2DED401442B2AC62DD15DC0B60A62BA5

```

Sending Authenticated Requests

Sending the JSESSIONID cookie that was returned by the login request along with any REST call in order to authenticate it.

Ending a session

Sending the JSESSIONID cookie to the /logout endpoint in a POST request will terminate the session. The session will also end after 15 minutes of inactivity.

Permission Levels

There are three distinct levels of permissions programmed into the system.

Unauthenticated

Unauthenticated users can access the GET /health endpoint, in order for container orchestrators (i.e., Kubernetes) to run a health check of the system.

Generic Authentication

Authenticated users with no specific roles can access any GET based endpoint.

Admin Authentication

Users with the ADMIN role can access all endpoints.

Disabling Security Requirements

It is possible that in some environments, you may want to disable the security layer (for example, in a CICD Pipeline). This can be accomplished by setting the property chaos.security.enabled with a value of false.