pyrox.dev
1# Keycloak {#module-services-keycloak}
2
3[Keycloak](https://www.keycloak.org/) is an
4open 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
11An administrative user with the username
12`admin` is automatically created in the
13`master` realm. Its initial password can be
14configured by setting [](#opt-services.keycloak.initialAdminPassword)
15and defaults to `changeme`. The password is
16not stored safely and should be changed immediately in the
17admin panel.
18
19Refer to the [Keycloak Server Administration Guide](
20 https://www.keycloak.org/docs/latest/server_admin/index.html
21) for information on
22how to administer your Keycloak
23instance.
24
25## Database access {#module-services-keycloak-database}
26
27Keycloak can be used with either PostgreSQL, MariaDB or
28MySQL. Which one is used can be
29configured in [](#opt-services.keycloak.database.type). The selected
30database will automatically be enabled and a database and role
31created unless [](#opt-services.keycloak.database.host) is changed
32from its default of `localhost` or
33[](#opt-services.keycloak.database.createLocally) is set to `false`.
34
35External 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
41appropriate. Note that you need to manually create the database
42and allow the configured database user full access to it.
43
44[](#opt-services.keycloak.database.passwordFile)
45must be set to the path to a file containing the password used
46to log in to the database. If [](#opt-services.keycloak.database.host)
47and [](#opt-services.keycloak.database.createLocally)
48are kept at their defaults, the database role
49`keycloak` with that password is provisioned
50on the local database instance.
51
52::: {.warning}
53The path should be provided as a string, not a Nix path, since Nix
54paths are copied into the world readable Nix store.
55:::
56
57## Hostname {#module-services-keycloak-hostname}
58
59The hostname is used to build the public URL used as base for
60all frontend requests and must be configured through
61[](#opt-services.keycloak.settings.hostname).
62
63::: {.note}
64If you're migrating an old Wildfly based Keycloak instance
65and want to keep compatibility with your current clients,
66you'll likely want to set [](#opt-services.keycloak.settings.http-relative-path)
67to `/auth`. See the option description
68for more details.
69:::
70
71[](#opt-services.keycloak.settings.hostname-backchannel-dynamic)
72Keycloak has the capability to offer a separate URL for backchannel requests,
73enabling internal communication while maintaining the use of a public URL
74for frontchannel requests. Moreover, the backchannel is dynamically
75resolved based on incoming headers endpoint.
76
77For more information on hostname configuration, see the [Hostname
78section of the Keycloak Server Installation and Configuration
79Guide](https://www.keycloak.org/server/hostname).
80
81## Setting up TLS/SSL {#module-services-keycloak-tls}
82
83By default, Keycloak won't accept
84unsecured HTTP connections originating from outside its local
85network.
86
87HTTPS support requires a TLS/SSL certificate and a private key,
88both [PEM formatted](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
89Their 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,
95since Nix paths are copied into the world readable Nix store.
96:::
97
98## Themes {#module-services-keycloak-themes}
99
100You can package custom themes and make them visible to
101Keycloak 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
105more information.
106
107## Configuration file settings {#module-services-keycloak-settings}
108
109Keycloak server configuration parameters can be set in
110[](#opt-services.keycloak.settings). These correspond
111directly to options in
112{file}`conf/keycloak.conf`. Some of the most
113important parameters are documented as suboptions, the rest can
114be found in the [All
115configuration section of the Keycloak Server Installation and
116Configuration Guide](https://www.keycloak.org/server/all-config).
117
118Options containing secret data should be set to an attribute
119set containing the attribute `_secret` - a
120string pointing to a file containing the value the option
121should 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
126A 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```