Wallaroo Enterprise User Management

Wallaroo uses Keycloak for user authentication, authorization, and management. Enterprise customers can manage their users in Keycloak through its web-based UI, or programmatically through Keycloak’s REST API.

In enterprise deployments customers store their Wallaroo user accounts either directly in Keycloak or utilize its User Federation feature. Integration with external/public Identity Providers (such as popular social networks) is not expected at this time.

See the Keycloak User Guide for more details: https://www.keycloak.org/documentation.html

The Keycloak instance deployed in the wallaroo Kubernetes namespace comes pre-configured with a single administrator user in the Master realm. All users must be managed within that realm.

Accessing The Wallaroo Keycloak Dashboard

Enterprise customers may access their Wallaroo Keycloak dashboard by navigating to https://<prefix>.keycloak.<suffix>, depending on their choice domain prefix and suffix supplied during installation.

Obtaining Administrator Credentials

The standard Wallaroo installation creates the user admin by default and assigns them a randomly generated password. The admin user credentials are obtained which may be obtained directly from Kubernetes with the following commands, assuming the Wallaroo instance namespace is wallaroo.

    kubectl -n wallaroo \
    get secret keycloak-admin-secret \
    -o go-template='{{.data.KEYCLOAK_ADMIN_USER | base64decode }}{{"\n"}}'

    kubectl -n wallaroo \
    get secret keycloak-admin-secret \
    -o go-template='{{.data.KEYCLOAK_ADMIN_PASSWORD | base64decode }}{{"\n"}}'

Accessing the User Management Panel

In the Keycloak Administration Console, click Manage -> Users in the left-hand side menu. Click the View all users button to see existing users.

Adding Users

To add a user through the Keycloak interface:

1. Click the Add user button in the top-right corner.

2. Enter the following:

   

   1. A unique username and email address.
   2. Ensure that the Email Verified checkbox is checked - Wallaroo does not perform email verification.
   3. Under Required User Actions, set Update Password so the user will update their password the next time they log in.

3. Click Save.

4. Once saved, select Credentials tab, then the Set Password section, enter the new user’s desired initial password in the Password and Password Confirmation fields.

   

5. Click Set Password. Confirm the action when prompted. This will force the user to set their own password when they log in to Wallaroo.

6. Log out of Keycloak as the Admin user before resuming other Wallaroo actions.

Managing Users Programmatically

It is possible to manage users through Keycloak’s Admin REST API. See https://www.keycloak.org/documentation.html for details.

Wallaroo simplifies this task with a small Python script, which can be utilized in a Jupyter notebook running in the wallaroo namespace through the following process:

1. Create a new Python file: In your JupyterHub workspace, create a new Python file named keycloak.py and populate it with the following:

2. Import the following libraries:

   import json
   import requests
   
   class Keycloak:
       def __init__(self, host, port, admin_username, admin_password):
           self.host = host
           self.port = port
           self.admin_username = admin_username
           self.admin_password = admin_password
   
       def get_token(self):
           """Using a hardcoded admin password, obtain a session token from keycloak"""
           url = f"http://{self.host}:{self.port}/auth/realms/master/protocol/openid-connect/token"
           headers = {
               "Content-Type": "application/x-www-form-urlencoded",
               "Accept": "application/json",
           }
           data = {
               "username": self.admin_username,
               "password": self.admin_password,
               "grant_type": "password",
               "client_id": "admin-cli",
           }
           resp = requests.post(url, headers=headers, data=data)
           assert resp.status_code == 200
           token = resp.json()["access_token"]
           assert len(token) > 800
           self.token = token
   
       def list_users(self):
           url = f"http://{self.host}:{self.port}/auth/admin/realms/master/users"
           headers = {
               "Content-Type": "application/json",
               "Authorization": f"bearer {self.token}",
           }
           data={}
           resp = requests.get(url, headers=headers, data=data)
           return resp
   
       def create_user(self, username, password, email):
           """Create a keycloak test user. Returns ID."""
           url = f"http://{self.host}:{self.port}/auth/admin/realms/master/users"
           headers = {
               "Content-Type": "application/json",
               "Authorization": f"bearer {self.token}",
           }
           payload = {
               "username": username,
               "enabled": "true",
               "emailVerified": "true",
               "email": email,
               "credentials": [
                   {
                       "type": "password",
                       "value": password,
                       "temporary": "false",
                   }
               ],
           }
           resp = requests.post(url, headers=headers, data=json.dumps(payload))
           assert resp.status_code == 201
           return resp.headers["Location"].split("/")[-1]
   
       def delete_user(self, userid):
           """Remove a keycloak user"""
           url = f"http://{self.host}:{self.port}/auth/admin/realms/master/users/{userid}"
           headers = {
               "Content-Type": "application/json",
               "Authorization": f"bearer {self.token}",
           }
           resp = requests.delete(url, headers=headers)
   

3. Create a Keycloak admin client: In JupyterHub environment, create a new Jupyter notebook in the same directory as your keycloak.py file.

   Import the new Python module and instantiate your Keycloak client, supplying your administrator user credentials (3rd and 4th arguments).

   For more information on retrieving your KeyClock username and password, see Obtaining Administrator Credentials.

   from keycloak import Keycloak
   kc = Keycloak('keycloak', 8080, 'admin', 'admin')
   

4. Obtain an authentication token: Before invoking any methods, you must obtain a fresh authentication token by calling get_token() method. This will obtain a new token, which is valid for 60 seconds, and cache it in the client.

   kc.get_token()
   

Listing existing users

To list existing users, use the Keycloak list_users method:

resp = kc.list_users()
resp.json()

Creating new users

To create a new user, use the Keycloak create_user() and supply their unique username, password, as well as a unique email address:

kc.create_user('testuser1', 'abc123', 'testuser1@example.com')

If successful, the return value will be the new user’s unique identifier generated by Keycloak.