Server installation and configuration

Keycloak is a highly modular system that allows great flexibility. There are more than 50 service provider interfaces SPIs , and you are allowed to swap out implementations of each SPI. An implementation of an SPI is known as a provider. Here we have two providers defined for the SPI myspi. The default-provider is listed as myprovider.

However it is up to the SPI to decide how it will treat this setting. Some SPIs allow more than one provider and some do not. So default-provider can help the SPI to choose. Also notice that each provider defines its own set of configuration properties. The fact that both providers above have a property called foo is just a coincidence. The type of each property value is interpreted by the provider. However, there is one exception. Consider the jpa provider for the eventsStore SPI:.

We see that the value begins and ends with square brackets. That means that the value will be passed to the provider as a list. To add more values to the list, just separate each list element with a comma. Follow the steps in Server Developer Guide for more details on custom providers and the configuration of providers.

Besides editing the configuration by hand, you also have the option of changing the configuration by issuing commands via the jboss-cli tool. CLI allows you to configure servers locally or remotely.

And it is especially useful when combined with scripting. If you wish to execute commands on a running server, you will first execute the connect command. If you run jboss-cli on the same machine as your running standalone server or domain controller and your account has appropriate file permissions, you do not have to setup or enter in an admin username and password.

See the WildFly 23 Documentation for more details on how to make things more secure if you are uncomfortable with that setup. If you do happen to be on the same machine as your standalone server and you want to issue commands while the server is not active, you can embed the server into CLI and make changes in a special mode that disallows incoming requests. To do this, first execute the embed-server command with the config file you wish to change. GUI mode launches a Swing application that allows you to graphically view and edit the entire management model of a running server.

GUI mode is especially useful when you need help formatting your CLI commands and learning about the options available. The GUI can also retrieve server logs from a local or remote server. Note: to connect to a remote server, you pass the --connect option as well.

Use the --help option for more details. The CLI has extensive scripting capabilities. A script is just a text file with CLI commands in it. Consider a simple script that turns off theme and template caching. Here are some configuration tasks and how to perform them with CLI commands.

There are features in Keycloak that are not enabled by default, these include features that are not fully supported. In addition there are some features that are enabled by default, but that can be disabled. Add the following to the file:. For example to disable Impersonation use -Dkeycloak. Keycloak comes with its own embedded Java-based relational database called H2. This is the default database that Keycloak will use to persist data and really only exists so that you can run the authentication server out of the box.

We highly recommend that you replace it with a more production ready external database. The H2 database is not very viable in high concurrency situations and should not be used in a cluster either.

The purpose of this chapter is to show you how to connect Keycloak to a more mature database. Keycloak uses two layered technologies to persist its relational data. The bottom layered technology is JDBC. There are different JDBC drivers per database type that are provided by your database vendor. This chapter discusses how to configure Keycloak to use one of these vendor-specific drivers.

The top layered technology for persistence is Hibernate JPA. Most deployments of Keycloak will never have to touch the configuration aspects of Hibernate, but we will discuss how that is done if you run into that rare circumstance.

This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation. Before you can use this driver, you must package it up into a module and install it into the server. The convention is use the Java package name of the JDBC driver for the name of the directory structure.

Copy your database driver JAR into this directory and create an empty module. The module name should match the directory structure of your module. You declare your JDBC into your deployment profile so that it loads and becomes available when the server boots up.

In domain mode, make sure you edit the profile you are using: either auth-server-standalone or auth-server-clustered. Within the profile, search for the drivers XML block within the datasources subsystem. Specify the module attribute which points to the module package that you created earlier for the driver JAR. You modify the existing datasource configuration that Keycloak uses to connect it to your new external database.

This is the logical name of the JDBC driver you declared in the previous section of this chapter. It is expensive to open a new connection to a database every time you want to perform a transaction.

To compensate, the datasource implementation maintains a pool of open connections. The max-pool-size specifies the maximum number of connections it will pool. You may want to change the value of this depending on the load of your system. Define the database username and password that is needed to connect to the database.

