Keycloak: Difference between revisions

From NixOS Wiki
imported>Edelagnier
add guide to create a theme
Onny (talk | contribs)
 
(9 intermediate revisions by 2 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 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 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
</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>
</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.
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 101: Line 109:
</nowiki>}}
</nowiki>}}


== Keycloak themes on NixOS ==
=== Keycloak themes on NixOS ===
 
You need to create a package for your custom theme and configure the keycloak service to use it
You need to create a package for your custom theme and configure the keycloak service to use it


Line 118: Line 125:
         - keycloak_custom_theme.nix <- package for your theme
         - keycloak_custom_theme.nix <- package for your theme


=== Create a theme ===
==== Create a theme ====
 


{{file|custom.css|css|<nowiki>
{{file|custom.css|css|<nowiki>
Line 134: Line 140:
</nowiki>}}
</nowiki>}}


=== Create a package ===
==== Create a package ====
 
{{file|keycloak_custom_theme.nix|nix|<nowiki>
{{file|keycloak_custom_theme.nix|nix|<nowiki>
     { stdenv }:
     { stdenv }:
Line 154: Line 159:
</nowiki>}}
</nowiki>}}


=== Create a packages set ===
==== Create a packages set ====
 


{{file|default.nix|nix|<nowiki>
{{file|default.nix|nix|<nowiki>
Line 169: Line 173:
</nowiki>}}
</nowiki>}}


 
==== Configure your keycloak service ====
=== Configure your keycloak service ===
 
{{file|configuration.nix|nix|<nowiki>
{{file|configuration.nix|nix|<nowiki>
     { config, pkgs, lib, ... }:
     { config, pkgs, lib, ... }:
Line 197: Line 199:
</nowiki>}}
</nowiki>}}


[[Category: Applications]]
[[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;
    		};
    ...
    }