Session-Based Authentication

Kraken uses Session-Based Authentication where session data is conveyed within the cookie portion of an HTTP header request.

Kraken enforces that all interactions with it and the API are performed over secure HTTP (i.e., HTTPS). Certificates are required to enable secure communications between the Kraken server and remote clients, and some environments may require certificates NOT be self signed. In these situations, Kraken allows a Kraken Administrator to Manage Certificates on the Kraken appliance.

In addition to enforcing API interaction over HTTPS, all API requests must also be authenticated. This requires the end user application exercising the Kraken API to authenticate against the login endpoint.

Upon logging in with valid username and password credentials on the /apis/v2/login endpoint, the Kraken server will respond with a 204 (No Content) success status response code, and set a cookie with session data.

Example

To demonstrate this with the curl command line application, the following example performs the login action to a remote Kraken server using an example password of krakenapi for the haiadmin administrator user:

Note

The default password for the Kraken server is provided in the Important Notice postcard, which is shipped with the device or available from the Download Center on the Haivision Support Portal.

❯ curl -v -X POST https://kraken.example.com/apis/v2/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "haiadmin", "password": "krakenapi" }' \
  -c cookie.txt

Curl sends this request:

> POST /apis/v2/login HTTP/1.1
> Host: kraken.example.com
> User-Agent: curl/7.77.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 48

And the Kraken response:

< HTTP/1.1 204 No Content
< Server: nginx
< Date: Tue, 08 Mar 2022 23:34:17 GMT
< Connection: keep-alive
< Cache-Control: no-cache, no-store, must-revalidate
< Pragma: no-cache
< Expires: 0
< Set-Cookie: DisplayUnsavedWarning=; Max-Age=100000; Path=/; Secure; SameSite=Strict
< Set-Cookie: id=1NwNImOGcDe4a2yHFUaaPHIicw3ngiCRHPHScQAs; Path=/; HttpOnly; Secure; SameSite=Strict
< Strict-Transport-Security: max-age=31536000; includeSubDomains

The session cookie data is provided in the id parameter. By using the -c cookie.txt curl command, curl writes the cookie data to a file.

Subsequent API requests can now use that stored cookie in cookie.txt to interact with Kraken in an authenticated manner.

For instance, now that the cookie is saved, use it with curl as:

❯ curl -v -X GET https://kraken.example.com/apis/v2/streams \
  --cookie cookie.txt

Additional information about the programming interfaces available within Kraken are discussed in Accessing API v2.0 Documentation.

Refer to your HTTP protocol tool documentation for how it handles cookie storage and inclusion back in HTTP header requests.