Authentication and user management
SmartFace Station allows you to use the Keycloak user management and authentication server.
Keycloak
Keycloak is providing self-hosted user management and authentication. Keycloak-Gatekeeper is used as a reverse proxy to forward requests to Keycloak and renew tokens. Keycloak can be also set up for social media logins, but this topic out of the scope of this manual.
Set up Keycloak Server
Requirement
Windows operating system
Download the Windows x64 package of Java JDK 8u241 from oracle.com/…downloads.
Run
jdk-8u241-windows-x64.exe
with the default options.Open System Properties. Either:
a. Click the Start button and type
SystemPropertiesAdvanced
, orb. Open Control Panel > System > Advanced system settings on the left.
Click Environment Variables…
Choose if you want to configure both User variables and System variables:
Click New….
Enter the Variable name:
JAVA_HOME
Enter the Variable value:
C:\Program Files\Java\jdk1.8.0_241
Click OK.
Double-click the Path variable.
Click New.
Enter the value:
%JAVA_HOME%\bin
Download the ZIP package of the latest 9 version of the standalone server distribution from https://www.keycloak.org/downloads
Unzip
keycloak-9-0-3.zip
.Open the PowerShell console and navigate to
\keycloak-9.0.3\bin
of the unzipped archive.Run
standalone.ps1
. If you encounter problems, try one of these options:- (Optional) You may need to run
Set-ExecutionPolicy Bypass
as administrator first.
⚠️ This step isn't secure, so we recommend consulting it with your system administrator, who can find a different approach.- (Optional) You may need to run
dir C:\path\to\keycloak\bin | Unblock-File
- (Optional) You may need to run
(Optional) To allow external requests, run the PowerShell script with the argument
-b 0.0.0.0
( such asstandalone.ps1 -b 0.0.0.0
). In production, you should have HTTPS. When running only for development purposes, you may turn off Secure-cookies on Keycloak-Gatekeeper and it works without HTTPS perfectly.Open
localhost:8080
in a browser. The homepage of the local Keycloak instance should show up.Create the administrator user by clicking on the button on the left.
Follow the first tutorial described at Create New Client in Keycloak until Conclusion Keycloak Client Configuration to set up a client.
Save the
realm name
,client-id
andclient-secret
Make sure the valid
Redirect URI
is set, for example *. Replacettyd
with a name of your choice.Use http://localhost:8080/ instead of https://ttyd.idocker.hacking-lab.com.
Set up Keycloak Gatekeeper proxy server
Once your Keycloak Server setup and running, you can set up Keycloak Gatekeeper proxy server.
Requirement
Windows operating system
Download the Gatekeeper-Windows from https://www.keycloak.org/downloads and unpack the
keycloak-gatekeeper-windows-amd64.tar.gz
file.Navigate into the directory and create a config file next to the executable
keycloak-gatekeeper.conf
and open it with a text editor.- (Optional) You may use as an example this config sample.
The config file should include at least:
discovery-url
: URL on which to access Keycloak Server and which Keycloak realm to use. For example,http://localhost:8080/auth/realms/master
. You should have defined it in the previous section Set up Keycloak Server.client-id
andclient-secret
of the target Keycloak realm. You should have set it up in the previous section Set up Keycloak Server.listen
: where the reverse-proxy listens for incoming requests. For example,3000
.upstream-url
: on which SmartFace Station server is hosted. For example, http://localhost:8080/.(Optional)
enable-refresh-tokens
: to enable refresh tokens, set to true.(Optional)
encryption-key
: If enable-refresh-tokens is set to true, then this value also has to be set. It must be a validAES-128
/AES-256
key of either 16 or 32 characters.
Run it from the command line as follows:
keycloak-gatekeeper.exe --config keycloak-gatekeeper.conf
Turn on authentication in SmartFace Station by setting
ENABLE_AUTHENTICATION=true
andKEYCLOAK_ADMIN_URL
in the.env
file. See the chapter SmartFace Station server configurationSmartFace Station should now be accessible from your web browser.
8000
and Keycloak Gatekeeper is listening on port 3000
, you should not allow users to directly connect to port 8000
(For example by setting the proper firewall rule).Set up SmartFace Keycloak theme
We’ve prepared a Keycloak login theme with SmartFace graphic design.
To install it, unzip the content of sf-theme-keykloak.zip
to the themes directory inside Keycloak Server. Then, restart Keycloak Server and apply the theme in the Keycloak’s admin console.