Authentication

Xill4 can be deployed with authentication in place. Xill4 doesn't provide user management, but supports OpenID. Xill4 uses Keycloak to implement OpenID. Keycloak supports many forms of authentication, for example social login or Active Directory. This guide will not explain how to connect identity providers to Keycloak. This guide will explain how to configure Xill4 to work with Keycloak and vice versa.

Keycloak

Prerequisites

Xill4 works with Keycloak version 17 and above.

Configuration

Follow the following steps to setup Keycloak to work with Xill4:

1. Create a new Realm.
2. Create a new Client.
3. Enable Authorization and Client authentication on the client.
4. Set Web origins to the hostname or IP address where Xill4 is deployed. Note that Xill4 runs on port 8000 by default.
5. Set Valid redirect URIs to the hostname or IP from step 4 with /auth/callback appended.
6. Set Valid post logout redirect URIs to the hostname or IP from step 4.
7. Setup your preferred Identity Provider.

Security recommendations

Although not necessary, it is highly advised to follow these security recommendations.

Remove unnecessary scopes

When a token is generated by Keycloak it will hold metadata about the user, of which only a fragment is needed. We therefore recommend to remove all default scopes for the Xill4 client. The following steps will help you remove these scopes.

1. Open the Keycloak admin console and navigate to your Xill4 realm.
2. In the navigation bar on the left select Clients and open the Xill4 client (created in the previous section).
3. Open the Client Scopes tab.
4. From the list of scopes all but a few scopes can be removed. All but: acr, roles, and *-dedicated (starts with your client name). Check all the checkboxes of the scopes to remove and open the context menu by clicking the three vertical ellipsis at the top.
5. Finally click remove.

Xill4

The following environment variables are available for configuration. If a variable doesn't have a default value, it must be set.

Environment Variable	Default Value
XILL4_KEYCLOAK_DISABLED	false
XILL4_KEYCLOAK_URL
XILL4_KEYCLOAK_REDIRECT_URL	http://localhost:8000
XILL4_KEYCLOAK_CLIENT_ID	xill4
XILL4_KEYCLOAK_CLIENT_SECRET
XILL4_KEYCLOAK_REALM	Xill4
XILL4_KEYCLOAK_AUTH_URL	{KEYCLOAK_URL}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/auth
XILL4_KEYCLOAK_JWKS_URL	{KEYCLOAK_URL}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/certs
XILL4_KEYCLOAK_TOKEN_URL	{KEYCLOAK_URL}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/token