This step is necessary for at least PostgreSQL. You may be concerned that these credentials are in clear text in the example. Methods exist to obfuscate these credentials, but these methods are beyond the scope of this guide. The configuration for this component is found in the standalone. Value of database dialect. Initialize database if empty. If set to false the database has to be manually initialized.

If you want to manually initialize the database set migrationStrategy to manual which will create a file with SQL commands to initialize the database. Defaults to true. Strategy to use to migrate database. Valid values are update , manual and validate. Update will automatically migrate the database schema. Manual will export the required changes to a file with SQL commands that you can manually execute on the database.

Validate will simply check if the database is up-to-date. Specify whether Hibernate should show all SQL commands in the console false by default. This is very verbose! Will log global statistics from Hibernate about executed DB queries and other things. Statistics are always reported to server log at specified interval in seconds and are cleared after each report.

Otherwise, characters are limited to those contained in database encoding which is often 8-bit. However, for some database systems, it is possible to enable UTF-8 encoding of Unicode characters and use full Unicode character set in all text fields. Often, this is counterbalanced by shorter maximum length of the strings than in case of 8-bit encodings. Please find the settings for your database below.

Note that if a database is listed here, it can still work properly provided it handles UTF-8 encoding properly both on the level of database and JDBC driver. If yes, there is a high chance that Unicode will be plausible, usually at the expense of field length. No special settings is needed for JDBC driver. If the database character set is not Unicode, then to use Unicode characters in the special fields, the JDBC driver needs to be configured with the connection property oracle.

It might be wise, though not strictly necessary, to also set the oracle. These properties can be set either as system properties or as connection properties. Please note that setting oracle. Unicode characters are properly handled only for the special fields. No special settings of JDBC driver or database is necessary. Please note that utf8mb4 character set does not work due to different storage requirements to utf8 character set [ 1 ].

Note that in this case, length restriction to non-special fields does not apply because columns are created to accommodate given amount of characters, not bytes. If the database default character set does not allow storing Unicode, only the special fields allow storing Unicode values. Unicode is supported when the database character set is UTF8. In that case, Unicode characters can be used in any field, there is no reduction of field length for non-special fields.

No special settings of JDBC driver is necessary. The character set of a PostgreSQL database is determined at the time it is created. If the default character set is not UTF 8, then you can create the database with UTF8 as its character set like this:.

Keycloak uses the public hostname for a number of things. For example, in the token issuer fields and URLs sent in password reset emails. The Hostname SPI provides a way to configure the hostname for a request. The default provider allows setting a fixed URL for frontend requests, while allowing backend requests to be based on the request URI.

It is also possible to develop your own provider in the case the built-in provider does not provide the functionality needed. The default hostname provider uses the configured frontendUrl as the base URL for frontend requests requests from user-agents and uses the request URL as the basis for backend requests direct requests from clients. Frontend request do not have to have the same context-path as the Keycloak server. This makes it possible to have user-agents browsers send requests to Keycloak through the public domain name, while internal clients can use an internal domain name or IP address.

To set the frontendUrl for Keycloak you can either pass add -Dkeycloak. See the example below:. If you want all requests to go through the public domain name you can force backend requests to use the frontend URL as well by setting forceBackendUrlToFrontendUrl to true.

It is also possible to override the default frontend URL for individual realms. This can be done in the admin console. If you do not want to expose the admin endpoints and console on the public domain use the property adminUrl to set a fixed URL for the admin console, which is different to the frontendUrl. To develop a custom hostname provider you need to implement org.

HostnameProviderFactory and org. Follow the instructions in the Service Provider Interfaces section in Server Developer Guide for more information on how to develop a custom provider. The default installation of Keycloak can run with some networking limitations. For one, all network endpoints bind to localhost so the auth server is really only usable on one local machine.

For HTTP based connections, it does not use default ports like 80 and Finally, Keycloak may often need to make secure SSL and HTTPS connections to external servers and thus need a trust store set up so that endpoints can be validated correctly. This chapter discusses all of these things. By default Keycloak binds to the localhost loopback address Generally, what we recommend is that you deploy a reverse proxy or load balancer on a public network and route traffic to individual Keycloak server instances on a private network.

