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