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#

1. Download the Windows x64 package of Java JDK 8u241 from oracle.com/…downloads.

2. Run jdk-8u241-windows-x64.exe with the default options.

3. Open System Properties. Either:

   a. Click the Start button and type SystemPropertiesAdvanced, or

   b. Open Control Panel > System > Advanced system settings on the left.

4. Click Environment Variables…

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

6. Download the ZIP package of the latest 9 version of the standalone server distribution from https://www.keycloak.org/downloads

7. Unzip keycloak-9-0-3.zip.

8. Open the PowerShell console and navigate to \keycloak-9.0.3\bin of the unzipped archive.

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

10. (Optional) To allow external requests, run the PowerShell script with the argument -b 0.0.0.0( such as standalone.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.

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

      1. Save the realm name, client-id and client-secret

      2. Make sure the valid Redirect URI is set, for example *. Replace ttyd with a name of your choice.

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

1. Download the Gatekeeper-Windows from https://www.keycloak.org/downloads and unpack the keycloak-gatekeeper-windows-amd64.tar.gz file.

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

3. 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 and client-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 valid AES-128/AES-256 key of either 16 or 32 characters.

4. Run it from the command line as follows: keycloak-gatekeeper.exe --config keycloak-gatekeeper.conf

5. Turn on authentication in SmartFace Station by setting ENABLE_AUTHENTICATION=true and KEYCLOAK_ADMIN_URL in the .env file. See the chapter SmartFace Station server configuration

6. SmartFace Station should now be accessible from your web browser.

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.