Configuring Keycloak Authentication Service in LobeHub
NextAuth (Auth.js) has been fully removed from LobeHub. The NEXT_AUTH_SSO_PROVIDERS and AUTH_URL variables shown below will now cause the deployment to fail at build/startup. This page is kept for historical reference only — use the Better Auth provider guides and the NextAuth to Better Auth migration guide instead.
Keycloak is an open-source identity and access management solution that provides single sign-on, identity brokering, and social login features, suitable for modern applications and services.
If you want to privately deploy Keycloak, we recommend using it together with LobeHub via Docker Compose deployment for easier service management.
Keycloak Configuration Process
If you deploy using a local network IP, this guide assumes:
- Your LobeHub database version IP/port is
http://LobeHub_IP:3210. - Your privately deployed Keycloak domain is
http://KEYCLOAK_IP:8080.
If you deploy using a public network, this guide assumes:
- Your LobeHub database version domain is
https://lobe.example.com. - Your privately deployed Keycloak domain is
https://lobe-auth-api.example.com.
Create Keycloak Realm and Client
Access your privately deployed Keycloak admin console (default is http://localhost:8080/admin) and log in with the administrator account.
-
Create a new Realm
- Click the dropdown menu in the upper left corner and select "Create Realm"
- Enter a name, such as "LobeHub", then click "Create"
-
Create a Client
- Select "Clients" from the left menu, then click "Create client"
- Fill in the following information:
- Client ID:
LobeHub - Client type:
OpenID Connect - Click "Next"
- Client ID:
- On the "Capability config" page:
- Enable "Client authentication"
- Enable "Standard flow"
- Click "Next"
- On the "Login settings" page:
- Valid redirect URIs:
- Local development environment:
http://localhost:3210/api/auth/callback/keycloak - Local network IP deployment:
http://LobeHub_IP:3210/api/auth/callback/keycloak - Public environment:
https://lobe.example.com/api/auth/callback/keycloak
- Local development environment:
- Web origins: Add your LobeHub domain or IP
- Click "Save"
- Valid redirect URIs:
-
Get Client Secret
- On the client details page, switch to the "Credentials" tab
- Copy the "Client secret" value, which will be needed later
Configure Users and Roles (Optional)
-
Create Users
- Select "Users" from the left menu, then click "Add user"
- Fill in the user information and click "Create"
- On the user details page, switch to the "Credentials" tab
- Set a password, and disable the "Temporary" option if needed
- Click "Set Password" to save
-
Create Roles and Permissions
- Select "Realm roles" from the left menu
- Click "Create role"
- Create necessary roles, such as "admin", "user", etc.
- Assign roles to users: On the user details page, switch to the "Role mapping" tab and assign appropriate roles
Disable Registration (Optional)
To ensure the security of your application, it's recommended to control Keycloak's registration functionality.
- Select "Realm settings" from the left menu
- Switch to the "Login" tab
- In the "User registration" section, disable the "User registration" option
- Click "Save" to save the settings
If registration is not disabled, anyone might be able to register and log in to your application. Please configure according to your security requirements.
Configure Environment Variables
Set the obtained client ID and client secret as AUTH_KEYCLOAK_ID and AUTH_KEYCLOAK_SECRET in the LobeHub environment variables.
Configure the LobeHub environment variable AUTH_KEYCLOAK_ISSUER as:
http://localhost:8080/realms/LobeHubfor local development environmenthttp://KEYCLOAK_IP:8080/realms/LobeHubfor privately deployed Keycloak on a local networkhttps://lobe-auth-api.example.com/realms/LobeHubfor Keycloak deployed in a public environment
When deploying LobeHub, you need to configure the following environment variables:
| Environment Variable | Type | Description |
|---|---|---|
AUTH_SECRET | Required | Key used to encrypt Auth.js session tokens. You can generate a key using: openssl rand -base64 32 |
NEXT_AUTH_SSO_PROVIDERS | Required | Select the single sign-on provider for LobeHub. For Keycloak, fill in keycloak. |
AUTH_KEYCLOAK_ID | Required | Keycloak client ID |
AUTH_KEYCLOAK_SECRET | Required | Keycloak client secret |
AUTH_KEYCLOAK_ISSUER | Required | OpenID Connect issuer URL for the Keycloak provider, in the format {keycloak_url}/realms/{realm_name} |
AUTH_URL | Required | This URL specifies the callback address for Auth.js during OAuth verification. Only needed when the default generated redirect address is incorrect. https://lobe.example.com/api/auth |
Visit 📘 Environment Variables for details on related variables.
After successful deployment, users will be able to authenticate through Keycloak and use LobeHub.