Keycloak: Difference between revisions

← Older edit
VisualWikitext
Klinger (talk | contribs)
trusted
707 edits
m added category nixos manual
Onny (talk | contribs)
144 edits
 
(7 intermediate revisions by the same user 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, ... }:
Retrieved from "https://wiki.nixos.org/wiki/Keycloak"