Varnish Controller

Identity Provider

Each organization can be configured with an Identity Provider. This chapter will describe how to set up a very basic Keycloak installation via a Docker container for test purposes.

Keycloak can integrate with LDAP, AD, Github, Google, etc. as third-party authentication providers. Note that authorization cannot be configured in a third-party provider since Varnish Controller has its own authorization system.

Setup Keycloak for development

For development purposes it is recommended to start Keycloak in development mode. This can be done with the following command:

docker run -d -p 8080:8080 --name keycloak -e KEYCLOAK_ADMIN=keycloak -e KEYCLOAK_ADMIN_PASSWORD=test start-dev

This will spin up a Docker container with keycloak, setting administrator username to keycloak and password test. It will start listening on localhost:8080.

Setup Keycloak for production

To run Keycloak in production it is mandatory to setup HTTPS certificates and keys. There is good documentation on how to do this on Keycloaks documentation

You can run Keycloak in docker as well on production though it is highly recommended to specify an external database that is persistent in this case. Keycloak has support for PostgreSQL so you could use the same database server as you are using for the Varnish Controller.

Configure Keycloak

  1. Open http://localhost:8080/admin/ in the web browser. Login with keycloak and password test.
  2. Open the drop-down menu on the left hand side that says master and click the Create realm button.
  3. Upload a JSON file with the following contents, replace the UI_URL with the URL the UI is reachable on.

The redirectUris specify the URLs that are allowed to authenticate as a redirect URL. All other URLS will be ignored.

	"realm": "demo",
	"enabled": true,
	"users": [
			"username": "demo",
			"enabled": true,
			"credentials": [
					"type": "password",
					"value": "test"
			"realmRoles": ["user"]
	"roles": {
		"realm": [
				"name": "user",
				"description": "User privileges"
				"name": "admin",
				"description": "Administrator privileges"
	"defaultRoles": ["user"],
	"clients": [
			"clientId": "demo-client",
			"enabled": true,
			"publicClient": false,
			"clientAuthenticatorType": "client-secret",
			"secret": "b124d51e-93e8-48c0-85cd-803657765040",
			"redirectUris": [

Configure Varnish Controller

The IDP is configured per organization, hence, an organization needs to be created.

# Login with system admin
vcli login http://localhost:8002 -u test
Password: ****

# Create an organization
vcli org add neworg

# Add IDP to the org (id 1 here, replace client-secret with your client-secret)
# The URL is the one for Keycloak's OIDC (OpenID Connect) path.
vcli idp add --org 1 --base-url http://localhost:8080/realms/demo/.well-known/openid-configuration --client-id demo-client --client-secret b124d51e-93e8-48c0-85cd-803657765040

We create a organization at the Organizations page. We need a name and in the IDP configuration at the bottom we need to add Base URL, Client ID and a Client secret from Keycloak.

Create organization with IDP configuration

Login Using IDP in the UI

  1. Click the link on the login page that says “Log in with identity provider”.
  2. Fill in the name of the organization and continue.
  3. A pop-up will appear, login with the user credentials.
  4. If the login was successful you will be redirected to the Varnish Controller UI.

Login Using IDP in the VCLI

Log in using VCLI, specify organization name and make sure to use --idp to specify that we should use IDP for login.

# Login using IDP to our organization called "neworg"
vcli login -o neworg --idp
Endpoint: http://localhost:8002
Go to the URL below and login:

Waiting 60sec for access...

Click the given link and log in via the Keycloak login form that is shown in the browser.


On a successful login, Keycloak and the Varnish Controller exchange access and refresh tokens automatically. You can close the window that displays the access and refresh tokens. The CLI will print a success message or timeout message if no successful login occurred within 60 seconds.

Login successful.

If it is the first login with the account, the account will not have any permissions. The permissions must be added by the organization administrator or system administrator.

See authorization examples how to add permissions.