using-keycloak.md

Authenticate using Keycloak

This guide describes a way to Dockerise Keycloak along with cBioPortal, for authentication as described in the cBioPortal documentation.

First, create an isolated network in which the Keycloak and MySQL servers can talk to one another.

docker network create kcnet

Run a MySQL database in which Keycloak can store its data. This database server will not be addressable from outside the Docker network. The database will store its files in a folder named kcdb-files in the present working directory, unless you specify some other (absolute) path before the colon in the -v argument.

docker run -d --restart=always \
    --name=kcdb \
    --net=kcnet \
    -v "$PWD/kcdb-files:/var/lib/mysql" \
    -e MYSQL_DATABASE=keycloak \
    -e MYSQL_USER=keycloak \
    -e MYSQL_PASSWORD=password \
    -e MYSQL_ROOT_PASSWORD=root_password \
    mysql:5.7

Then run the actual Keycloak server, using this image available from Docker Hub. This will by default connect to the database using the (non-root) credentials in the example above. The server will be accessible to the outside world on port 8180, so make sure to choose a strong administrator password.

The command below uses the default values for MYSQL_DATABASE, MYSQL_USER and MYSQL_PASSWORD (listed in the command above). If you wish to change these credentials, specify them in the command below. For instance, if MYSQL_USER in the database container is user, you need to add -e MYSQL_USER=user.

docker run -d --restart=always \
    --name=cbiokc \
    --net=kcnet \
    -p 8180:8080 \
    -e DB_VENDOR=mysql \
    -e DB_ADDR=kcdb \
    -e KEYCLOAK_USER=admin \
    -e "KEYCLOAK_PASSWORD=<admin_password_here>" \
    jboss/keycloak:4.8.3.Final

Finally, configure Keycloak and cBioPortal as explained in the cBioPortal documentation. Click here for a general explanation on how to adjust portal properties used when building a Docker image for cBioPortal, and remember to specify port 8180 for the Keycloak server, wherever the guide says 8080.

When starting the cBioPortal web server with the new configuration, instead of modifying Tomcat config files, include the -Dauthenticate=saml flag in the CATALINA_OPTS argument on the command line:

    -e CATALINA_OPTS='-Xms2g -Xmx4g -Dauthenticate=saml' \