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

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

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

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

  4. 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
  1. (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.

  2. Open localhost:8080 in a browser. The homepage of the local Keycloak instance should show up.

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.

  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.

⚠️ After installing Keycloak Gatekeeper, you should access SmartFace Station only through the reverse proxy and not directly. So if, for example, SmartFace Station is running on port 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.