Keycloak: Difference between revisions

← Older edit

@@ 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 NixOS 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 25.05. Tracking issue: https://github.com/NixOS/nixpkgs/pull/273833}}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
-</syntaxhighlight>
-... you encounter errors like:
+  services.keycloak = {
+    realmFiles = [
+      (pkgs.writeText "OIDCDemo.json" (builtins.toJSON realm))
+    ];
+  };
-<syntaxhighlight lang="bash">
+}
-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
 </syntaxhighlight>
+== Tips and tricks ==
-... 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:
+=== Installation in subdirectory ===
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
-{ config, pkgs, ... }:
-{
-  environment.noXlibs = false;
-}
-</nowiki>}}
-== 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.
@@ Line 100: / Line 108: @@
 }
 </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]]