Setup Apache & Keycloak locally

Owned by Paul Hoang (Unlicensed)
Last updated: 20 Dec 2019 by Yafang Deng
4 min read

This is a guide that takes you through setting up your machine such that all requests and flows through your system and mimics the production system. It assumes that you've been through the Development set up on Mac page and have successfully deployed the backend services, database and frontend applications.

The issue with the mentioned set up page is that it hard codes the JWT token to all inbound requests going through nginx (the proxy) this gives the benefit of not needing to run keycloak (KC) locally but also has the downsides that if we need to work with KC in any shape for form (such as updating KC to the latest version or testing authentication) then that wont be possible.

The following is a long list of steps to bring up instances of KC, apache with mod OIDC (OpenID Connect), nginx and the rest of the services so that we can effectively work on a system locally with then minimum amount of hacks

Please clone https://github.com/Health-Education-England/TIS-APACHE-SETUP to get started

Setup the host

  • Update your /etc/hosts file so that the localhost entry has an alias "local.tis.com" e.g. 127.0.0.1  localhost   local.tis.com
  • Update your shell's profile to include the following environment variables (this can be your .bashrc file or if your using bash or .zshrc if your using zsh). Dont forget to source the file if you don't want to log in and out/restart
  • Start most of the backend services
    • Profile
    • TCS
    • Reference
  • Build admins ui with npm run build
  • Start up your ES container: docker start <container id/name> (make sure your not running the old es 2.4 container)
    • if you don't have one, create one using something like: docker run --name elasticsearch-6.2.4 -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "http.host=0.0.0.0" -e "transport.host=0.0.0.0" -e "xpack.security.enabled=false" -d docker.elastic.co/elasticsearch/elasticsearch:6.2.4
  • Start up your MySql container: docker start <mysql container id/name> / start up the mysql service
  • Ensure you have the KC database and user
    • create database keycloak;
    • grant all on keycloak.* to keycloak@'%' identified by '29UTYZ735L0T8i7h6657Di71H';
    • flush privileges;


So now you have 2 options, to use docker compose or create the containers separately. I would suggest you use compose

Using docker compose

To make life easier, I've create a compose file to bring up the required services. To start them all up, do:

  • edit the compose file
    • update the nginx service to have a volume that points to your TIS-ADMIN admin subdirectory
    • update the MYSQL_PORT_3306_TCP_ADDR address to your host ip
  • follow the setup the host section
  • create a kc database, follow the steps in the setup kc section
  • docker-compose up --build
  • navigate to http://local.tis.com/auth/ login using the KC credentials in the ENV values
  • setup kc from the below section
  • copy the OIDCClientSecret from oauth2.conf under ./files/etc/apache2/conf-available/oauth2.conf
    • update the api-gateway secret in the keycloak database → client table

this would build the apache image and start up the containers.

Setup Keycloak

The KC docker image is in our local docker repository, in order to pull it, you'll need to log into that repo

Get the username and password from ops. Pull and start a new KC container

  • docker pull repository.tis.nhs.uk:5000/hee/keycloak-mysql:latest
  • docker run -d --name kc -p 8087:8080 -p 9990:9990 --env MYSQL_PORT_3306_TCP_ADDR=docker.for.mac.localhost --env MYSQL_PORT_3306_TCP_PORT=3306 --env MYSQL_DATABASE=keycloak --env MYSQL_USERNAME=keycloak --env MYSQL_PASSWORD=29UTYZ735L0T8i7h6657Di71H --env PROXY_ADDRESS_FORWARDING=true --env KEYCLOAK_USER=admin --env KEYCLOAK_PASSWORD=29UTYZ735L0T8i7h6657Di71H --env KEYCLOAK_LOGLEVEL=INFO repository.tis.nhs.uk:5000/hee/keycloak-mysql:latest
  • Browser to http://localhost:8087/auth/
  • u: admin
  • p: 29UTYZ735L0T8i7h6657Di71H

The following are steps to do within the KC web interface. If an option is not mentioned, assume that it should be left on the default setting

Setup the realm

name: lin
display name: TRAINEE INFORMATION SYSTEM
html display name: TRAINEE INFORMATION SYSTEM
endpoints: openid endpoint configuration

login tab:
forgot password: on

email:
host: smtp.sendgrid.net
port: 25
from: local-noreply@hee.nhs.uk
enable authentication: on
username: apikey
password: ??????????

theme:
login theme: lin
account theme: keycloak
email theme: lin

tokens:
SSO session idle: 10 minutes
SSO session max: 10 hours
offline session idle: 15 days
access token lifespan: 8 minutes
Access Token Lifespan For Implicit Flow: 1 minute
Client login timeout: 1 minute
Login timeout: 30 minutes
Login action timeout: 15 minutes

