Keycloak: Difference between revisions

From NixOS Wiki
imported>Nix
cleanup
Onny (talk | contribs)
 
(14 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''[https://keycloak.org/ Keycloak]''' ([[wikipedia:en: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.)
'''[https://keycloak.org/ Keycloak]''' ([[wikipedia:en: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...
For official documentation on Keycloak please consult the [https://nixos.org/manual/nixos/stable/index.html#module-services-keycloak NixOS manual].


* covered in the [https://nixos.org/manual/nixos/stable/index.html#module-services-keycloak NixOS manual]
== Setup ==
* packaged [https://search.nixos.org/packages?type=packages&query=keycloak for Nix]
Following configuration will enable a minimal and insecure Keycloak instance for '''testing purpose'''.<syntaxhighlight lang="nix">
* available as a [https://search.nixos.org/options?query=keycloak Nix service]
environment.etc."keycloak-database-pass".text = "PWD";
* written in [[Java]]
services.keycloak = {
* maintained by Red Hat
  enable = true;
  settings = {
    hostname = "localhost";
    http-enabled = true;
    hostname-strict-https = false;
  };
  database.passwordFile = "/etc/keycloak-database-pass";
};
</syntaxhighlight>After applying the configuration the Keycloak management interface will be available at http://localhost. Login with username <code>admin</code> and password <code>changeme</code>.


== Troubleshooting ==
== Configuration ==


=== Installing on system without X11 ===
=== Importing realms ===
{{Note|The module is not yet part of the latest NixOS stable release and will be available with version 24.11.}}Using the realmFiles option, it is possible provision a realm from a JSON file or previous JSON export.<syntaxhighlight lang="nix">
{ ... }: let


If, when you perform:
  realm = {
    realm = "OIDCDemo";
    enabled = true;
    clients = [{
      clientId = "mydemo";
      rootUrl = "http://localhost:8080";
    }];
    users = [{
      enabled = true;
      firstName = "Christian";
      lastName = "Bauer";
      username = "cbauer";
      email = "cbauer@localhost";
      credentials = [{
        type = "password";
        temporary = false;
        value = "changeme";
      }];
    }];
  };


<syntaxhighlight lang="bash">
in {
nixos-rebuild switch
 
  services.keycloak = {
    realmFiles = [
      (pkgs.writeText "OIDCDemo.json" (builtins.toJSON realm))
    ];
  };
 
}
</syntaxhighlight>
</syntaxhighlight>
== Tips and tricks ==


... you encounter errors like:
=== 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 <code>domain.tld</code>, reflecting your used domain.


<syntaxhighlight lang="bash">
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
building Nix...
{


...
  services.nginx = {
    enable = true;


checking for CAIRO_BACKEND... no
    # enable recommended settings
configure: error: Package requirements (cairo-xlib >= 1.6) were not met:
    recommendedGzipSettings = true;
    recommendedOptimisation = true;
    recommendedTlsSettings = true;
    recommendedProxySettings = true;


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


...
  services.postgresql.enable = true;


error: build of '/nix/store/vfz...2a0-nixos-system-nixos-21.11pre322478.e4ef597edfd.drv' failed
  services.keycloak = {
</syntaxhighlight>
    enable = true;
 
    database = {
      type = "postgresql";
      createLocally = true;


... it would be because the package expects X11 to be installed. The [https://nixos.org/manual/nixos/unstable/options.html#opt-environment.noXlibs environment.noXlibs] NixOS option will specify to not require the X11 libraries:
      username = "keycloak";
      passwordFile = "/etc/nixos/secrets/keycloak_psql_pass";
    };


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
    settings = {
{ config, pkgs, ... }:
      hostname = "domain.tld";
      http-relative-path = "/cloak";
      http-port = 38080;
      proxy = "passthrough";
      http-enabled = true;
    };
  };


{
  environment.noXlibs = false;
}
}
</nowiki>}}
</nowiki>}}
=== 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 ====
{{file|custom.css|css|<nowiki>
    body {
    background: red;
        color: blue;
    }
</nowiki>}}
{{file|theme.properties|bash|<nowiki>
    parent=base
    import=common/keycloak
    styles=css/custom.css
</nowiki>}}
==== Create a package ====
{{file|keycloak_custom_theme.nix|nix|<nowiki>
    { 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
      '';
    }
</nowiki>}}
==== Create a packages set ====
{{file|default.nix|nix|<nowiki>
    {pkgs, ...}: let
      callPackage = pkgs.callPackage;
    in {
      nixpkgs.overlays = [(final: prev: {
        custom_keycloak_themes = {
          custom = callPackage ./keycloak_custom_theme.nix {};
        };
      })];
    }
</nowiki>}}
==== Configure your keycloak service ====
{{file|configuration.nix|nix|<nowiki>
    { 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;
    };
    ...
    }
</nowiki>}}
[[Category:Server]]
[[Category:Security]]
[[Category:NixOS Manual]]

Latest revision as of 13:24, 22 July 2024

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

For official documentation on Keycloak please consult the NixOS manual.

Setup

Following configuration will enable a minimal and insecure Keycloak instance for testing purpose.

environment.etc."keycloak-database-pass".text = "PWD";
services.keycloak = {
  enable = true;
  settings = {
    hostname = "localhost";
    http-enabled = true;
    hostname-strict-https = false;
  };
  database.passwordFile = "/etc/keycloak-database-pass";
};

After applying the configuration the Keycloak management interface will be available at http://localhost. Login with username admin and password changeme.

Configuration

Importing realms

Note: The module is not yet part of the latest NixOS stable release and will be available with version 24.11.

Using the realmFiles option, it is possible provision a realm from a JSON file or previous JSON export.

{ ... }: let

  realm = {
    realm = "OIDCDemo";
    enabled = true;
    clients = [{
      clientId = "mydemo";
      rootUrl = "http://localhost:8080";
    }];
    users = [{
      enabled = true;
      firstName = "Christian";
      lastName = "Bauer";
      username = "cbauer";
      email = "cbauer@localhost";
      credentials = [{
        type = "password";
        temporary = false;
        value = "changeme";
      }];
    }];
  };

in {

  services.keycloak = {
    realmFiles = [
      (pkgs.writeText "OIDCDemo.json" (builtins.toJSON realm))
    ];
  };

}

Tips and tricks

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