depot/nixos/modules/services/web-apps/keycloak.md

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.

::: {.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

The hostname is used to build the public URL used as base for all frontend requests and must be configured through .

::: {.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 to /auth. See the option description for more details. :::

Keycloak has the capability to offer a separate URL for backchannel requests, enabling internal communication while maintaining the use of a public URL for frontchannel requests. Moreover, the backchannel is dynamically resolved based on incoming headers 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 .

::: {.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

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 {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.

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-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";
  };
}