Skip to main content
Version: Latest (4.54.0)

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 VariableDefault Value
XILL4_KEYCLOAK_DISABLEDfalse
XILL4_KEYCLOAK_URL
XILL4_KEYCLOAK_REDIRECT_URLhttp://localhost:8000
XILL4_KEYCLOAK_CLIENT_IDxill4
XILL4_KEYCLOAK_CLIENT_SECRET
XILL4_KEYCLOAK_REALMXill4
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