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