diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index c1020690299e..9c6a5ca305cb 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -564,4 +564,6 @@ in services.postgresql.enable = lib.mkDefault databaseActuallyCreateLocally; }; + + meta.doc = ./keycloak.xml; } diff --git a/nixos/modules/services/web-apps/keycloak.xml b/nixos/modules/services/web-apps/keycloak.xml new file mode 100644 index 000000000000..6b97d48e0bd8 --- /dev/null +++ b/nixos/modules/services/web-apps/keycloak.xml @@ -0,0 +1,190 @@ + + 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 Admin + Console section of the Keycloak Server Administration Guide for + information on how to administer your + Keycloak instance. + +
+ +
+ Database access + + Keycloak depends on + PostgreSQL and will automatically + enable it and create a database and role unless configured not + to, either by changing + from its default of localhost or setting + + to false. + + + + + 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. + + +
+ +
+ Frontend URL + + The frontend URL is used as base for all frontend requests and + must be configured through . + It should normally include a trailing /auth + (the default web context). + + + + + 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. + + + + See the Hostname + section of the Keycloak Server Installation and Configuration + Guide for more information. + +
+ +
+ Setting up TLS/SSL + + By default, Keycloak won't accept + unsecured HTTP connections originating from outside its local + network. + + + + For HTTPS support, a TLS certificate and private key is + required. They should be PEM + formatted and concatenated into a single file. The path + to this file should be configured in + . + + + + + The path should be provided as a string, not a Nix path, + since Nix paths are copied into the world readable Nix store. + + +
+ +
+ Additional configuration + + Additional Keycloak configuration options, for which no + explicit NixOS options are provided, + can be set in . + + + + 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 + null. + + + For example, the following script, which removes the hostname + provider default, adds the deprecated + hostname provider fixed and defines it the + default: + + +/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") + + + would be expressed as + + +services.keycloak.extraConfig = { + "subsystem=keycloak-server" = { + "spi=hostname" = { + "provider=default" = null; + "provider=fixed" = { + enabled = true; + properties.hostname = "keycloak.example.com"; + }; + default-provider = "fixed"; + }; + }; +}; + + + + You can discover available options by using the jboss-cli.sh + program and by referring to the Keycloak + Server Installation and Configuration Guide. + +
+ +
+ Example configuration + + A basic configuration with some custom settings could look like this: + +services.keycloak = { + enable = true; + initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login + frontendUrl = "https://keycloak.example.com/auth"; + forceBackendUrlToFrontendUrl = true; + certificatePrivateKeyBundle = "/run/keys/ssl_cert"; + databasePasswordFile = "/run/keys/db_password"; +}; + + + +
+