diff --git a/SUMMARY.adoc b/SUMMARY.adoc index caa976b65b..261b65eb07 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -1,6 +1,5 @@ = Summary - . link:topics/preface.adoc[Preface] . link:topics/overview.adoc[Overview] .. link:topics/overview/recommended-reading.adoc[Recommended Reading] . link:topics/installation.adoc[Installation] diff --git a/book.json b/book.json index 3be9cf7d4a..fe5534d5bf 100755 --- a/book.json +++ b/book.json @@ -13,8 +13,8 @@ "product": false, "images": "keycloak-images", "appserver": { - "name": "JBoss EAP", - "version": "6.4", + "name": "Wildfly", + "version": "10", "admindoc": { "name": "JBoss EAP Administration and Configuration Guide", "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/" @@ -57,6 +57,11 @@ "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2" } + }, + "developerguide": { + "name": "Keycloak Server Developer Guide", + "link": "https://keycloak.gitbooks.io/server-developer-guide/content/" + }, "adminguide": { "name": "Keycloak Adminstration Guide", diff --git a/topics/database/datasource.adoc b/topics/database/datasource.adoc index 4f7963b5eb..cae5634492 100755 --- a/topics/database/datasource.adoc +++ b/topics/database/datasource.adoc @@ -1,8 +1,8 @@ === Modify the {{book.project.name}} Datasource After declaring your JDBC driver, you have to modify the existing datasource configuration that {{book.project.name}} uses -to connect to the built-in embedded database. You'l need to change it to connect to your new external database. You'll do -this within the same configuration file and XML block that you registered your JDBC driver. Here's an example +to connect it to your new external database. You'll do +this within the same configuration file and XML block that you registered your JDBC driver in. Here's an example that set's up the connection to your new database: .Declare Your JDBC Drivers @@ -27,8 +27,8 @@ that set's up the connection to your new database: ---- -Search for the +datasource+ definition for +KeycloakDS+. You'll first need to specify the +connection-url+. The -documentation for your vendor's JDBC implementation will tell you the connection URL you should provide there. +Search for the +datasource+ definition for +KeycloakDS+. You'll first need to modify the +connection-url+. The +documentation for your vendor's JDBC implementation should specify the format for this connection URL value. Next define the +driver+ you will use. This is the logical name of the JDBC driver you declared in the previous section of this chapter. @@ -37,10 +37,10 @@ It is expensive to open a new connection to a database ever time you want to per 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. -Finally, or PostgreSQL at least, you need to define the database username and password that is needed to connect to the database. You +Finally, with PostgreSQL at least, you need to define the database username and password that is needed to connect to the database. You may be worried that this is in clear text in the example. There are methods to obfuscate this, but this is beyond the scope of this guide. NOTE: For more information and details features of datasources, please see the link:{{book.appserver.datasource.link}}[the datasource configuration chapter] -of the {{book.appserver.admindoc.name}}. + of the {{book.appserver.admindoc.name}}. diff --git a/topics/database/hibernate.adoc b/topics/database/hibernate.adoc index d5e0615454..22dfb5fdc1 100755 --- a/topics/database/hibernate.adoc +++ b/topics/database/hibernate.adoc @@ -1,7 +1,7 @@ === Hibernate Configuration -The Hibernate persistence API is already pre-configured out of the box. It is rare to have to modify the configuration for it. -To configure Hibernate, you need to edit the _keycloak-server.json_ file. If you are running +The Hibernate persistence API is already pre-configured out of the box and rarely needs to be changed. +The configuration for this component lies in the _keycloak-server.json_ file. If you are running in standalone mode, this file is in the _.../standalone/configuration_ directory. If you are running in domain mode this file will live in the _.../domain/servers/{server name}/configuration_ directory. diff --git a/topics/database/jdbc.adoc b/topics/database/jdbc.adoc index b264ad18f6..09c37cf2c5 100755 --- a/topics/database/jdbc.adoc +++ b/topics/database/jdbc.adoc @@ -1,13 +1,14 @@ === Package the JDBC Driver -Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module. +Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module +and install it into the server. Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on other modules. They are pretty simple to set up. Within the _.../modules/system/layers/keycloak/_ directory of your {{book.project.name}} distribution, you need to create a directory structure to hold your module definition. The convention is use the Java package name of the JDBC driver for the name of the directory structure. For PostgreSQL, create the directory _org/postgresql/main_. Copy your database -driver JAR into this directory and also create an empty _module.xml_ file. +driver JAR into this directory and create an empty _module.xml_ file within it too. .Module Directory image:../../{{book.images}}/db-module.png[] @@ -32,28 +33,20 @@ After you have done this, open up the _module.xml_ file and create the following ---- The module name should match the directory structure of your module. So, _org/postgresql_ maps to +org.postgresql+. The -+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that ++resource-root path+ attribute should specify the JAR filename of the driver. The rest are just the normal dependencies that any JDBC driver JAR would have. === Declare and Load JDBC Driver The next thing you have to do is declare your newly packaged JDBC driver into your deployment profile so that it loads and becomes -available. Where you perform this action depends on your <>. If you're +available when the server boots up. Where you perform this action depends on your <>. If you're deploying in standard mode, edit _.../standalone/configuration/standalone.xml_. If you're deploying in standard clustering mode, edit _.../standalone/configuration/standalone-ha.xml_. If you're deploying in domain mode, edit -_.../domain/configuration/domain.xml_. In domain mode, you'll need to make sure you edit the profile you are using: +_.../domain/configuration/domain.xml_. In domain mode, you'll need to make sure you edit the profile you are using: either +auth-server-standalone+ or +auth-server-clustered+ -.Domain Profile -[source,xml] ----- - - ... - ----- - Within the profile, search for the +drivers+ XML block within the +datasources+ subsystem. You should see -a pre-defined driver declared for the H2 JDBC driver. There is where you'll declare the JDBC driver for your external +a pre-defined driver declared for the H2 JDBC driver. This is where you'll declare the JDBC driver for your external database. .JDBC Drivers @@ -72,7 +65,8 @@ database. ---- Within the +drivers+ XML block you'll need to declare an additional JDBC driver. It needs to have a +name+ which -you can choose to be anything you want. You have to define the module the new JDBC driver classes are defined in. Finally +you can choose to be anything you want. You specify the +module+ attribute which points to the +module+ package you +created earlier for the driver JAR. Finally you have to specify the driver's Java class. Here's an example of installing PostgreSQL driver that lives in the module example defined earlier in this chapter. diff --git a/topics/installation.adoc b/topics/installation.adoc index a2f982f931..289e0ec6ed 100755 --- a/topics/installation.adoc +++ b/topics/installation.adoc @@ -1,5 +1,4 @@ == Installation -This chapter reviews what binaries you need to install to run the {{book.project.name}} Server on a specific machine. -It describes the directory structure and files of the distribution. Finally, it describes how to install {{book.project.name}} -on the cloud if you prefer that type of deployment. \ No newline at end of file +Installing {{book.project.name}} is as simple as downloading it and unzipping it. This chapter reviews system requirements +as well as the directory structure of the distribution. \ No newline at end of file diff --git a/topics/installation/directory-structure.adoc b/topics/installation/directory-structure.adoc index 1e640f5e51..15f902467b 100755 --- a/topics/installation/directory-structure.adoc +++ b/topics/installation/directory-structure.adoc @@ -11,20 +11,20 @@ _bin/_:: This contains various scripts to either boot the server or perform some other management action on the server. _domain/_:: - This contains configuration files and working directory when running {{book.project.name}} in <>. + This contains configuration files and working directory when running {{book.project.name}} in <>. _modules/_:: These are all the Java libraries used by the server. _providers/_:: - If you are writing extensions to keycloak, you can put your extensions here. See the link:http://not-implemented-yet[Server Developer Guide] for more information on this. + If you are writing extensions to keycloak, you can put your extensions here. See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this. _standalone/_:: - This contains configuration files and working directory when running {{book.project.name}} in <>. + This contains configuration files and working directory when running {{book.project.name}} in <>. _themes/_:: This directory contains all the html, style sheets, javascript files, and images used to display any UI screen displayed by the server. - Here you can modify an existing theme or create your own. See the link:http://not-implemented-yet[Server Developer Guide] for more information on this. + Here you can modify an existing theme or create your own. See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this. diff --git a/topics/installation/distribution-files-community.adoc b/topics/installation/distribution-files-community.adoc index 94762043f2..881b5d96e2 100755 --- a/topics/installation/distribution-files-community.adoc +++ b/topics/installation/distribution-files-community.adoc @@ -10,13 +10,13 @@ The 'keycloak-{{book.project.version}}.[zip|tar.gz]' file is the server only dis to run the Keycloak Server. To unpack this file just run your operating system's +unzip+ or +gunzip+ and +tar+ utilities. The 'keycloak-overlay-{{book.project.version}}.[zip|tar.gz]' file is a Wildfly Service Pack that allows you to install Keycloak Server on top of an existing -Wildfly or JBoss EAP distribution. We suggest that you do not use this file unless you want to install on top of a JBoss EAP distribution. We do not support +Wildfly or JBoss EAP distribution. We suggest that you do not use this distribution unless you want to install on top of the latest JBoss EAP distribution. We do not support users that want to run their applications and Keycloak on the same server instance. To install the Keycloak Service Pack, just unzip it in the root directory of your JBoss EAP distribution. -The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains a the server binaries, all documentation and all examples. It is preconfigured with both the +The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains the server binaries, all documentation and all examples. It is preconfigured with both the OIDC and SAML client application adapters and can deploy any of the distribution examples out of the box with no configuration. This distribution is only -recommended for those that want to test drive Keycloak. +recommended for those that want to test drive Keycloak. We do not support users that run the demo distribution in production. To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities. diff --git a/topics/installation/distribution-files-product.adoc b/topics/installation/distribution-files-product.adoc index c81e06ccff..d1b1aa9da6 100755 --- a/topics/installation/distribution-files-product.adoc +++ b/topics/installation/distribution-files-product.adoc @@ -1,11 +1,11 @@ === Installing Distribution Files -The Keycloak Server is contained in one distribution file: +The {{book.project.name}} Server is contained in one distribution file: * 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries -to run the Keycloak Server. +to run the {{book.project.name}} Server. To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities. diff --git a/topics/installation/system-requirements.adoc b/topics/installation/system-requirements.adoc index 49b2a3f1ef..a19a7b7306 100755 --- a/topics/installation/system-requirements.adoc +++ b/topics/installation/system-requirements.adoc @@ -7,9 +7,9 @@ These are the requirements to run the {{book.project.name}} authentication serve * zip or gzip and tar * At least 512M of RAM * At least 1G of diskspace -* Network multicast support on your machine if you want to run in a cluster out of the box. {{book.project.name}} can - be clustered without multicast, but this requires a bunch of configuration changes. Please see - the <> section of this guide for more information. * A shared external database like Postgres, MySql, Oracle, etc. {{book.project.name}} requires an external shared database if you want to run in a cluster. Please see the <> section of this guide for more information. +* Network multicast support on your machine if you want to run in a cluster. {{book.project.name}} can + be clustered without multicast, but this requires a bunch of configuration changes. Please see + the <> section of this guide for more information. diff --git a/topics/operating-mode.adoc b/topics/operating-mode.adoc index bdd87b7f10..2f0acd744f 100755 --- a/topics/operating-mode.adoc +++ b/topics/operating-mode.adoc @@ -4,8 +4,7 @@ Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode you are going to use. Will you run {{book.project.name}} within a cluster? Do you want a centralized way to manage -your server configurations? This is where deciding the operating mode comes in. This decision - effects how you configure databases, configure caching and even how you boot the server. +your server configurations? Your choice of operating mode effects how you configure databases, configure caching and even how you boot the server. TIP: The {{book.project.name}} is built on top of the {{book.appserver.name}} Application Server. This guide will only go over the basics for deployment within a specific mode. If you want specific information on this, a better place diff --git a/topics/operating-mode/domain.adoc b/topics/operating-mode/domain.adoc index 899ea07227..645986f652 100755 --- a/topics/operating-mode/domain.adoc +++ b/topics/operating-mode/domain.adoc @@ -1,6 +1,8 @@ [[_domain-mode]] === Domain Clustered Mode +Domain mode is a way to centrally manage and publish the configuration for your servers. + Running a cluster in standard mode can quickly become aggravating as the cluster grows in size. Every time you need to make a configuration change, you have perform it on each node in the cluster. Domain mode solves this problem by providing a central place to store and publish configuration. It can be quite complex to set up, but it is worth it in the end. @@ -46,11 +48,11 @@ where the domain profile and server group for the {{book.project.name}} server a .domain.xml image:../../{{book.images}}/domain-file.png[] -NOTE: Any changes you make to this file while the domain controller is running will not take effect and may even be overwritten +WARNING: Any changes you make to this file while the domain controller is running will not take effect and may even be overwritten by the server. Instead use the the command line scripting or the web console of {{book.appserver.name}}. See the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information. -Let's look at some aspects of this _domain.xml_ file. The +auth-server+ +profile+ XML block is where you are going to make the bulk of your configuration decisions. +Let's look at some aspects of this _domain.xml_ file. The +auth-serve-standalone+ and +auth-server-clustered+ +profile+ XML block is where you are going to make the bulk of your configuration decisions. You'll be configuring things here like network connections, caches, and database connections. @@ -58,12 +60,36 @@ You'll be configuring things here like network connections, caches, and database [source,xml] ---- - + + ... + + ... ---- -The +ha-sockets+ +socket-binding-group+ defines the default port mappings for various connectors that are opened with each +The +auth-server-standalone+ profile is a non-clustered setup. The +auth-server-clustered+ profile is the clustered setup. + +If you scroll down further, you'll see various +socket-binding-groups+ defined. + +.socket-binding-grous +[source,xml] +---- + + + ... + + + ... + + + + ... + + ---- + + +This config defines the default port mappings for various connectors that are opened with each {{book.project.name}} server instance. Any value that contains +${...}+ is a value that can be overriden on the command line with the +-D+ switch, i.e. @@ -79,7 +105,14 @@ binds a +socket-binding-group+ to the server group. [source,xml] ---- - + + + + + + + + @@ -97,8 +130,9 @@ _host-master.xml_ and _host-slave.xml_. _host-master.xml_ is configured to boot one {{book.project.name}} server instance. _host-slave.xml_ is configured to talk to the domain controller and boot up one {{book.project.name}} server instance. -NOTE: You should remove the load balancer server from _host-master.xml_. The load balancer included is really not that - production ready and doesn't work as smoothly as something like Apache HTTPD + mod-cluster or a hardward based one. +NOTE: The load balancer is not a required service. It exists so that you can easily test drive clustering on your development + machine. While usable in production, you have the option of replacing it if you have a different hardware or software + based load balancer you want to use. .Host Controller Config image:../../{{book.images}}/host-files.png[] @@ -152,7 +186,7 @@ image:../../{{book.images}}/domain-json-config.png[] When running the server in domain mode, there is a specific script you need to run to boot the server depending on your operating system. These scripts live in the _bin/_ directory of the server distribution. -.Standalone Boot Scripts +.Domain Boot Script image:../../{{book.images}}/domain-boot-files.png[] To boot the server: @@ -173,22 +207,25 @@ When running the boot script you will need pass in the host controlling configur +--host-config+ switch. [[_clustered-domain-example]] -==== Running the Clustered Domain Example +==== Clustered Domain Example -The example domain that comes with {{book.project.name}} was meant to run on one machine. It starts a: -* domain controller -* HTTP load balancer +You can test drive clustering using the out-of-the-box _domain.xml_ configuration. This example +domain is meant to run on one machine and boots up: + +* a domain controller +* an HTTP load balancer * 2 {{book.project.name}} server instances To simulate running a cluster on two machines, you'll run the +domain.sh+ script twice to start two separate -host controllers. The first will be the master host controller. It start a domain controller, an HTTP load balancer, and one +host controllers. The first will be the master host controller which will start a domain controller, an HTTP load balancer, and one {{book.project.name}} authentication server instance. The second will be a slave host controller that only starts up an authentication server instance. -===== Setup Secure Master Slave Connection +===== Setup Slave Connection to Domain Controller Before you can boot things up though, you have to configure the slave host controller so that it can talk securely to the domain -controller to obtain the centralized configuration. To set up a secure connection, you have to create a server admin user and a secret that +controller. If you do not do this, then the slave host will not be able to obtain the centralized configuration from the domain controller. +To set up a secure connection, you have to create a server admin user and a secret that will be shared between the master and the slave. You do this by running the +.../bin/add-user.sh+ script. When you run the script select +Management User+ and answer +yes+ when it asks you if the new user is going to be used @@ -225,7 +262,7 @@ $ add-user.sh To represent the user add the following to the server-identities definition ---- -Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file: +Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file as follows: [source,xml] ---- @@ -239,7 +276,7 @@ Now cut and paste the secret value into the _.../domain/configuration/host-slave ===== Run the Boot Scripts -Since we're simulating running on two separate machines, you'll run the boot script twice: +Since we're simulating a two node cluster on one development machine, you'll run the boot script twice: .Boot up master [source,shell] diff --git a/topics/operating-mode/standalone-ha.adoc b/topics/operating-mode/standalone-ha.adoc index 07fde37123..a57988c492 100755 --- a/topics/operating-mode/standalone-ha.adoc +++ b/topics/operating-mode/standalone-ha.adoc @@ -3,14 +3,14 @@ === Standalone Clustered Mode Standalone clustered operation mode is for when you want to run {{book.project.name}} within a cluster. This mode -requires that you have a copy of each distribution for each node you want to run in the cluster. While very easy to -deploy initially, this mode can become cumbersome if you end up having a large cluster because you will have to -modify the configuration in each node anytime you need to make a change. +requires that you have a copy of the {{book.project.name}} distribution on each machine you want to run a server instance. +This mode can be very easy to deploy initially, but can become quite cumbersome. To make a configuration change +you'll have to modify each distribution on each machine. For a large cluster this can become time consuming and error prone. ==== Standalone Clustered Configuration The distribution has a mostly pre-configured app server configuration file for running within a cluster. It has all the specific -infrasture settings you need to configure networking, databases, caches, and discovery. This file resides +infrastructure settings for networking, databases, caches, and discovery. This file resides in _.../standalone/configuration/standalone-ha.xml_. There's a few things missing from this configuration. You can't run {{book.project.name}} in a cluster without a configuring a shared database connection. You also need to deploy some type of load balancer in front of the cluster. The <> and @@ -19,11 +19,11 @@ deploy some type of load balancer in front of the cluster. The <