In either case though, you still need to set up your network interfaces to bind to something other than localhost. Setting the bind address is quite easy and can be done on the command line with either the standalone.

Open up the profile configuration file standalone. The public interface corresponds to subsystems creating sockets that are available publicly. An example of one of these subsystems is the web layer which serves up the authentication endpoints of Keycloak.

The management interface corresponds to sockets opened up by the management layer of the WildFly. Specifically the sockets which allow you to use the jboss-cli. This string denotes a value The -b is just a shorthand notation for this command.

So, you can either change the bind address value directly in the profile config, or change it on the command line when you boot up. The ports opened for each socket have a pre-defined default that can be overridden at the command line or within configuration.

Search for socket-binding-group. These bindings specify the interface bind address they use as well as what port number they will open. The ones you will be most interested in are:. This socket binding defines the port used for the AJP protocol. When running in domain mode setting the socket configurations is a bit trickier as the example domain. If you scroll down to the server-group definitions you can see what socket-binding-group is used for each server-group.

Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost , Keycloak does not require SSL. This should really only be used in development when you are playing around with things. This involves. When you see the question What is your first and last name?

For testing purposes, localhost should be used. After executing this command, the keycloak. However, you first need to use the following procedure. Where yourdomain is a DNS name for which this certificate is generated. Keytool generates the request:. Now that you have a Java keystore with the appropriate certificates, you need to configure your Keycloak installation to use it. Edit the standalone. If you are using absolute paths, remove the optional relative-to parameter from your configuration See operating mode.

Here is an example, which you would repeat for each host:. The Keycloak server often needs to make non-browser HTTP requests to the applications and services it secures. The auth server manages these outgoing connections by maintaining an HTTP client connection pool. Maximum time the connection might stay idle in the connection pool seconds by default. Set to -1 to disable this checking and the background thread.

This is the file path to a Java keystore file. This keystore contains client certificate for two-way SSL. Password for the client keystore. Denotes proxy configurations for outgoing HTTP requests. If an outgoing request requires HTTPS and this config option is set to true you do not have to specify a truststore.

This setting should only be used during development and never in production as it will disable verification of SSL certificates. The default value is false. Outgoing HTTP requests sent by Keycloak can optionally use a proxy server based on a comma delimited list of proxy-mappings. A proxy-mapping denotes the combination of a regex based hostname pattern and a proxy-uri in the form of hostnamePattern;proxyUri , e.

To determine the proxy for an outgoing HTTP request the target hostname is matched against the configured hostname patterns. The first matching pattern determines the proxy-uri to use. If none of the configured patterns match for the given hostname then no proxy is used. It is possible to specify a catch-all pattern at the end of the proxy-mappings to define a default proxy for all outgoing requests.

This can be configured via the following jboss-cli command. Note that you need to properly escape the regex-pattern as shown below. The jboss-cli command results in the following subsystem configuration.

Keycloak does not differ between the two. If a hostname is specified, all its prefixes subdomains are also excluded from using proxy. However, for example groups. If proxy mappings are defined using the subsystem configuration as described above , the environment variables are not considered by Keycloak. To do so, you can specify a generic no proxy route as follows:. This is necessary in order to prevent man-in-the-middle attacks.

This truststore is managed by the Keycloak server. The truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications. You can use keytool to create a new truststore file or add trusted host certificates to an existing one:. The truststore is configured within the standalone. You can add your truststore configuration by using the following template:. The path to a Java keystore file.

HTTPS requests need a way to verify the host of the server they are talking to. This is what the trustore does. The keystore contains one or more trusted host certificates or certificate authorities.

This truststore file should only contain public certificates of your secured hosts. ANY means that the hostname is not verified. Picking an operation mode and configuring a shared database have been discussed earlier in this guide. This chapter describes setting up a load balancer and supplying a private network as well as booting up a host in the cluster.

This isolates all clustering connections and provides a nice means of protecting the servers. Keycloak does come with an out of the box clustering demo that leverages domain mode. Review the Clustered Domain Example chapter for more details. This section discusses a number of things you need to configure before you can put a reverse proxy or load balancer in front of your clustered Keycloak deployment.

