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:


    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:


    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:

    Add Realm

    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.

    Realm Settings

    You can further configure your realm according to your preferences.

    Create a new client by clicking 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:

    Change <YOUR_GREENLIGHT_FQDN> to whatever you have as “$GL_HOSTNAME.$DOMAIN_NAME”.

    For, and GL_HOSTNAME=gl, type in*.

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

    Save Client

    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:

    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:


    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:

    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:

    Google Auth

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

    Google Creds

    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:

    Auth Actions

    Fill the form as follow:


    You should have something similar to this:

    Default Save


    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:

    Realm Creds

    Then, select Endpoints>OpenID Endpoint Configuration:

    OpenID Config

    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”.

    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:


    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:

    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 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.

    Removing Keycloak

    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:

    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

    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.