Keycloak is an open source identity and access management server with support for OpenID Connect, OAUTH 2.0 and SAML 2.0.

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.

Keycloak can be used with either PostgreSQL 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 a database called keycloak 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.

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). If you use a reverse proxy, you need to set this option to "", so that frontend URL is derived from HTTP headers. X-Forwarded-* headers support also should be enabled, using respective guidelines. 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.

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.

You can package custom themes and make them visible to Keycloak via option. See the Themes section of the Keycloak Server Development Guide and respective NixOS option description for more information.

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.

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; sslCertificate = "/run/keys/ssl_cert"; sslCertificateKey = "/run/keys/ssl_key"; database.passwordFile = "/run/keys/db_password"; };