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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
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#admin-console">Admin
Console section of the Keycloak Server Administration Guide</link> for
information on how to administer your
<productname>Keycloak</productname> instance.
</para>
</section>
<section xml:id="module-services-keycloak-database">
<title>Database access</title>
<para>
<productname>Keycloak</productname> can be used with either
<productname>PostgreSQL</productname> or
<productname>MySQL</productname>. Which one is used can be
configured in <xref
linkend="opt-services.keycloak.databaseType" />. The selected
database will automatically be enabled and a database and role
created unless <xref
linkend="opt-services.keycloak.databaseHost" /> is changed from
its default of <literal>localhost</literal> or <xref
linkend="opt-services.keycloak.databaseCreateLocally" /> is set
to <literal>false</literal>.
</para>
<para>
External database access can also be configured by setting
<xref linkend="opt-services.keycloak.databaseHost" />, <xref
linkend="opt-services.keycloak.databaseUsername" />, <xref
linkend="opt-services.keycloak.databaseUseSSL" /> and <xref
linkend="opt-services.keycloak.databaseCaCert" /> as
appropriate. Note that you need to manually create a database
called <literal>keycloak</literal> and allow the configured
database user full access to it.
</para>
<para>
<xref linkend="opt-services.keycloak.databasePasswordFile" />
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.databaseHost" />
and <xref linkend="opt-services.keycloak.databaseCreateLocally" />
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-frontendurl">
<title>Frontend URL</title>
<para>
The frontend URL is used as base for all frontend requests and
must be configured through <xref linkend="opt-services.keycloak.frontendUrl" />.
It should normally include a trailing <literal>/auth</literal>
(the default web context).
</para>
<para>
<xref linkend="opt-services.keycloak.forceBackendUrlToFrontendUrl" />
determines whether Keycloak should force all requests to go
through the frontend URL. By default,
<productname>Keycloak</productname> 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>
See the <link
xlink:href="https://www.keycloak.org/docs/latest/server_installation/#_hostname">Hostname
section of the Keycloak Server Installation and Configuration
Guide</link> for more information.
</para>
</section>
<section xml:id="module-services-keycloak-tls">
<title>Setting up TLS/SSL</title>
<para>
By default, <productname>Keycloak</productname> won't accept
unsecured HTTP connections originating from outside its local
network.
</para>
<para>
For HTTPS support, a TLS certificate and private key is
required. They should be <link
xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM
formatted</link> and concatenated into a single file. The path
to this file should be configured in
<xref linkend="opt-services.keycloak.certificatePrivateKeyBundle" />.
</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-extra-config">
<title>Additional configuration</title>
<para>
Additional Keycloak configuration options, for which no
explicit <productname>NixOS</productname> options are provided,
can be set in <xref linkend="opt-services.keycloak.extraConfig" />.
</para>
<para>
Options are expressed as a Nix attribute set which matches the
structure of the jboss-cli configuration. The configuration is
effectively overlayed on top of the default configuration
shipped with Keycloak. To remove existing nodes and undefine
attributes from the default configuration, set them to
<literal>null</literal>.
</para>
<para>
For example, the following script, which removes the hostname
provider <literal>default</literal>, adds the deprecated
hostname provider <literal>fixed</literal> and defines it the
default:
<programlisting>
/subsystem=keycloak-server/spi=hostname/provider=default:remove()
/subsystem=keycloak-server/spi=hostname/provider=fixed:add(enabled = true, properties = { hostname = "keycloak.example.com" })
/subsystem=keycloak-server/spi=hostname:write-attribute(name=default-provider, value="fixed")
</programlisting>
would be expressed as
<programlisting>
services.keycloak.extraConfig = {
"subsystem=keycloak-server" = {
"spi=hostname" = {
"provider=default" = null;
"provider=fixed" = {
enabled = true;
properties.hostname = "keycloak.example.com";
};
default-provider = "fixed";
};
};
};
</programlisting>
</para>
<para>
You can discover available options by using the <link
xlink:href="http://docs.wildfly.org/21/Admin_Guide.html#Command_Line_Interface">jboss-cli.sh</link>
program and by referring to the <link
xlink:href="https://www.keycloak.org/docs/latest/server_installation/index.html">Keycloak
Server Installation and Configuration Guide</link>.
</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:
<programlisting>
services.keycloak = {
<link linkend="opt-services.keycloak.enable">enable</link> = true;
<link linkend="opt-services.keycloak.initialAdminPassword">initialAdminPassword</link> = "e6Wcm0RrtegMEHl"; # change on first login
<link linkend="opt-services.keycloak.frontendUrl">frontendUrl</link> = "https://keycloak.example.com/auth";
<link linkend="opt-services.keycloak.forceBackendUrlToFrontendUrl">forceBackendUrlToFrontendUrl</link> = true;
<link linkend="opt-services.keycloak.certificatePrivateKeyBundle">certificatePrivateKeyBundle</link> = "/run/keys/ssl_cert";
<link linkend="opt-services.keycloak.databasePasswordFile">databasePasswordFile</link> = "/run/keys/db_password";
};
</programlisting>
</para>
</section>
</chapter>
|
