Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  2. /
  3. Local Administrator Guides
  4. /
  5. Fuzzball Entity Management
  6. /
  7. Keycloak Configuration

Keycloak Configuration

If you are not delegating user authentication to an upstream identity provider such as LDAP, you should ensure that the Keycloak service integrated into Orchestrate is configured correctly. You should also change the Fuzzball password of the cluster admin user, which was given the default password when Orchestrate was deployed.

This guide walks through the necessary Keycloak adjustments that should be applied once per deployment to improve security and user experience.

Overview

This configuration process involves two main tasks. Both of the following will be accomplished via the steps below:

  1. Configure password policies to require users to change their password on first login.
  2. Change the password of the Fuzzball admin user that owns the default organization.

Accessing Keycloak

First, you need to log into your Keycloak admin interface. The URL will depend on your deployment but will fit the pattern below.

https://auth.YOUR_DOMAIN/auth

See the guide to accessing the web interface for details on how to obtain the URL, connect via a tunnel if necessary, and fetch the keycloak login details from Kubernetes.

Step 1: Switch to Fuzzball Realm

After logging into Keycloak, ensure you’re working in the correct realm:

  1. Change the realm to “Fuzzball” using the dropdown menu below the Keycloak logo
Keycloak realm selection
The name of the realm created for Fuzzball defaults to “Fuzzball” but is configurable in local deployments. If you selected a different name switch to the realm name you specified.

Step 2: Change Organization Owner’s Password

The organization owner account (configured as keycloak.create.ownerEmail in the Orchestrate configuration) initially uses the default password (keycloak.create.defaultUserPassword which defaults to a secure random string) for new users created without an explicit password. This should be changed to a unique password.

  1. Navigate to Users in the left sidebar.
  2. You should see your existing users. In the case of a new deployment the only user here should be the Fuzzball organization owner created automatically during deployment.
  3. Click on the organization owner user account.
  4. Select the Credentials tab.
User credentials tab
  1. Click Reset Password.
  2. Enter a new, secure password for the organization owner.
  3. Deselect “Temporary” if you don’t want the admin user to have to reset again immediately.
Password change dialog

Step 3: Configure Required Password Changes

To improve security, configure Keycloak to force new users to change their password on first login:

  1. Go to Authentication in the left sidebar.
  2. Select the Required Actions tab.
  3. Find Update Password in the list.
  4. Toggle Set as default action to ON.
Password change default action

This ensures that when new users log in for the first time they will be required to change their password from the password explicitly set when the user was created with the Fuzzball CLI or the default password when no explicit password was provided.

Step 4: Verify Configuration

After completing these steps:

  1. Log out of Keycloak.
  2. Test the configuration by logging into the Fuzzball UI with the organization owner account using the new password set above.
  3. If you did not select “Temporary” you should not be forced to change the admin user’s password.

Next Steps

With Keycloak properly configured, you can now proceed with:

Important Notes

  • As of the time of this writing, the password shown as the cluster admin’s password in the output of the deployment info script is the default new user password that was assigned to the admin user when Orchestrate was initially configured. It does not reflect any changes made to the cluster admin in keycloak (as described above). Changes to the default user password after the initial configuration will be reflected in this password but will not affect the existing admin user.
  • If you edit the Orchestrate deployment to change keycloak.create.defaultUserPassword, the Fuzzball agent service has to be restarted for the change to become effective. This can be done with kubectl rollout restart -n fuzzball deployment/fuzzball-agent.
  • Share the default password securely with new users when you create their accounts.
  • New users will be forced to change this default password on their first login.
  • This configuration only needs to be done once per Fuzzball deployment.
gdoc_arrow_left_alt Deleting Accounts User Management gdoc_arrow_right_alt