nixos/keycloak: convert manual chapter to MD
This commit is contained in:
pennae
@@ -0,0 +1,141 @@
|
||||
# Keycloak {#module-services-keycloak}
|
||||
|
||||
[Keycloak](https://www.keycloak.org/) is an
|
||||
open source identity and access management server with support for
|
||||
[OpenID Connect](https://openid.net/connect/),
|
||||
[OAUTH 2.0](https://oauth.net/2/) and
|
||||
[SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0).
|
||||
|
||||
## Administration {#module-services-keycloak-admin}
|
||||
|
||||
An administrative user with the username
|
||||
`admin` is automatically created in the
|
||||
`master` realm. Its initial password can be
|
||||
configured by setting [](#opt-services.keycloak.initialAdminPassword)
|
||||
and defaults to `changeme`. The password is
|
||||
not stored safely and should be changed immediately in the
|
||||
admin panel.
|
||||
|
||||
Refer to the [Keycloak Server Administration Guide](
|
||||
https://www.keycloak.org/docs/latest/server_admin/index.html
|
||||
) for information on
|
||||
how to administer your Keycloak
|
||||
instance.
|
||||
|
||||
## Database access {#module-services-keycloak-database}
|
||||
|
||||
Keycloak can be used with either PostgreSQL, MariaDB or
|
||||
MySQL. Which one is used can be
|
||||
configured in [](#opt-services.keycloak.database.type). The selected
|
||||
database will automatically be enabled and a database and role
|
||||
created unless [](#opt-services.keycloak.database.host) is changed
|
||||
from its default of `localhost` or
|
||||
[](#opt-services.keycloak.database.createLocally) is set to `false`.
|
||||
|
||||
External database access can also be configured by setting
|
||||
[](#opt-services.keycloak.database.host),
|
||||
[](#opt-services.keycloak.database.name),
|
||||
[](#opt-services.keycloak.database.username),
|
||||
[](#opt-services.keycloak.database.useSSL) and
|
||||
[](#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.
|
||||
|
||||
[](#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 [](#opt-services.keycloak.database.host)
|
||||
and [](#opt-services.keycloak.database.createLocally)
|
||||
are kept at their defaults, the database role
|
||||
`keycloak` with that password is provisioned
|
||||
on the local database instance.
|
||||
|
||||
::: {.warning}
|
||||
The path should be provided as a string, not a Nix path, since Nix
|
||||
paths are copied into the world readable Nix store.
|
||||
:::
|
||||
|
||||
## Hostname {#module-services-keycloak-hostname}
|
||||
|
||||
The hostname is used to build the public URL used as base for
|
||||
all frontend requests and must be configured through
|
||||
[](#opt-services.keycloak.settings.hostname).
|
||||
|
||||
::: {.note}
|
||||
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 [](#opt-services.keycloak.settings.http-relative-path)
|
||||
to `/auth`. See the option description
|
||||
for more details.
|
||||
:::
|
||||
|
||||
[](#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.
|
||||
|
||||
For more information on hostname configuration, see the [Hostname
|
||||
section of the Keycloak Server Installation and Configuration
|
||||
Guide](https://www.keycloak.org/server/hostname).
|
||||
|
||||
## Setting up TLS/SSL {#module-services-keycloak-tls}
|
||||
|
||||
By default, Keycloak won't accept
|
||||
unsecured HTTP connections originating from outside its local
|
||||
network.
|
||||
|
||||
HTTPS support requires a TLS/SSL certificate and a private key,
|
||||
both [PEM formatted](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
|
||||
Their paths should be set through
|
||||
[](#opt-services.keycloak.sslCertificate) and
|
||||
[](#opt-services.keycloak.sslCertificateKey).
|
||||
|
||||
::: {.warning}
|
||||
The paths should be provided as a strings, not a Nix paths,
|
||||
since Nix paths are copied into the world readable Nix store.
|
||||
:::
|
||||
|
||||
## Themes {#module-services-keycloak-themes}
|
||||
|
||||
You can package custom themes and make them visible to
|
||||
Keycloak through [](#opt-services.keycloak.themes). See the
|
||||
[Themes section of the Keycloak Server Development Guide](
|
||||
https://www.keycloak.org/docs/latest/server_development/#_themes
|
||||
) and the description of the aforementioned NixOS option for
|
||||
more information.
|
||||
|
||||
## Configuration file settings {#module-services-keycloak-settings}
|
||||
|
||||
Keycloak server configuration parameters can be set in
|
||||
[](#opt-services.keycloak.settings). These correspond
|
||||
directly to options in
|
||||
{file}`conf/keycloak.conf`. Some of the most
|
||||
important parameters are documented as suboptions, the rest can
|
||||
be found in the [All
|
||||
configuration section of the Keycloak Server Installation and
|
||||
Configuration Guide](https://www.keycloak.org/server/all-config).
|
||||
|
||||
Options containing secret data should be set to an attribute
|
||||
set containing the attribute `_secret` - a
|
||||
string pointing to a file containing the value the option
|
||||
should be set to. See the description of
|
||||
[](#opt-services.keycloak.settings) for an example.
|
||||
|
||||
## Example configuration {#module-services-keycloak-example-config}
|
||||
|
||||
A basic configuration with some custom settings could look like this:
|
||||
```
|
||||
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";
|
||||
};
|
||||
```
|
||||
@@ -674,6 +674,8 @@ in
|
||||
mkIf createLocalMySQL (mkDefault dbPkg);
|
||||
};
|
||||
|
||||
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||
# `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`
|
||||
meta.doc = ./keycloak.xml;
|
||||
meta.maintainers = [ maintainers.talyz ];
|
||||
}
|
||||
|
||||
@@ -1,202 +1,177 @@
|
||||
<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">
|
||||
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:
|
||||
<programlisting>
|
||||
<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"></xref>
|
||||
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"></xref>. The
|
||||
selected database will automatically be enabled and a database and
|
||||
role created unless
|
||||
<xref linkend="opt-services.keycloak.database.host"></xref> is
|
||||
changed from its default of <literal>localhost</literal> or
|
||||
<xref linkend="opt-services.keycloak.database.createLocally"></xref>
|
||||
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>,
|
||||
<xref linkend="opt-services.keycloak.database.name"></xref>,
|
||||
<xref linkend="opt-services.keycloak.database.username"></xref>,
|
||||
<xref linkend="opt-services.keycloak.database.useSSL"></xref> and
|
||||
<xref linkend="opt-services.keycloak.database.caCert"></xref> 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"></xref>
|
||||
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"></xref> and
|
||||
<xref linkend="opt-services.keycloak.database.createLocally"></xref>
|
||||
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"></xref>.
|
||||
</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"></xref>
|
||||
to <literal>/auth</literal>. See the option description for more
|
||||
details.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
<xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel"></xref>
|
||||
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"></xref> and
|
||||
<xref linkend="opt-services.keycloak.sslCertificateKey"></xref>.
|
||||
</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"></xref>. 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"></xref>. 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"></xref> 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 = "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";
|
||||
initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login
|
||||
sslCertificate = "/run/keys/ssl_cert";
|
||||
sslCertificateKey = "/run/keys/ssl_key";
|
||||
database.passwordFile = "/run/keys/db_password";
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user