Keycloak

From NixOS Wiki
Revision as of 18:59, 16 May 2024 by Klinger (talk | contribs) (changed categories to Category: Server Category: Security)

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

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;
    		};
    ...
    }