Connecting to Keycloak

    Configuring 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:

    Landing

    Select the administration console:

    Admin Console

    The default Username is admin and password is whatever you have on KEYCLOAK_PASSWORD in the ~/greenlight-run/.env file:

    Credentials

    Start by creating a new realm for Greenlight by hovering over the Master realm on the top left corner and clicking on Add realm:

    Realm

    Call the realm greenlight and click on create:

    Add Realm

    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.

    Realm Settings

    You can further configure your realm according to your preferences.

    Create a new client by clicking Clients:

    Clients

    Click on Create:

    Create Clients

    Fill in the form as follow and click Save:

    Create Clients

    Make sure to set Access Type to Confidential:

    Access Type

    And the redirect URI pattern:

    Kindly change **** to whatever you have as “**$GL_HOSTNAME.$DOMAIN_NAME**”.

    For a DOMAIN_NAME=xlab.bigbluebutton.org, and GL_HOSTNAME=gl.

    Type in https://gl.xlab.bigbluebutton.org/*.

    Valid Redirect

    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:

    Save Client

    Kindly go to Credentials and store the Secret key, as we will need to use it later:

    Client Creds

    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:

    Idp

    Click on Add provider… on the select menu and choose the provider you like, for example, with Google:

    Google Idp

    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:

    Google Auth

    After obtaining the credentials, put them in the form as follow:

    Google Creds

    After filling in the credentials, please save changes.

    Save

    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:

    Authentication

    Click on Actions>Config on the “Identity Provider Redirector” row:

    Auth Actions

    Fill the form as follow:

    Default

    You should have something similar to this:

    Default Save

    Auth-2

    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:

    Realm Creds

    Then, select Endpoints>OpenID Endpoint Configuration:

    OpenID Config

    Copy the issuer URL:

    Issuer

    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>**/
    

    Starting Greenlight

    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:

    Signin

    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:

    Variable Name Description
    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.


    Removing Keycloak

    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:

    Remove Compose

    Also, all of the other services dependencies need to be updated.

    On the nginx service object, remove the highlighted line:

    Remove Compose 2

    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

    Remove Nginx

    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
    

    Remove Containers

    You should not have a Keycloak container.

    All other services should be up and running with no issues.