pyrox.dev
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#admin-console">Admin
31 Console section of the Keycloak Server Administration Guide</link> for
32 information on how to administer your
33 <productname>Keycloak</productname> instance.
34 </para>
35 </section>
36
37 <section xml:id="module-services-keycloak-database">
38 <title>Database access</title>
39 <para>
40 <productname>Keycloak</productname> can be used with either
41 <productname>PostgreSQL</productname> or
42 <productname>MySQL</productname>. Which one is used can be
43 configured in <xref
44 linkend="opt-services.keycloak.database.type" />. The selected
45 database will automatically be enabled and a database and role
46 created unless <xref
47 linkend="opt-services.keycloak.database.host" /> is changed from
48 its default of <literal>localhost</literal> or <xref
49 linkend="opt-services.keycloak.database.createLocally" /> is set
50 to <literal>false</literal>.
51 </para>
52
53 <para>
54 External database access can also be configured by setting
55 <xref linkend="opt-services.keycloak.database.host" />, <xref
56 linkend="opt-services.keycloak.database.username" />, <xref
57 linkend="opt-services.keycloak.database.useSSL" /> and <xref
58 linkend="opt-services.keycloak.database.caCert" /> as
59 appropriate. Note that you need to manually create a database
60 called <literal>keycloak</literal> and allow the configured
61 database user full access to it.
62 </para>
63
64 <para>
65 <xref linkend="opt-services.keycloak.database.passwordFile" />
66 must be set to the path to a file containing the password used
67 to log in to the database. If <xref linkend="opt-services.keycloak.database.host" />
68 and <xref linkend="opt-services.keycloak.database.createLocally" />
69 are kept at their defaults, the database role
70 <literal>keycloak</literal> with that password is provisioned
71 on the local database instance.
72 </para>
73
74 <warning>
75 <para>
76 The path should be provided as a string, not a Nix path, since Nix
77 paths are copied into the world readable Nix store.
78 </para>
79 </warning>
80 </section>
81
82 <section xml:id="module-services-keycloak-frontendurl">
83 <title>Frontend URL</title>
84 <para>
85 The frontend URL is used as base for all frontend requests and
86 must be configured through <xref linkend="opt-services.keycloak.frontendUrl" />.
87 It should normally include a trailing <literal>/auth</literal>
88 (the default web context).
89 </para>
90
91 <para>
92 <xref linkend="opt-services.keycloak.forceBackendUrlToFrontendUrl" />
93 determines whether Keycloak should force all requests to go
94 through the frontend URL. By default,
95 <productname>Keycloak</productname> allows backend requests to
96 instead use its local hostname or IP address and may also
97 advertise it to clients through its OpenID Connect Discovery
98 endpoint.
99 </para>
100
101 <para>
102 See the <link
103 xlink:href="https://www.keycloak.org/docs/latest/server_installation/#_hostname">Hostname
104 section of the Keycloak Server Installation and Configuration
105 Guide</link> for more information.
106 </para>
107 </section>
108
109 <section xml:id="module-services-keycloak-tls">
110 <title>Setting up TLS/SSL</title>
111 <para>
112 By default, <productname>Keycloak</productname> won't accept
113 unsecured HTTP connections originating from outside its local
114 network.
115 </para>
116
117 <para>
118 HTTPS support requires a TLS/SSL certificate and a private key,
119 both <link
120 xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM
121 formatted</link>. Their paths should be set through <xref
122 linkend="opt-services.keycloak.sslCertificate" /> and <xref
123 linkend="opt-services.keycloak.sslCertificateKey" />.
124 </para>
125
126 <warning>
127 <para>
128 The paths should be provided as a strings, not a Nix paths,
129 since Nix paths are copied into the world readable Nix store.
130 </para>
131 </warning>
132 </section>
133
134 <section xml:id="module-services-keycloak-extra-config">
135 <title>Additional configuration</title>
136 <para>
137 Additional Keycloak configuration options, for which no
138 explicit <productname>NixOS</productname> options are provided,
139 can be set in <xref linkend="opt-services.keycloak.extraConfig" />.
140 </para>
141
142 <para>
143 Options are expressed as a Nix attribute set which matches the
144 structure of the jboss-cli configuration. The configuration is
145 effectively overlayed on top of the default configuration
146 shipped with Keycloak. To remove existing nodes and undefine
147 attributes from the default configuration, set them to
148 <literal>null</literal>.
149 </para>
150 <para>
151 For example, the following script, which removes the hostname
152 provider <literal>default</literal>, adds the deprecated
153 hostname provider <literal>fixed</literal> and defines it the
154 default:
155
156<programlisting>
157/subsystem=keycloak-server/spi=hostname/provider=default:remove()
158/subsystem=keycloak-server/spi=hostname/provider=fixed:add(enabled = true, properties = { hostname = "keycloak.example.com" })
159/subsystem=keycloak-server/spi=hostname:write-attribute(name=default-provider, value="fixed")
160</programlisting>
161
162 would be expressed as
163
164<programlisting>
165services.keycloak.extraConfig = {
166 "subsystem=keycloak-server" = {
167 "spi=hostname" = {
168 "provider=default" = null;
169 "provider=fixed" = {
170 enabled = true;
171 properties.hostname = "keycloak.example.com";
172 };
173 default-provider = "fixed";
174 };
175 };
176};
177</programlisting>
178 </para>
179 <para>
180 You can discover available options by using the <link
181 xlink:href="http://docs.wildfly.org/21/Admin_Guide.html#Command_Line_Interface">jboss-cli.sh</link>
182 program and by referring to the <link
183 xlink:href="https://www.keycloak.org/docs/latest/server_installation/index.html">Keycloak
184 Server Installation and Configuration Guide</link>.
185 </para>
186 </section>
187
188 <section xml:id="module-services-keycloak-example-config">
189 <title>Example configuration</title>
190 <para>
191 A basic configuration with some custom settings could look like this:
192<programlisting>
193services.keycloak = {
194 <link linkend="opt-services.keycloak.enable">enable</link> = true;
195 <link linkend="opt-services.keycloak.initialAdminPassword">initialAdminPassword</link> = "e6Wcm0RrtegMEHl"; # change on first login
196 <link linkend="opt-services.keycloak.frontendUrl">frontendUrl</link> = "https://keycloak.example.com/auth";
197 <link linkend="opt-services.keycloak.forceBackendUrlToFrontendUrl">forceBackendUrlToFrontendUrl</link> = true;
198 <link linkend="opt-services.keycloak.sslCertificate">sslCertificate</link> = "/run/keys/ssl_cert";
199 <link linkend="opt-services.keycloak.sslCertificateKey">sslCertificateKey</link> = "/run/keys/ssl_key";
200 <link linkend="opt-services.keycloak.database.passwordFile">database.passwordFile</link> = "/run/keys/db_password";
201};
202</programlisting>
203 </para>
204
205 </section>
206 </chapter>