Connecting to Keycloak
At this point, Greenlight and Keycloak should be up and running and accessible through the web via their FQDNs with HTTPS enabled URLs.
Kindly open your browser and go to your Keycloak URL:
Keycloak landing page:
Select the administration console:
The default Username is admin and password is whatever you have on KEYCLOAK_PASSWORD in the ~/greenlight-run/.env file:
Start by creating a new realm for Greenlight by hovering over the Master realm on the top left corner and clicking on Add realm:
Call the realm greenlight and click on create:
Now that the greenlight realm has been created, make a minimal configuration for it to become ready for use:
However, this default configuration is only for testing purposes and shouldn not be used as is for production environments. We highly recommend checking the official documentations for Keycloak to check the available options and how to change the default configurations to suit your needs and increase security.
You can further configure your realm according to your preferences.
Create a new client by clicking Clients:
Click on Create:
Fill in the form as follow and click Save:
Make sure to set Access Type to Confidential:
And the redirect URI pattern:
Kindly change **
For a DOMAIN_NAME=xlab.bigbluebutton.org, and GL_HOSTNAME=gl.
Type in https://gl.xlab.bigbluebutton.org/*.
All required options should be already set for you, you can still configure the rest of the OpenID client options as you wish - for the configuration, we highly recommend that you check the official OpenID documentations.
After making the changes, we will validate the OpenID client creation by clicking Save at the end of the form:
Kindly go to Credentials and store the Secret key, as we will need to use it later:
We are left to create users and roles if we are willing to use Keycloak local authentication or we can integrate it with an identity provider to act as a broker or with a user federation.
The steps to connect Keycloak to Google OAuth2 API for authentication will be documented. However, feel free to check the official documentations on how to create local accounts if that best suits your case.
Start by going to Configure>Identity Providers:
Click on Add provider… on the select menu and choose the provider you like, for example, with Google:
We need the OpenID client credentials: the Client ID and secret.
For Google, follow this guide to obtain the credentials https://developers.google.com/identity/protocols/oauth2/openid-connect.
Feel free to use different providers and refer to their documentations on how to create and obtain OpenID credentials.
You need to copy the Redirect URI and paste it when asked for, while configuring your OpenID provider:
This is an example coming from creating the Google OAuth2 credentials:
After obtaining the credentials, put them in the form as follow:
After filling in the credentials, please save changes.
Since we have one Identity provider and we do not want the local authentication, let’s make it the default authentication option.
For that, go to, Configure>Authentication:
Click on Actions>Config on the “Identity Provider Redirector” row:
Fill the form as follow:
You should have something similar to this:
Google is now the default authentication option to use.
Connect Greenlight to Keycloak, for that we need the realm issuer URL and secret.
We already have stored the secret so, we only need the URL.
For that, go to Configure>Realm settings:
Then, select Endpoints>OpenID Endpoint Configuration:
Copy the issuer URL:
In data/greenlight/.env uncomment all OpenID connect variables (those prefixed with OPENID_CONNECT).
And fill in the credentials as follow:
:** is a placeholder for your OpenID client secret.
:** is a placeholder for your Keycloak issuer (realm) URL.
:** is a placeholder for your Greenlight FQDN. It should match what you have as “**$DOMAIN_NAME.$GL_HOSTNAME**”.
OPENID_CONNECT_CLIENT_ID=greenlight OPENID_CONNECT_CLIENT_SECRET=**<YOUR_SECRET>** OPENID_CONNECT_ISSUER=**<ISSUER_URL>** OPENID_CONNECT_REDIRECT=https://**<YOUR_GREENLIGHT_DOMAIN>**/
Now, restart Greenlight:
sudo docker compose down && sudo docker compose up -d
Once Greenlight restarts, you should be able to use the Keycloak realm client that you have created instead of the local authentication:
Open Greenlight in your browser and click on Sign In. You should be redirected to Google authentication consent screen:
After Authenticating on Google, you should be redirected back to Greenlight and have your account created and be logged in.
You can now further configure Keycloak realm to use other social networks (identity providers) or other authentication systems such as SAML, LDAP and many more.
Connecting to Another OpenID Provider
If you have an OpenID connect provider that you want to use, it’s only a matter of filling these environmental variables to match your configuration:
|OPENID_CONNECT_CLIENT_ID||The client ID of the OpenID issuer.|
|OPENID_CONNECT_CLIENT_SECRET||The secret to use to authenticate to the OpenID issuer.|
|OPENID_CONNECT_ISSUER||The URL for the OpenID issuer. It’s required to be HTTPS URL using the default HTTPS port (TCP 443).|
|OPENID_CONNECT_REDIRECT||The Redirect URI after successful authentication. It will be the URL to Greenlight.|
The Redirect URI pattern should be: https://<YOUR_GREENLIGHT_FQDN>/* where <YOUR_GREENLIGHT_FQDN> is a placeholder for your Greenlight FQDN matching “$GL_HOSTNAME.$DOMAIN_NAME”
The only constraint, however, is to have the OpenID provider accessible through your network via HTTPS on the default port (TCP 443).
Once you make your changes, you can jump to Starting Greenlight.
Some deployments may not require having Keycloak installed.
These steps will document what to change in order to set and run Greenlight v3 without Keycloak.
Please note that your users will have to authenticate only through Greenlight v3 local accounts.
You can still connect Greenlight v3 to any OpenID connect provider by updating the OpenID connect environmental variables, as documented in Greenlight with Keycloak.
Greenlight v3 is a distributed application that has more then a single service running.
One of which is Keycloak, so let’s start by removing the Keycloak service.
Stop Greenlight if it’s running:
cd ~/greenlight-run sudo docker compose down
Then, remove the Keycloak service from the docker-compose.yaml file as follow by removing all of the highlighted lines:
Also, all of the other services dependencies need to be updated.
On the nginx service object, remove the highlighted line:
Save the changes.
And update the nginx templates as follow:
Remove the lines starting from “#### For <$KC_HOSTNAME.$NGINX_DOMAIN>” on data/nginx/sites.template-docker and data/nginx/sites.template-local
Kindly save the changes.
Remove the KC_HOSTNAME value:
sed -i "s/KC_HOSTNAME=.*/KC_HOSTNAME=/" .env
If you have followed the guide Greenlight with Keycloak and already set Keycloak and integrated it with Greenlight, you have to comment out the OpenID client configuration for Keycloak:
For that, please run:
sed -i "/^OPENID_CONNECT.*/s/OPENID/#OPENID/g" data/greenlight/.env
Then, restart Greenlight:
sudo docker compose up -d sudo docker compose restart nginx
You can remove any data related to the Keycloak containers such as the docker image, certificates, etc.
At this point, you should have Greenlight services up and running without Keycloak.
You can verify that by running:
sudo docker container ls
You should not have a Keycloak container.
All other services should be up and running with no issues.