Sessions

Varnish Controller acts as an identity provider, with support for Keycloak and basic auth. It hands out both access tokens and refresh tokens.

Varnish Controller follows the same idea as Oauth2+OIDC with access and refresh tokens.

Login Example

Login via basic auth:

$ curl -s -X POST -utest:test http://localhost:8002/api/v1/auth/login  | jq .
{
  "accessExpire": 1601885112,
  "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6MiwidHlwIjoiSldUIn0.eyJleHAiOjE2MDE4ODUxMTIsImp0aSI6IjRiZmExMjI1NjdhYTVhZTE4YzFkNTAzNTkyOTUyYjQzIiwibmJmIjoxNjAxODg0NTEyLCJ0eXAiOiJCZWFyZXIiLCJ2YXJuaXNoQ29udHJvbGxlciI6bnVsbH0.HP5gK4Ln-8BGe3xJ3ZiOOiqnCUdwB58MO8q3K8FBnfXhRCqmGxTLzOF9cfA29a8XieBTal9W63GzVlkg3iUe9q7itIFNm8XSMVNAzQMp49F1LfPSNnwIe9UaD63rCnBDEBp6bdnDbtQXmQCTwIE7IhqIGZ_3DUxu7fjFb7EwEhk",
  "refreshExpire": 1601888112,
  "refreshToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6MiwidHlwIjoiSldUIn0.eyJleHAiOjE2MDE4ODgxMTIsImp0aSI6IjRiZmExMjI1NjdhYTVhZTE4YzFkNTAzNTkyOTUyYjQzIiwibmJmIjoxNjAxODg0NTEyLCJ0eXAiOiJSZWZyZXNoIiwidmFybmlzaENvbnRyb2xsZXIiOnt9fQ.Vb8322BbYIYbS76GjMx3W-apnsHb4nx8jds0SJFd1GcmmdJvSCq63gUBoYGRMyiZjm7G8__9uCb3G9gwkIjgzifqTWOGXu0_rfA3ihjPU23ikDvUvQ3zMRxmamSiCnoeqUDy6SoduyM7TYN7XVluDDMxOGPnWGAhNKp_udwLdqU"
}

In the above example a login is performed with the system administrator. The result is a accessExpire value that consists of a unix timestamp when the access token expires. The refreshExpire contains a unix timestamp when the refresh token expires. Then it returns the accessToken and refreshToken.

The access and refresh expiration times can be configured per organization (accessTTL and refreshTTL) for basic auth. If an IDP is used, the expiration times for access and refresh tokens are set by the IDP.

The following sections will describe how to use both of these tokens.

Sessions

A session is created when a user logs in. The session consists of an access token and a refresh token, described below. These tokens are encoded as JSON Web Tokens (JWT) and are cryptographically signed.

Access Tokens

Access tokens are rather short lived. They are used to access resources (API endpoints) and for each API call the access token should be specified in the header.

$ curl -H "Authorization: Bearer <access_token>" http://localhost:8002/api/v1/agents

Once the access token expires, it cannot be used any more. A new access token can be retrieved by using the refresh token without the need to log in again.

Access tokens should be kept secret, but since they are short lived they may only be used for a rather short period of time, and access will be automatically revoked once they expire.

Refresh Tokens

Refresh tokens are long lived and cannot be used to access resources. They can only be used to retrieve a new access token.

Requesting a new access token also generates a new refresh token.

$ curl -X POST -H "Authorization: Refresh <refresh_token>" localhost:8002/api/v1/auth/refresh

Refresh tokens should be kept safe and secret since they can be used to retrieve access tokens and are long lived.

Refresh tokens can be revoked manually via the REST API, which is necessary if they are compromised.

# Delete the session to revoke
curl -X DELETE -s -H "Authorization: Bearer <access-token>" http://localhost:8002/api/v1/sessions/<session-id>

When the user logs out, the refresh token and access token are automatically revoked.

JWT

The access and refresh tokens consist of cryptographically signed JSON Web Tokens (JWT). They cannot be tampered with and are validated in the api-gw before a request is sent to brainz.

Brainz handles the private keys to sign the JWTs with and have a rolling update of keys in the database, which are used to sign the JWTs with. Hence, the signing keys are only used for a while before a new pair is generated and used to sign with. Time between each key generation can be configured in brainz (see brainz - Max Key Age).

Revoking sessions

When revoking a session the users is forcefully logged out. Revoking can be done by deleting a session or checking the checkbox to revoke sessions when changing permissions so the user is forced to login again.

When using Keycloak (Identity Provider) revoking a session in the Varnish Controller will also revoke the session and logout the user from the IDP platform. IDP does not have support to push a revocation from IDP towards the Varnish Controller. When a session is revoked in Keycloak the session in the Varnish Controller will have to be manually revoked as well to forcefully logout the user.