SearchVarnish 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 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.
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 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 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.
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).
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.
Long lived tokens are actually long lived sessions where the expiration time can be configured to any value. The session can be assigned a specific role. The role must however have same or lower permissions than the logged in user. If no role is used, the token will have the same permissions as the logged in user.
Another important thing is that the token cannot be refreshed as a regular session. The expiration time is set to the configured time for both refresh and access token. Once the token is end of life, a new token must be generated.
Long Lived Tokens can only be generated by organizational users. Long lived session will be of kind
API Token.
Example of generating a token using vcli. The output will be in JSON format, where the accessToken key contains the bearer token for API authentication. The accessExpire key indicates the token’s expiration time as a Unix timestamp.
# Create a default token with 24h expiration time.
vcli session create
# With a custom expiration time (1 year) and custom label to identify the token.
vcli session create -e 8760h --label myStatToken
# With a custom role (with id 1)
vcli session create -e 8760h --label myStatToken --role 1
# List all sessions, including long lived tokens.
vcli sess ls
+----+----------+--------------+-------------+------------+------+---------------------+
| ID | Account | Organization | Label | Kind | Role | Expire |
+----+----------+--------------+-------------+------------+------+---------------------+
| 2 | test2(2) | test(1) | vcli | User Login | | 2025-03-18 10:00:18 |
| 7 | test2(2) | test(1) | myStatToken | API Token | | 2026-03-18 10:03:48 |
+----+----------+--------------+-------------+------------+------+---------------------+