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 to use.
However, this default configuration is only for testing purposes and should not be used as is for production environments.
It is recommended to follow the official documentations from Keycloak to check the available options and 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:
<YOUR_GREENLIGHT_FQDN> to whatever you have as “$GL_HOSTNAME.$DOMAIN_NAME”.
For 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, it is recommended that you check the official OpenID documentations.
After making the changes, validate the OpenID client creation by clicking Save at the end of the form:
Go to Credentials and store the Secret key, as it will be needed later for OPENID_CONNECT_CLIENT_SECRET variable in data/greenlight/.env file:
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 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 there is only one Identity provider, and local authentication is not desired, 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.
Now, connect Greenlight to Keycloak.
For that, the realm issuer URL and secret is needed.
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:
<YOUR_SECRET>is a placeholder for your OpenID client secret that you stored before.
<ISSUER_URL>is a placeholder for your Keycloak issuer (realm) URL.
<YOUR_GREENLIGHT_DOMAIN>is a placeholder for your Greenlight FQDN. It should match what you have as “$GL_HOSTNAME.$DOMAIN_NAME”.
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, fill 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 is 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 do not require having Keycloak installed.
The following steps will indicate what to change in order to set and run Greenlight v3 without Keycloak.
Please note that your users will have to authenticate 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
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.