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