Keycloak

Keycloak (Wikipedia) is identity and access management software, and can serve as an authentication server for applications (providing support for OpenID Connect, OAuth 2.0, and SAML.)

Keycloak is...

• covered in the NixOS manual
• packaged for Nix
• available as a NixOS service
• written in Java
• maintained by Red Hat

Troubleshooting

Installing on system without X11

If, when you perform:

nixos-rebuild switch

... you encounter errors like:

building Nix...

...

checking for CAIRO_BACKEND... no
configure: error: Package requirements (cairo-xlib >= 1.6) were not met:

No package 'cairo-xlib' found

...

error: build of '/nix/store/vfz...2a0-nixos-system-nixos-21.11pre322478.e4ef597edfd.drv' failed

... it would be because the package expects X11 to be installed. The environment.noXlibs NixOS option will specify to not require the X11 libraries:

/etc/nixos/configuration.nix

{ config, pkgs, ... }:

{
  environment.noXlibs = false;
}

Installation in subdirectory

Keycloak may be installed in a subdirectory of a domain. Thus you don't need to configure and expose a subdomain. For example with the following configuration, remember to edit domain.tld, reflecting your used domain.

/etc/nixos/configuration.nix

{

  services.nginx = {
    enable = true;

    # enable recommended settings
    recommendedGzipSettings = true;
    recommendedOptimisation = true;
    recommendedTlsSettings = true;
    recommendedProxySettings = true;

    virtualHosts = {
      "domain.tld" = {
        forceSSL = true;
        enableACME = true;
        locations = {
          "/cloak/" = {
            proxyPass = "http://localhost:${toString config.services.keycloak.settings.http-port}/cloak/";
          };
        };
      };
    };
  };

  services.postgresql.enable = true;

  services.keycloak = {
    enable = true;

    database = {
      type = "postgresql";
      createLocally = true;

      username = "keycloak";
      passwordFile = "/etc/nixos/secrets/keycloak_psql_pass";
    };

    settings = {
      hostname = "domain.tld";
      http-relative-path = "/cloak";
      http-port = 38080;
      proxy = "passthrough";
      http-enabled = true;
    };
  };

}

Keycloak themes on NixOS

You need to create a package for your custom theme and configure the keycloak service to use it

Here is a what a basic theme will look like :

   - configuration.nix
   - keycloak
       - custom_theme
           - login
               - resources
                   - css
                       - custom.css 
                  - theme.properties
       - default.nix <- set of packages to be imported in your configuration.nix
       - keycloak_custom_theme.nix <- package for your theme

Create a theme

custom.css

    body {
    	background: red;
         color: blue;
    }

theme.properties

    parent=base
    import=common/keycloak
    styles=css/custom.css

Create a package

keycloak_custom_theme.nix

    { stdenv }:
    stdenv.mkDerivation rec {
      name = "keycloak_custom_theme";
      version = "1.0";

      src = ./keycloak_custom_theme;

      nativeBuildInputs = [ ];
      buildInputs = [ ];

      installPhase = ''
        mkdir -p $out
        cp -a login $out
      '';
    }

Create a packages set

default.nix

     {pkgs, ...}: let
      callPackage = pkgs.callPackage;
    in {
      nixpkgs.overlays = [(final: prev: {
        custom_keycloak_themes = {
          custom = callPackage ./keycloak_custom_theme.nix {};
        };
      })];
    }

Configure your keycloak service

configuration.nix

    { config, pkgs, lib, ... }:
    {
    	imports =
    		[ # Include the results of the hardware scan.
    		./hardware-configuration.nix
    		./keycloak
    		];
    ...
    	environment.systemPackages = with pkgs; [
    		...
            # authentication requires
    		keycloak
    		custom_keycloak_themes.agatha
    	];
    ...
    services.keycloak = {
    		enable = true;
    		themes = with pkgs ; {
    			custom = custom_keycloak_themes.custom;
    		};
    ...
    }