It also covers configuring the built-in load balancer that was Clustered Domain Example. The following diagram illustrates the use of a load balancer. In this example, the load balancer serves as a reverse proxy between three clients and a cluster of three Keycloak servers. A few features in Keycloak rely on the fact that the remote address of the HTTP client connecting to the authentication server is the real IP address of the client machine.

Examples include:. Authentication flows - a custom authentication flow that uses the IP address to for example show OTP only for external requests. This can be problematic when you have a reverse proxy or loadbalancer in front of your Keycloak authentication server. The usual setup is that you have a frontend proxy sitting on a public network that load balances and forwards requests to backend Keycloak server instances located in a private network.

There is some extra configuration you have to do in this scenario so that the actual client IP address is forwarded to and processed by the Keycloak server instances. Take extra precautions to ensure that the X-Forwarded-For header is set by your proxy.

This becomes really important if you are doing any black or white listing of IP addresses. Beyond the proxy itself, there are a few things you need to configure on the Keycloak side of things. To do this, open up the profile configuration file standalone. Add the proxy-address-forwarding attribute to the http-listener element. Set the value to true.

Instead of modifying the http-listener , you need to add a filter to pull this information from the AJP packets. Add the redirect-socket attribute to the http-listener element. The value should be proxy-https which points to a socket binding you also need to define. Make sure the endpoints starts with the address scheme, domain and port of your reverse proxy or load balancer.

By doing this you make sure that Keycloak is using the correct endpoint. This should show a warning in the server log something like this:.

Check that the value of ipAddress is the IP address of the machine you tried to login with and not the IP address of the reverse proxy or load balancer. This section covers configuring the built-in load balancer that is discussed in the Clustered Domain Example. The Clustered Domain Example is only designed to run on one machine. Copy the server distribution.

Edit the host-slave. Open domain. Go to the undertow configuration in the load-balancer profile. Add a new host definition called remote-host3 within the reverse-proxy XML block. The output-socket-binding is a logical name pointing to a socket-binding configured later in the domain. The instance-id attribute must also be unique to the new host as this value is used by a cookie to enable sticky sessions when load balancing. Go down to the load-balancer-sockets socket-binding-group and add the outbound-socket-binding for remote-host3.

Either edit the domain. Either edit the host-slave. The values of jboss. The value of jboss. See the load balancing section in the WildFly 23 Documentation for information how to use other software-based load balancers.

Typical cluster deployment consists of the load balancer reverse proxy and 2 or more Keycloak servers on private network. For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same Keycloak backend node. The reason is, that Keycloak is using Infinispan distributed cache under the covers for save data related to current authentication session and user session.

The Infinispan distributed caches are configured with one owner by default. That means that particular session is saved just on one cluster node and the other nodes need to lookup the session remotely if they want to access it. For example if authentication session with ID is saved in the Infinispan cache on node1 , and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity. It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions.

The workflow in the cluster environment with the public frontend load balancer and two backend Keycloak nodes can be like this:. This request is served by the frontend load balancer, which forwards it to some random node eg. It all depends on the implementation and configuration of underlying load balancer reverse proxy. Keycloak creates authentication session with random ID eg. Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID.

See Infinispan documentation for more details around this. In our example case, it will be From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID and hence Infinispan can lookup this session locally.

After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above.

How exactly do this is dependent on your loadbalancer. It is recommended on the Keycloak side to use the system property jboss. For example, -Djboss. Here is an example of the start up command using this system property:. Typically in production environment the route name should use the same name as your backend host, but it is not required. You can use a different route name. For example, if you want to hide the host name of your Keycloak server inside your private network.

Some load balancers can be configured to add the route information by themselves instead of relying on the back end Keycloak node. However, as described above, adding the route by the Keycloak is recommended. This is because when done this way performance improves, since Keycloak is aware of the entity that is the owner of particular session and can route to that node, which is not necessarily the local node.

