Keycloak Configuration

This guide walks through the following steps to improve the security and usability of your Fuzzball cluster.

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

First, you need to log in to 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.

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

The name of the realm created for Fuzzball defaults to “Fuzzball” but is configurable in local deployments. If you selected a different name or created a new organization, switch to the realm name you specified.

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.

5. Click Reset Password.
6. Enter a new, secure password for the organization owner.
7. Deselect “Temporary” if you don’t want the admin user to have to reset again immediately.

To improve security and usability, 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.

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.

After completing these steps:

1. Log out of Keycloak.
2. Test the configuration by logging in to 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.

• The deployment info script displays the default password that was assigned to the cluster admin when Orchestrate was first configured. This password does not automatically update if you change it in Keycloak. 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 may need to be repeated if you create a new organization since new orgs also create new keycloak realms.