under clients:
create new:
client id: api-gateway . save
access type: confidential
Direct Access Grants Enabled: off

* Valid Redirect URIs :
https://local.tis.com/access/index.html
http://localhost/*
*
https://local.tis.com/logout/index.html
https://local.tis.com/admin/redirect_uri

Web Origins
https://local.tis.com


Mappers

create new:

name: Client-Host
Mapper Type: User session note
User Session Note: clientHost
Token Claim Name: clientHost
Add to ID token: on
Add to access token: on

name: Client ID
Mapper Type: User session note
User Session Note: clientId
Token Claim Name: clientId
Add to ID token: on
Add to access token: on

name: Client IP Address
Mapper Type: User session note
User Session Note: clientAddress
Token Claim Name: clientAddress
Add to ID token: on
Add to access token: on

name: groups
Mapper Type: Group membership
Token claim name: groups
Add to ID token: on
Add to access token: on
Add to userinfo: on


Under Roles add the following roles with default settings

AssessmentsAdmin
BulkUploadAdmin
ConcernsAdmin
ConnectionDiscrepanciesManager
Delta
ESR
ETL
HEE Admin
HEE Admin Revalidation
HEE Admin Sensitive
HEE TIS Admin
HEE Trust Admin
HEE Trust Observer
HEE User Admin
HEE User Observer
PCSAdmin
PersonAdmin
PPAdmin
ProfileAdmin
ProfileObserver
ReferenceAdmin
RVAdmin
RVOfficer
SuperUser
TcsAdmin
TcsObserver
TisAdmin
Trainee

Menu Identity Providers
select OpenID Connect
alias: msoidc .... skip...

Authentication:
Required Actions: uncheck update profile

Main:
groups: add the following groups
trainee
North West
North East
South West
North Central and East London
admin
LaSE
Yorkshire and The Humber
West Midlands
East Midlands
North West London
Wessex
Kent Surrrey and Sussex
South London
Thames Valley
East of England

Menu users:
add user:
username: paul.hoang@hee.nhs.uk
email: paul.hoang@hee.nhs.uk
First name: paul
surname: hoang
save

credentials
set password


Setup User in Profile

Now that you have a user in KC, you need a matching user in the Profile datanbase.

use profile;

INSERT INTO `HeeUser` (`name`, `firstName`, `lastName`, `gmcId`, `phoneNumber`, `emailAddress`, `active`) VALUES ('paul.hoang@hee.nhs.uk', 'Paul', 'Hoang', NULL, NULL, 'paul.hoang@hee.nhs.uk', 1);

INSERT INTO `UserRole` (`userName`, `roleName`) VALUES
('paul.hoang@hee.nhs.uk', 'AssessmentsAdmin'),
('paul.hoang@hee.nhs.uk', 'ConcernsObserver'),
('paul.hoang@hee.nhs.uk', 'ETL'),
('paul.hoang@hee.nhs.uk', 'HEE TIS Admin'),
('paul.hoang@hee.nhs.uk', 'PersonAdmin'),
('paul.hoang@hee.nhs.uk', 'ProfileAdmin'),
('paul.hoang@hee.nhs.uk', 'RVObserver');

Setup Apache

You'll need to make some modifications to the configuration files within the apache project before building the docker image and running it. Within the apache project directory...

  • Update the oauth2.conf file OIDCOAuthClientSecret and OIDCClientSecret with the api-gateway client secret in KC
  • Do the same in openconnet.conf OIDCClientSecret property
  • If your not using a mac, then you'll need to make changes to the configuration files in the ./apache2/conf-available/*.conf files. Replace all instances of 'docker.for.mac.localhost. with 'host.docker.internal'
  • Within the root directory where the Dockerfile exists. docker build -t apache-local .
  • docker run -d --name apache-local -p 80:80 -p 443:443 apache-local

Setup Nginx

The admins ui project is served by nginx, so we'll need another web server

  • docker run -d -p 8094:80 --name adminsui-build -v ./apache/files/etc/nginx/conf.d/:/etc/nginx/conf.d/ -v ./apache/files/logs/:/var/log/apps/ -v /Users/paul/Dev/Projects/nhs/code/TIS-ADMINS-UI/admin:/app/admin nginx:latest


In your browser, navigate to https://local.tis.com/admins/ you will probably see a warning that the site cant be trusted. This is because the apache webserver has been configured with a self signed certificate. Add the certificate if your using firefox or continue if using chrome. You should now see the TIS loging screen. Use the credentials made when setting up KC and you should now see the Peoples page.

All communication to the FE is now done via apache, mod oidc and KC



Slack: https://hee-nhs-tis.slack.com/
Jira issues: https://hee-tis.atlassian.net/issues/?filter=14213