The default clustering support needs IP Multicast. Multicast is a network broadcast protocol. This protocol is used at boot time to discover and join the cluster. It is also used to broadcast messages for the replication and invalidation of distributed caches used by Keycloak. The clustering subsystem for Keycloak runs on the JGroups stack. Out of the box, the bind addresses for clustering are bound to a private network interface with Edit your the standalone-ha.

Configure the jboss. When cluster nodes are isolated on a private network it requires access to the private network to be able to join a cluster or to view communication in the cluster. In addition you can also enable authentication and encryption for cluster communication. As long as your private network is secure it is not necessary to enable authentication and encryption.

Keycloak does not send very sensitive information on the cluster in either case. If you want to enable authentication and encryption for clustering communication, see the 'High Availability Guide' in the WildFly documentation. Keycloak cluster nodes are allowed to boot concurrently. When Keycloak server instance boots up it may do some database migration, importing, or first time initializations. A DB lock is used to prevent start actions from conflicting with one another when cluster nodes boot up concurrently.

By default, the maximum timeout for this lock is seconds. If a node is waiting on this lock for more than the timeout it will fail to boot. You may need to use additional parameters or system properties.

For example, the parameter -b for the binding host or the system property jboss. Note that when you run a cluster, you should see message similar to this in the log of both cluster nodes:. Firewall could be enabled just on public access point to your network instead. If for some reason you still need to have firewall enabled on cluster nodes, you will need to open some ports. Default values are UDP port and multicast port with multicast address Note that you may need more ports opened if you want to enable additional features like diagnostics for your JGroups stack.

If you are interested in failover support high availability , evictions, expiration and cache tuning, see Server cache configuration. Keycloak has two types of caches. One type of cache sits in front of the database to decrease load on the DB and to decrease overall response times by keeping data in memory. Realm, client, role, and user metadata is kept in this type of cache. This cache is a local cache. Local caches do not use replication even if you are in the cluster with more Keycloak servers.

Instead, they only keep copies locally and if the entry is updated an invalidation message is sent to the rest of the cluster and the entry is evicted. There is separate replicated cache work , which task is to send the invalidation messages to the whole cluster about what entries should be evicted from local caches. This greatly reduces network traffic, makes things efficient, and avoids transmitting sensitive metadata over the wire.

The second type of cache handles managing user sessions, offline tokens, and keeping track of login failures so that the server can detect password phishing and other attacks. The data held in these caches is temporary, in memory only, but is possibly replicated across the cluster.

This chapter discusses some configuration options for these caches for both clustered and non-clustered deployments. There are multiple different caches configured for Keycloak. There is a realm cache that holds information about secured applications, general security data, and configuration options. There is also a user cache that contains user metadata. Both caches default to a maximum of entries and use a least recently used eviction strategy. Each of them is also tied to an object revisions cache that controls eviction in a clustered setup.

This cache is created implicitly and has twice the configured size. The same applies for the authorization cache, which holds the authorization data. The keys cache holds data about external keys and does not need to have dedicated revisions cache.

Rather it has expiration explicitly declared on it, so the keys are periodically expired and forced to be periodically downloaded from external clients or identity providers. The eviction policy and max entries for these caches can be configured in the standalone. In the configuration file, there is the part with infinispan subsystem, which looks similar to this:. To limit or expand the number of allowed entries simply add or edit the object element or the expiration element of particular cache configuration.

In addition, there are also separate caches sessions , clientSessions , offlineSessions , offlineClientSessions , loginFailures and actionTokens. These caches are distributed in cluster environment and they are unbounded in size by default. If they are bounded, it would then be possible that some sessions will be lost. Expired sessions are cleared internally by Keycloak itself to avoid growing the size of these caches without limit. If you see memory issues due to a large number of sessions, you can try to:.

Increase the size of cluster more nodes in cluster means that sessions are spread more equally among nodes. Decrease the number of owners to ensure that caches are saved in one single place. See Replication and failover for more details. Decrease session timeouts, which could be done individually for each realm in Keycloak admin console.

But this could affect usability for end users. See Timeouts for more details. There is an additional replicated cache, work , which is mostly used to send messages among cluster nodes; it is also unbounded by default.

