Keycloak: Difference between revisions

← Older edit Newer edit →

VisualWikitext

@@ 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 ==
+== Tips and tricks ==
-=== Installing on system without X11 ===
+=== 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.
-If, when you perform:
+{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+{
+  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;
-<syntaxhighlight lang="bash">
+    database = {
-nixos-rebuild switch
+      type = "postgresql";
-</syntaxhighlight>
+      createLocally = true;
-... you encounter errors like:
+      username = "keycloak";
+      passwordFile = "/etc/nixos/secrets/keycloak_psql_pass";
+    };
-<syntaxhighlight lang="bash">
+    settings = {
-building Nix...
+      hostname = "domain.tld";
+      http-relative-path = "/cloak";
+      http-port = 38080;
+      proxy = "passthrough";
+      http-enabled = true;
+    };
+  };
+}
+</nowiki>}}
-...
+=== Keycloak themes on NixOS ===
+You need to create a package for your custom theme and configure the keycloak service to use it
-checking for CAIRO_BACKEND... no
+Here is a what a basic theme will look like :
-configure: error: Package requirements (cairo-xlib >= 1.6) were not met:
-No package 'cairo-xlib' found
+    - 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 ====
-error: build of '/nix/store/vfz...2a0-nixos-system-nixos-21.11pre322478.e4ef597edfd.drv' failed
+{{file|custom.css|css|<nowiki>
-</syntaxhighlight>
+    body {
+    	background: red;
+         color: blue;
+    }
+</nowiki>}}
-... 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:
+{{file|theme.properties|bash|<nowiki>
+    parent=base
+    import=common/keycloak
+    styles=css/custom.css
+</nowiki>}}
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+==== Create a package ====
-{ config, pkgs, ... }:
+{{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 ====
-  environment.noXlibs = false;
+{{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]]