Hub Enterprise with Multi-Tenancy
- Eran Galily
Running OpenLegacy Hub Enterprise with Multi-Tenancy
Note: The following guide refers to Keycloak version 26.0.0.
Step 1: Master API Key Configuration
When running the Hub Enterprise, you need to define the Master API Key as an environment variable. This key is required for administrative functions and must be securely managed.
Master API Key Configuration
A Master API Key is required for administrative functions, such as creating new tenants. It must be securely managed as an environment variable.
● Environment Variable: OL_ENT_MASTER_API_KEY
When initializing the Hub Enterprise, you run the container with this master API key set as an environment variable. Whenever you want to run an administrative function, include the header x-master-key: <master_api_key> in the request.
Step 2: Creating a New Tenant
The next step in initializing multi-tenancy in OpenLegacy Hub Enterprise is to create a new tenant.
1. Create Tenant
The "Create Tenant" endpoint allows you to create a new tenant in the system, creating a new keycloak admin user and automatically generating a unique user API key for the tenant upon creation.
Endpoint
● POST /backoffice/tenants
Authorization
● Header: x-api-key Hub user/acount api key
● Header: x-master-key (Master API key required)
Request Body
{
"contactPersonEmail": "Contact Email",
"organization": "Organization Name"
}
● contactPersonEmail: (required) The email of the contact person for the tenant. This value must include a valid email, which will be used as the default admin username in further steps.
● organization: (required) The name of the tenant's organization.
Responses
● 200 OK
○ Description: Tenant, admin user in Keycloak, and its API key created successfully. The admin user is created in Keycloak with admin permissions for the tenant.
○ Body:
{
"tenantId": "<tenant_id>",
"adminUserId": "<admin_user_id>",
"apiKey": "<user_api_key>"
}
Licensing
● The tenant will be created with the same master license as the tenant that invoked the request.
● If there is no master license connected to the current tenant, the new tenant user will need to provide a master license key during their first login, via a popup window.
Step 3: Accessing the Newly Created Tenant
Once the tenant has been created, you need to access the newly created tenant with the admin user account.
As mentioned in the previous step, an admin user is created in Keycloak with admin permissions for the tenant.
● The admin username is the contactPersonEmail used to create the new tenant.
● The default password for the admin user is ol-hub.
Changing Admin User Credentials
To change these credentials, follow these steps:
Log in using the following credentials:
○ Username: root
○ Password: openlegacy
These credentials can be changed from the environment variables used to initialize the container:
● KEYCLOAK_ADMIN
● KEYCLOAK_ADMIN_PASSWORD
In the top left corner, select the ol-hub realm.
Click on Users.
Find and select the newly created user.
Click on the Credentials tab.
Delete the default password and set a new one.
Manually Creating a User in Keycloak
Step 1: Create a User in Keycloak
If you need to create a user manually in Keycloak, follow these steps:
Log in using the following credentials:
Username: root
Password: openlegacy
These credentials can be changed from the environment variables used to initialize the container:
● KEYCLOAK_ADMIN
● KEYCLOAK_ADMIN_PASSWORD
In the top left corner, select the ol-hub realm.
Click on Users.
Click on Add User.
Fill in the form with the user details.
Step 2: Create Credentials And Attributes for the User
Click on the Credentials tab.
Set a new password for the user.
Click on the Attributes tab.
Add the following attributes:
○ ol-fullname: The full name of the user.
○ ol-company: The company associated with the user.
○ ol-tenantId: The desired tenant ID. This value must match the tenant ID for the new tenant.
Step 3: Creating the User Role in the Database
For the user to obtain permissions, you will need to create the appropriate permission resource in the database. To do so:
It would be best if you invoked the following endpoint:
Endpoint: /backend/api/permissions/useres/:userId/tenant-roles (POST)
Input Body:
{
"role": "<ADMIN/CONTRIBUTOR/MEMBER>"
}