However, this cache should not cause any memory issues as entries in this cache are very short-lived. There are caches like sessions , authenticationSessions , offlineSessions , loginFailures and a few others See Eviction and expiration for more details , which are configured as distributed caches when using a clustered setup. Entries are not replicated to every single node, but instead one or more nodes is chosen as an owner of that data.

If a node is not the owner of a specific cache entry it queries the cluster to obtain it. What this means for failover is that if all the nodes that own a piece of data go down, that data is lost forever.

You were also taught how to install the Honolulu project on Windows Server With the upgrade of Windows Server security system, ie Windows Defender, the following items are available to you: -ASR or Attack Surface Reduction feature that provides malware access to Windows, detection and blocking of suspicious files and threats. SR Enables synchronous and asynchronous block synchronization of volumes between servers or clusters for each Disaster Recovery.

SR also allows the user to create Failover Stretch Clusters that exist on two different sites and all of their Nodes are Sync. Remote Desktop Session Host is one of the new features of Windows Server and allows users to use Windows-based applications or even access the Windows environment.

With this feature, users will be able to use relevant server resources and Windows-based applications and can even save files. This feature did not exist due to bugs in previous versions, but has been provided with troubleshooting in Windows Server This product offers a simple and reliable virtualization solution that can improve server productivity and reduce costs. The Windows Admin Center, formerly known as the Honolulu Project, is designed to provide a central location for server management.

At first, they may look similar, but they differ greatly in performance and features. Windows desktop is designed for the average user and has a graphical version, while Windows Server is designed as a server to run various services such as IIS Server, DNS Server and so on.

Your email address will not be published. Order Now. Michael Morgan 15 Min Read. Table of Contents. Recommended Article: Windows Server installation and configuration tutorial.

Share On:. View More Posts Michael Morgan. Eldernode Writer. We Are Waiting for your valuable comments and you can be sure that it will be answered in the shortest possible time. Post A Comment. You also have the option of changing the computer name as a part of the domain join operation. The current computer name is displayed on the main screen of SConfig. You can change the computer name by accessing the Computer Name settings page from the main menu and following the instructions.

To add other users or groups to the local Administrators group, use the Add local administrator option on the main menu. You can enable various remote management scenarios from the Configure remote management settings page:. The Microsoft Update settings are displayed in the main SConfig screen.

You can configure the server to use automatic or manual updates on the Update setting settings page. When Automatic is selected, the system will check for and install updates every day at AM.

Time is interpreted according to the effective time zone configured on the server, which may or may not be the same as the official time zone in the area. The Download only option will scan for updates, download any that are available, and then notify you in the Action center that they are ready for installation. It is the default option. When Manual updates is selected, the system will not check for updates automatically.

Action center is only available on Windows Server installed with the Server with Desktop Experience installation option, and it is only visible while you're signed in to the server. The terminology for update types but not necessarily release cadence and schedule is unified with Windows 10 and Windows Hence, Feature updates is another name for what used to be known as operating system upgrades.

Regular monthly updates, including security updates, are referred to as Quality updates. If you want to upgrade Windows Server to a newer version, you need to use traditional installation media such as an ISO. From there, you either run Setup. SConfig does not specifically facilitate these scenarios. The search returns any available updates within the category.

You will be presented with the option of installing all available updates, a specific update, or none of the available updates. From the main SConfig menu, type 6 and press Enter to enter the Install updates settings page. After you have made your selection, a list of available updates will be displayed. You can choose one the following options:. The status of Remote desktop settings is displayed in the main SConfig screen.

You can configure the following Remote desktop settings by accessing the Remote desktop settings page and following the instructions on screen:. By default, the operating system will attempt to provision a network address from a DHCP server. Alternatively, you can assign a static IPv4 address manually, and specify the subnet mask and default gateway. When configuring an IPv4 address, you can also use this settings page to configure primary and secondary DNS servers. Selecting the Date and time option from the main menu will open the Date and Time Control Panel applet.

You can use this applet to set the date and time and to modify the time zone settings.