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