diff --git a/nixos/modules/services/web-apps/keycloak.md b/nixos/modules/services/web-apps/keycloak.md new file mode 100644 index 000000000000..aa8de40d642b --- /dev/null +++ b/nixos/modules/services/web-apps/keycloak.md @@ -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"; +}; +``` diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index d52190a28648..a1f13f159f94 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -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 ]; } diff --git a/nixos/modules/services/web-apps/keycloak.xml b/nixos/modules/services/web-apps/keycloak.xml index 0d95ee3575a5..f6602a3c70df 100644 --- a/nixos/modules/services/web-apps/keycloak.xml +++ b/nixos/modules/services/web-apps/keycloak.xml @@ -1,202 +1,177 @@ - - Keycloak - - Keycloak is an - open source identity and access management server with support for - OpenID - Connect, OAUTH - 2.0 and SAML - 2.0. - -
- Administration - - An administrative user with the username - admin is automatically created in the - master realm. Its initial password can be - configured by setting - 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 for information on - how to administer your Keycloak - instance. - -
- -
- Database access - - Keycloak can be used with either - PostgreSQL, - MariaDB or - MySQL. Which one is used can be - configured in . The selected - database will automatically be enabled and a database and role - created unless is changed - from its default of localhost or is - set to false. - - - - External database access can also be configured by setting - , , , and as - appropriate. Note that you need to manually create the database - and allow the configured database user full access to it. - - - - - must be set to the path to a file containing the password used - to log in to the database. If - and - are kept at their defaults, the database role - keycloak with that password is provisioned - on the local database instance. - - - - - The path should be provided as a string, not a Nix path, since Nix - paths are copied into the world readable Nix store. - - -
- -
- Hostname - - The hostname is used to build the public URL used as base for - all frontend requests and must be configured through . - - - - - 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 to /auth. See the option description - for more details. - - - - - - 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. - -
- -
- Setting up TLS/SSL - - 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. Their paths should be set through and . - - - - - The paths should be provided as a strings, not a Nix paths, - since Nix paths are copied into the world readable Nix store. - - -
- -
- Themes - - You can package custom themes and make them visible to - Keycloak through . See the - Themes section of the Keycloak Server Development Guide - and the description of the aforementioned NixOS option for - more information. - -
- -
- Configuration file settings - - Keycloak server configuration parameters can be set in . These correspond - directly to options in - 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. - - - - 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 for an example. - -
- - -
- Example configuration - - A basic configuration with some custom settings could look like this: - + + Keycloak + + Keycloak is an + open source identity and access management server with support for + OpenID + Connect, OAUTH + 2.0 and + SAML + 2.0. + +
+ Administration + + An administrative user with the username admin + is automatically created in the master realm. + Its initial password can be configured by setting + + 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 for information on how to + administer your Keycloak instance. + +
+
+ Database access + + Keycloak can be used with either PostgreSQL, MariaDB or MySQL. + Which one is used can be configured in + . The + selected database will automatically be enabled and a database and + role created unless + is + changed from its default of localhost or + + is set to false. + + + External database access can also be configured by setting + , + , + , + and + as + appropriate. Note that you need to manually create the database + and allow the configured database user full access to it. + + + + must be set to the path to a file containing the password used to + log in to the database. If + and + + are kept at their defaults, the database role + keycloak with that password is provisioned on + the local database instance. + + + + The path should be provided as a string, not a Nix path, since + Nix paths are copied into the world readable Nix store. + + +
+
+ Hostname + + The hostname is used to build the public URL used as base for all + frontend requests and must be configured through + . + + + + 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 + + to /auth. See the option description for more + details. + + + + + 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. + +
+
+ Setting up TLS/SSL + + 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. Their paths should be set through + and + . + + + + The paths should be provided as a strings, not a Nix paths, + since Nix paths are copied into the world readable Nix store. + + +
+
+ Themes + + You can package custom themes and make them visible to Keycloak + through . See + the + Themes + section of the Keycloak Server Development Guide and the + description of the aforementioned NixOS option for more + information. + +
+
+ Configuration file settings + + Keycloak server configuration parameters can be set in + . These + correspond directly to options in + 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. + + + 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 + for an + example. + +
+
+ Example configuration + + A basic configuration with some custom settings could look like + this: + + 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"; }; - - -
- +
+