nixos/modules/services/web-apps/keycloak.md

   1 # Keycloak {#module-services-keycloak}
   2
   3 [Keycloak](https://www.keycloak.org/) is an
   4 open source identity and access management server with support for
   5 [OpenID Connect](https://openid.net/connect/),
   6 [OAUTH 2.0](https://oauth.net/2/) and
   7 [SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0).
   8
   9 ## Administration {#module-services-keycloak-admin}
  10
  11 An administrative user with the username
  12 `admin` is automatically created in the
  13 `master` realm. Its initial password can be
  14 configured by setting [](#opt-services.keycloak.initialAdminPassword)
  15 and defaults to `changeme`. The password is
  16 not stored safely and should be changed immediately in the
  17 admin panel.
  18
  19 Refer to the [Keycloak Server Administration Guide](
  20   https://www.keycloak.org/docs/latest/server_admin/index.html
  21 ) for information on
  22 how to administer your Keycloak
  23 instance.
  24
  25 ## Database access {#module-services-keycloak-database}
  26
  27 Keycloak can be used with either PostgreSQL, MariaDB or
  28 MySQL. Which one is used can be
  29 configured in [](#opt-services.keycloak.database.type). The selected
  30 database will automatically be enabled and a database and role
  31 created unless [](#opt-services.keycloak.database.host) is changed
  32 from its default of `localhost` or
  33 [](#opt-services.keycloak.database.createLocally) is set to `false`.
  34
  35 External database access can also be configured by setting
  36 [](#opt-services.keycloak.database.host),
  37 [](#opt-services.keycloak.database.name),
  38 [](#opt-services.keycloak.database.username),
  39 [](#opt-services.keycloak.database.useSSL) and
  40 [](#opt-services.keycloak.database.caCert) as
  41 appropriate. Note that you need to manually create the database
  42 and allow the configured database user full access to it.
  43
  44 [](#opt-services.keycloak.database.passwordFile)
  45 must be set to the path to a file containing the password used
  46 to log in to the database. If [](#opt-services.keycloak.database.host)
  47 and [](#opt-services.keycloak.database.createLocally)
  48 are kept at their defaults, the database role
  49 `keycloak` with that password is provisioned
  50 on the local database instance.
  51
  52 ::: {.warning}
  53 The path should be provided as a string, not a Nix path, since Nix
  54 paths are copied into the world readable Nix store.
  55 :::
  56
  57 ## Hostname {#module-services-keycloak-hostname}
  58
  59 The hostname is used to build the public URL used as base for
  60 all frontend requests and must be configured through
  61 [](#opt-services.keycloak.settings.hostname).
  62
  63 ::: {.note}
  64 If you're migrating an old Wildfly based Keycloak instance
  65 and want to keep compatibility with your current clients,
  66 you'll likely want to set [](#opt-services.keycloak.settings.http-relative-path)
  67 to `/auth`. See the option description
  68 for more details.
  69 :::
  70
  71 [](#opt-services.keycloak.settings.hostname-backchannel-dynamic)
  72 Keycloak has the capability to offer a separate URL for backchannel requests,
  73 enabling internal communication while maintaining the use of a public URL
  74 for frontchannel requests. Moreover, the backchannel is dynamically
  75 resolved based on incoming headers endpoint.
  76
  77 For more information on hostname configuration, see the [Hostname
  78 section of the Keycloak Server Installation and Configuration
  79 Guide](https://www.keycloak.org/server/hostname).
  80
  81 ## Setting up TLS/SSL {#module-services-keycloak-tls}
  82
  83 By default, Keycloak won't accept
  84 unsecured HTTP connections originating from outside its local
  85 network.
  86
  87 HTTPS support requires a TLS/SSL certificate and a private key,
  88 both [PEM formatted](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
  89 Their paths should be set through
  90 [](#opt-services.keycloak.sslCertificate) and
  91 [](#opt-services.keycloak.sslCertificateKey).
  92
  93 ::: {.warning}
  94  The paths should be provided as a strings, not a Nix paths,
  95 since Nix paths are copied into the world readable Nix store.
  96 :::
  97
  98 ## Themes {#module-services-keycloak-themes}
  99
 100 You can package custom themes and make them visible to
 101 Keycloak through [](#opt-services.keycloak.themes). See the
 102 [Themes section of the Keycloak Server Development Guide](
 103   https://www.keycloak.org/docs/latest/server_development/#_themes
 104 ) and the description of the aforementioned NixOS option for
 105 more information.
 106
 107 ## Configuration file settings {#module-services-keycloak-settings}
 108
 109 Keycloak server configuration parameters can be set in
 110 [](#opt-services.keycloak.settings). These correspond
 111 directly to options in
 112 {file}`conf/keycloak.conf`. Some of the most
 113 important parameters are documented as suboptions, the rest can
 114 be found in the [All
 115 configuration section of the Keycloak Server Installation and
 116 Configuration Guide](https://www.keycloak.org/server/all-config).
 117
 118 Options containing secret data should be set to an attribute
 119 set containing the attribute `_secret` - a
 120 string pointing to a file containing the value the option
 121 should be set to. See the description of
 122 [](#opt-services.keycloak.settings) for an example.
 123
 124 ## Example configuration {#module-services-keycloak-example-config}
 125
 126 A basic configuration with some custom settings could look like this:
 127 ```nix
 128 {
 129   services.keycloak = {
 130     enable = true;
 131     settings = {
 132       hostname = "keycloak.example.com";
 133       hostname-strict-backchannel = true;
 134     };
 135     initialAdminPassword = "e6Wcm0RrtegMEHl";  # change on first login
 136     sslCertificate = "/run/keys/ssl_cert";
 137     sslCertificateKey = "/run/keys/ssl_key";
 138     database.passwordFile = "/run/keys/db_password";
 139   };
 140 }
 141 ```