dput-ng: fix eval (#364540)
[NixPkgs.git] / nixos / modules / services / web-apps / keycloak.md
blob4036885ce151c5b1372bc9cdb28fcf1268554b9c
1 # Keycloak {#module-services-keycloak}
3 [Keycloak](https://www.keycloak.org/) is an
4 open source identity and access management server with support for
5 [OpenID Connect](https://openid.net/connect/),
6 [OAUTH 2.0](https://oauth.net/2/) and
7 [SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0).
9 ## Administration {#module-services-keycloak-admin}
11 An administrative user with the username
12 `admin` is automatically created in the
13 `master` realm. Its initial password can be
14 configured by setting [](#opt-services.keycloak.initialAdminPassword)
15 and defaults to `changeme`. The password is
16 not stored safely and should be changed immediately in the
17 admin panel.
19 Refer to the [Keycloak Server Administration Guide](
20   https://www.keycloak.org/docs/latest/server_admin/index.html
21 ) for information on
22 how to administer your Keycloak
23 instance.
25 ## Database access {#module-services-keycloak-database}
27 Keycloak can be used with either PostgreSQL, MariaDB or
28 MySQL. Which one is used can be
29 configured in [](#opt-services.keycloak.database.type). The selected
30 database will automatically be enabled and a database and role
31 created unless [](#opt-services.keycloak.database.host) is changed
32 from its default of `localhost` or
33 [](#opt-services.keycloak.database.createLocally) is set to `false`.
35 External database access can also be configured by setting
36 [](#opt-services.keycloak.database.host),
37 [](#opt-services.keycloak.database.name),
38 [](#opt-services.keycloak.database.username),
39 [](#opt-services.keycloak.database.useSSL) and
40 [](#opt-services.keycloak.database.caCert) as
41 appropriate. Note that you need to manually create the database
42 and allow the configured database user full access to it.
44 [](#opt-services.keycloak.database.passwordFile)
45 must be set to the path to a file containing the password used
46 to log in to the database. If [](#opt-services.keycloak.database.host)
47 and [](#opt-services.keycloak.database.createLocally)
48 are kept at their defaults, the database role
49 `keycloak` with that password is provisioned
50 on the local database instance.
52 ::: {.warning}
53 The path should be provided as a string, not a Nix path, since Nix
54 paths are copied into the world readable Nix store.
55 :::
57 ## Hostname {#module-services-keycloak-hostname}
59 The hostname is used to build the public URL used as base for
60 all frontend requests and must be configured through
61 [](#opt-services.keycloak.settings.hostname).
63 ::: {.note}
64 If you're migrating an old Wildfly based Keycloak instance
65 and want to keep compatibility with your current clients,
66 you'll likely want to set [](#opt-services.keycloak.settings.http-relative-path)
67 to `/auth`. See the option description
68 for more details.
69 :::
71 [](#opt-services.keycloak.settings.hostname-backchannel-dynamic)
72 Keycloak has the capability to offer a separate URL for backchannel requests,
73 enabling internal communication while maintaining the use of a public URL
74 for frontchannel requests. Moreover, the backchannel is dynamically
75 resolved based on incoming headers endpoint.
77 For more information on hostname configuration, see the [Hostname
78 section of the Keycloak Server Installation and Configuration
79 Guide](https://www.keycloak.org/server/hostname).
81 ## Setting up TLS/SSL {#module-services-keycloak-tls}
83 By default, Keycloak won't accept
84 unsecured HTTP connections originating from outside its local
85 network.
87 HTTPS support requires a TLS/SSL certificate and a private key,
88 both [PEM formatted](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
89 Their paths should be set through
90 [](#opt-services.keycloak.sslCertificate) and
91 [](#opt-services.keycloak.sslCertificateKey).
93 ::: {.warning}
94  The paths should be provided as a strings, not a Nix paths,
95 since Nix paths are copied into the world readable Nix store.
96 :::
98 ## Themes {#module-services-keycloak-themes}
100 You can package custom themes and make them visible to
101 Keycloak through [](#opt-services.keycloak.themes). See the
102 [Themes section of the Keycloak Server Development Guide](
103   https://www.keycloak.org/docs/latest/server_development/#_themes
104 ) and the description of the aforementioned NixOS option for
105 more information.
107 ## Configuration file settings {#module-services-keycloak-settings}
109 Keycloak server configuration parameters can be set in
110 [](#opt-services.keycloak.settings). These correspond
111 directly to options in
112 {file}`conf/keycloak.conf`. Some of the most
113 important parameters are documented as suboptions, the rest can
114 be found in the [All
115 configuration section of the Keycloak Server Installation and
116 Configuration Guide](https://www.keycloak.org/server/all-config).
118 Options containing secret data should be set to an attribute
119 set containing the attribute `_secret` - a
120 string pointing to a file containing the value the option
121 should be set to. See the description of
122 [](#opt-services.keycloak.settings) for an example.
124 ## Example configuration {#module-services-keycloak-example-config}
126 A basic configuration with some custom settings could look like this:
127 ```nix
129   services.keycloak = {
130     enable = true;
131     settings = {
132       hostname = "keycloak.example.com";
133       hostname-strict-backchannel = true;
134     };
135     initialAdminPassword = "e6Wcm0RrtegMEHl";  # change on first login
136     sslCertificate = "/run/keys/ssl_cert";
137     sslCertificateKey = "/run/keys/ssl_key";
138     database.passwordFile = "/run/keys/db_password";
139   };