gitlab conversion script
This commit is contained in:
Bill Burke
parent
aad8d04f0b
commit
16e4b237f6
39 changed files with 151 additions and 617 deletions
103
gitlab-conversion.py
Executable file
103
gitlab-conversion.py
Executable file
|
|
@ -0,0 +1,103 @@
|
|||
import sys, os, re, json, shutil, errno
|
||||
|
||||
def transform(root, f, targetdir):
|
||||
full = os.path.join(root, f)
|
||||
print full
|
||||
input = open(full, 'r').read()
|
||||
dir = os.path.join(targetdir, root)
|
||||
if not os.path.exists(dir):
|
||||
os.makedirs(dir)
|
||||
output = open(os.path.join(dir, f), 'w')
|
||||
for variable in re.findall(r"\{\{(.*?)\}\}", input):
|
||||
tmp = variable.replace('.', '_')
|
||||
input = input.replace(variable, tmp)
|
||||
input = input.replace('{{', '{').replace('}}','}')
|
||||
input = re.sub(r"<<fake.+#", "<<", input)
|
||||
for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
|
||||
tmp = variable.replace('.', '_')
|
||||
input = input.replace(variable, tmp)
|
||||
exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
|
||||
input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
|
||||
input = re.sub(r"image:(\.\./)*", "image:", input)
|
||||
output.write(input)
|
||||
|
||||
indir = 'topics'
|
||||
targetdir = 'target'
|
||||
if len(sys.argv) > 1:
|
||||
targetdir = sys.argv[1]
|
||||
|
||||
shutil.rmtree(os.path.join(targetdir, 'images'))
|
||||
shutil.rmtree(os.path.join(targetdir, 'keycloak-images'))
|
||||
shutil.rmtree(os.path.join(targetdir, 'rhsso-images'))
|
||||
shutil.copytree('images',os.path.join(targetdir, 'images'))
|
||||
shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images'))
|
||||
shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images'))
|
||||
|
||||
tmp = os.path.join(targetdir, 'topics')
|
||||
if not os.path.exists(tmp):
|
||||
os.makedirs(tmp)
|
||||
|
||||
# transform files
|
||||
for root, dirs, filenames in os.walk(indir):
|
||||
for f in filenames:
|
||||
transform(root,f,targetdir)
|
||||
|
||||
# Create master.doc includes
|
||||
input = open('SUMMARY.adoc', 'r').read()
|
||||
output = open(os.path.join(targetdir, 'master.adoc'), 'w')
|
||||
|
||||
output.write("""
|
||||
:toc:
|
||||
:toclevels: 3
|
||||
:numbered:
|
||||
|
||||
include::document-attributes.adoc[]
|
||||
""")
|
||||
|
||||
input = re.sub(r"[ ]*\.+\s*link:(.*)\[(.*)\]", "include::\g<1>[]", input)
|
||||
for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
|
||||
tmp = variable.replace('.', '_')
|
||||
input = input.replace(variable, tmp)
|
||||
exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
|
||||
input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
|
||||
output.write(input)
|
||||
|
||||
# parse book.json file and create document attributes
|
||||
with open('book.json') as data_file:
|
||||
data = json.load(data_file)
|
||||
|
||||
variables = data['variables']
|
||||
|
||||
def makeAttributes(variables, variable, list):
|
||||
for i in variables.keys():
|
||||
if variable is None:
|
||||
tmp = i
|
||||
else:
|
||||
tmp = variable + '_' + i
|
||||
if isinstance(variables[i],dict):
|
||||
makeAttributes(variables[i], tmp, list)
|
||||
elif isinstance(variables[i],bool):
|
||||
boolval = 'false'
|
||||
if variables[i]:
|
||||
boolval = 'true'
|
||||
list.append({tmp: boolval})
|
||||
else:
|
||||
list.append({tmp: str(variables[i])})
|
||||
|
||||
|
||||
attributeList = []
|
||||
makeAttributes(variables, None, attributeList)
|
||||
|
||||
output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w')
|
||||
for attribute in attributeList:
|
||||
for k in attribute.keys():
|
||||
output.write(':book_' + k + ": " + attribute[k] + "\n")
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
== Server Cache Configuration
|
||||
|
||||
{{book.project.name}} has two types of caches. One type of cache sits in front of the database to decrease load on the DB
|
||||
|
|
|
|||
1
topics/cache/clear.adoc
vendored
1
topics/cache/clear.adoc
vendored
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Clearing Caches at Runtime
|
||||
|
||||
To clear the realm or user cache, go to the {{book.project.name}} admin console Realm Settings->Cache Config page.
|
||||
|
|
|
|||
1
topics/cache/disable.adoc
vendored
1
topics/cache/disable.adoc
vendored
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Disabling Caching
|
||||
|
||||
To disable the realm or user cache, you must edit the `keycloak-server.json` file in your distribution. Where
|
||||
|
|
|
|||
1
topics/cache/eviction.adoc
vendored
1
topics/cache/eviction.adoc
vendored
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Eviction and Expiration
|
||||
|
||||
There are multiple different caches configured for {{book.project.name}}.
|
||||
|
|
|
|||
1
topics/cache/replication.adoc
vendored
1
topics/cache/replication.adoc
vendored
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Replication and Failover
|
||||
|
||||
The `sessions`, `offlineSessions` and `loginFailures` caches are the only caches that may perform replication. Entries are
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_clustering]]
|
||||
== Clustering
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Booting the Cluster
|
||||
|
||||
Booting {{book.project.name}} in a cluster depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Clustering Example
|
||||
|
||||
{{book.project.name}} does come with an out of the box clustering demo that leverages domain mode. Review the
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Setting Up a Load Balancer
|
||||
|
||||
This section only covers configuring the built in load balancer that is discussed in the
|
||||
|
|
@ -59,7 +60,7 @@ binding needs to point to the host and port of the new host.
|
|||
</socket-binding-group>
|
||||
----
|
||||
|
||||
=== Master Bind Addresses
|
||||
==== Master Bind Addresses
|
||||
|
||||
Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host. Either
|
||||
edit the _domain.xml_ file as discussed in the <<fake/../../network/bind-address.adoc#_bind-address, Bind Addresses>> chapter
|
||||
|
|
@ -70,7 +71,7 @@ or specify these bind addresses on the command line as follows:
|
|||
$ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2
|
||||
----
|
||||
|
||||
=== Host Slave Bind Addresses
|
||||
==== Host Slave Bind Addresses
|
||||
|
||||
Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`). Either edit the
|
||||
_host-slave.xml_ file or specify them on the command line as follows:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Multicast Network Setup
|
||||
|
||||
Out of the box clustering support has a need to for IP Multicast. Multicast is a network broadcast protocol. This protocol
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Recommended Network Architecture
|
||||
|
||||
The recommended network architecture for deploying {{book.project.name}} is to set up an HTTP/HTTPS load balancer on
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_clustering_db_lock]]
|
||||
=== Serialized Cluster Startup
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Troubleshooting
|
||||
|
||||
Note that when you run cluster, you should see message similar to this in the log of both cluster nodes:
|
||||
|
|
@ -16,3 +17,6 @@ Default values are UDP port 55200 and multicast port 45688 with multicast addres
|
|||
Note that you may need more ports opened if you want to enable additional features like diagnostics for your JGroups stack.
|
||||
{{book.project.name}} delegates most of the clustering work to Infinispan/JGroups.
|
||||
Please consult the link:{{book.appserver.jgroups.link}}[JGroups] chapter of the {{book.appserver.jgroups.name}}.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== RDBMS Setup Checklist
|
||||
|
||||
These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Modify the {{book.project.name}} Datasource
|
||||
|
||||
After declaring your JDBC driver, you have to modify the existing datasource configuration that {{book.project.name}} uses
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Hibernate Configuration
|
||||
|
||||
The Hibernate persistence API is already pre-configured out of the box and rarely needs to be changed.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== 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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
== Installation
|
||||
|
||||
Installing {{book.project.name}} is as simple as downloading it and unzipping it. This chapter reviews system requirements
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Distribution Directory Structure
|
||||
|
||||
This chapter walks you through the directory structure of the server distribution.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Installing Distribution Files
|
||||
|
||||
The Keycloak Server has three downloadable distributions:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Installing Distribution Files
|
||||
|
||||
The {{book.project.name}} Server is contained in one distribution file:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== System Requirements
|
||||
|
||||
These are the requirements to run the {{book.project.name}} authentication server:
|
||||
|
|
|
|||
|
|
@ -7,7 +7,8 @@ shown how to edit the _standalone.xml_ or _domain.xml_ directly. This must be d
|
|||
Additionally, you may be shown how to apply config changes on a running server using the app server's command line interface ({{books.appserver.name}} CLI). This chapter discusses
|
||||
how you will do this.
|
||||
|
||||
=== Start the {{books.appserver.name}} CLI
|
||||
|
||||
=== Start the {{book.appserver.name}} CLI
|
||||
|
||||
To start the {{books.appserver.name}} CLI, you need to run the `jboss-cli` script.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_mongo]]
|
||||
|
||||
== Mongo DB Setup
|
||||
|
|
@ -94,6 +95,6 @@ Therefore, a configuration like the following
|
|||
----
|
||||
will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
|
||||
|
||||
==== MongoDB Replica Sets
|
||||
=== MongoDB Replica Sets
|
||||
|
||||
In order to use a mongo replica set for Keycloak, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_network]]
|
||||
|
||||
== Network Setup
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_bind-address]]
|
||||
|
||||
=== Bind Addresses
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Setting up HTTPS/SSL
|
||||
|
||||
WARNING: {{book.project.name}} is not set up by default to handle SSL/HTTPS.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Outgoing HTTP Requests
|
||||
|
||||
The {{book.project.name}} server often needs to make non-browser HTTP requests to the applications and services it secures.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_ports]]
|
||||
|
||||
=== Socket Port Bindings
|
||||
|
|
|
|||
|
|
@ -1,610 +0,0 @@
|
|||
[[_server_installation]]
|
||||
|
||||
= Installation and Configuration of Keycloak Server
|
||||
|
||||
== Installation
|
||||
|
||||
Keycloak Server has three downloadable distributions.
|
||||
To run the Keycloak server you need to have Java 8 already installed.
|
||||
|
||||
* keycloak-.[zip|tar.gz]
|
||||
* keycloak-overlay-.[zip|tar.gz]
|
||||
* keycloak-demo-.[zip|tar.gz]
|
||||
|
||||
[[_server_install]]
|
||||
=== Install Standalone Server
|
||||
|
||||
For production and for non-JavaEE developers we recommend using the standalone Keycloak server.
|
||||
All you need to do is to download `keycloak-.zip` or `keycloak-.tar.gz`, unpackage and start to have a Keycloak server up and running.
|
||||
|
||||
To install first download either the zip or tar.gz and extract.
|
||||
Then start by running either:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.sh
|
||||
----
|
||||
or:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.bat
|
||||
----
|
||||
|
||||
[[_overlay_install]]
|
||||
=== Install on existing WildFly or JBoss EAP
|
||||
|
||||
Keycloak can be installed into an existing installations of WildFly or JBoss EAP . To do this download `keycloak-overlay-.zip` or `keycloak-overlay-.tar.gz`.
|
||||
Once downloaded extract into the root directory of your installation.
|
||||
|
||||
To add Keycloak to existing standalone.xml server config run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/jboss-cli.sh --file=bin/keycloak-install.cli
|
||||
----
|
||||
To add Keycloak to existing standalone-ha.xml server config run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/jboss-cli.sh --file=bin/keycloak-install-ha.cli
|
||||
----
|
||||
If you want to add Keycloak to a different server config edit `keycloak-install.cli` or `keycloak-install-ha.cli` and change the name of the server config.
|
||||
|
||||
=== Install Development Bundle
|
||||
|
||||
The demo bundle contains everything you need to get started with Keycloak including documentation and examples.
|
||||
To install it first download `keycloak-demo-.zip` or `keycloak-demo-.tar.gz`.
|
||||
Once downloaded extract it inside `keycloak-demo-` you'll find `keycloak` which contains a full WildFly server with Keycloak Server and Adapters included.
|
||||
You'll also find `docs` and `examples` which contains everything you need to get started developing applications that use Keycloak.
|
||||
|
||||
To start WildFly with Keycloak run:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.sh
|
||||
----
|
||||
or:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.bat
|
||||
----
|
||||
|
||||
== Configuring the Server
|
||||
|
||||
Although the Keycloak Server is designed to run out of the box, there's some things you'll need to configure before you go into production.
|
||||
Specifically:
|
||||
|
||||
* Configuring Keycloak to use a production database
|
||||
* Setting up SSL/HTTPS
|
||||
* Enforcing HTTPS connections
|
||||
|
||||
=== Admin User
|
||||
|
||||
To access the admin console to configure Keycloak you need an account to login.
|
||||
There is no built in user, instead you have to first create an admin account.
|
||||
This can done either by opening http://localhost:8080/auth (creating a user through the browser can only be done through localhost) or you can use the add-user script from the command-line.
|
||||
|
||||
The `add-user` script creates a temporary file with the details of the user, which are imported at startup.
|
||||
To add a user with this script run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/add-user.[sh|bat] -r master -u <username> -p <password>
|
||||
----
|
||||
Then restart the server.
|
||||
For `keycloak-overlay`, please make sure to use:
|
||||
|
||||
[source]
|
||||
----
|
||||
bin/add-user-keycloak.[sh|bat] -r master -u <username> -p <password>
|
||||
----
|
||||
|
||||
=== Relational Database Configuration
|
||||
|
||||
You might want to use a better relational database for Keycloak like PostgreSQL or MySQL.
|
||||
You might also want to tweak the configuration settings of the datasource.
|
||||
Please see the https://docs.jboss.org/author/display/WFLY8/DataSource+configuration[Wildfly] documentation on how to do this.
|
||||
|
||||
Keycloak runs on a Hibernate/JPA backend which is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default the setting is like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
"connectionsJpa": {
|
||||
"default": {
|
||||
"dataSource": "java:jboss/datasources/KeycloakDS",
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
},
|
||||
----
|
||||
Possible configuration options are:
|
||||
|
||||
dataSource::
|
||||
JNDI name of the dataSource
|
||||
|
||||
jta::
|
||||
boolean property to specify if datasource is JTA capable
|
||||
|
||||
driverDialect::
|
||||
Value of Hibernate dialect.
|
||||
In most cases you don't need to specify this property as dialect will be autodetected by Hibernate.
|
||||
|
||||
databaseSchema::
|
||||
Specify if schema should be updated or validated.
|
||||
Valid values are "update" and "validate" ("update is default).
|
||||
|
||||
showSql::
|
||||
Specify whether Hibernate should show all SQL commands in the console (false by default)
|
||||
|
||||
formatSql::
|
||||
Specify whether Hibernate should format SQL commands (true by default)
|
||||
|
||||
globalStatsInterval::
|
||||
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.
|
||||
|
||||
schema::
|
||||
Specify the database schema to use
|
||||
|
||||
===== Tested databases
|
||||
|
||||
Here is list of RDBMS databases and corresponding JDBC drivers, which were tested with Keycloak.
|
||||
Note that Hibernate dialect is usually set automatically according to your database, but you have possibility to override if default dialect doesn't work correctly.
|
||||
You can setup dialect by adding property `driverDialect` to the `keycloak-server.json` into `connectionsJpa` section (see above).
|
||||
|
||||
.Tested databases
|
||||
[cols="1,1,1", frame="all", options="header"]
|
||||
|===
|
||||
| Database
|
||||
| JDBC driver
|
||||
| Hibernate Dialect
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|===
|
||||
|
||||
=== MongoDB based model
|
||||
|
||||
Keycloak provides http://www.mongodb.com[MongoDB] based model implementation, which means that your identity data will be saved in MongoDB instead of traditional RDBMS.
|
||||
To configure Keycloak to use Mongo open `standalone/configuration/keycloak-server.json` in your favourite editor, then change:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"eventsStore": {
|
||||
"provider": "jpa",
|
||||
"jpa": {
|
||||
"exclude-events": [ "REFRESH_TOKEN" ]
|
||||
}
|
||||
},
|
||||
|
||||
"realm": {
|
||||
"provider": "jpa"
|
||||
},
|
||||
|
||||
"user": {
|
||||
"provider": "${keycloak.user.provider:jpa}"
|
||||
},
|
||||
----
|
||||
to:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"eventsStore": {
|
||||
"provider": "mongo",
|
||||
"mongo": {
|
||||
"exclude-events": [ "REFRESH_TOKEN" ]
|
||||
}
|
||||
},
|
||||
|
||||
"realm": {
|
||||
"provider": "mongo"
|
||||
},
|
||||
|
||||
"user": {
|
||||
"provider": "mongo"
|
||||
},
|
||||
----
|
||||
And at the end of the file add the snippet like this where you can configure details about your Mongo database:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"connectionsMongo": {
|
||||
"default": {
|
||||
"host": "127.0.0.1",
|
||||
"port": "27017",
|
||||
"db": "keycloak",
|
||||
"connectionsPerHost": 100,
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
}
|
||||
----
|
||||
All configuration options are optional.
|
||||
Default values for host and port are localhost and 27017.
|
||||
Default name of database is `keycloak` . You can also specify properties `user` and `password` if you want authenticate against your MongoDB.
|
||||
If user and password are not specified, Keycloak will connect unauthenticated to your MongoDB.
|
||||
|
||||
Finally there is set of optional configuration options, which can be used to specify connection-pooling capabilities of Mongo client.
|
||||
Supported int options are: `connectionsPerHost`, `threadsAllowedToBlockForConnectionMultiplier`, `maxWaitTime`, `connectTimeout` `socketTimeout`.
|
||||
Supported boolean options are: `socketKeepAlive`, `autoConnectRetry`.
|
||||
Supported long option is `maxAutoConnectRetryTime`.
|
||||
See http://api.mongodb.org/java/2.11.4/com/mongodb/MongoClientOptions.html[Mongo documentation] for details about those options and their default values.
|
||||
|
||||
Alternatively, you can configure MongoDB using a MongoDB http://docs.mongodb.org/manual/reference/connection-string/[connection URI].
|
||||
In this case, you define all information concerning the connection and authentication within the URI, as described in the MongoDB documentation.
|
||||
Please note that the database specified within the URI is only used for authentication.
|
||||
To change the database used by keycloak you have to set `db` property as before.
|
||||
Therefore, a configuration like the following
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"connectionsMongo": {
|
||||
"default": {
|
||||
"uri": "mongodb://user:password@127.0.0.1/authentication",
|
||||
"db": "keycloak"
|
||||
}
|
||||
}
|
||||
----
|
||||
will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
|
||||
|
||||
==== MongoDB Replica Sets
|
||||
|
||||
In order to use a mongo replica set for Keycloak, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`.
|
||||
|
||||
=== Outgoing Server HTTP Requests
|
||||
|
||||
Keycloak server needs to invoke on remote HTTP endpoints to do things like backchannel logouts and other management functions.
|
||||
Keycloak maintains a HTTP client connection pool which has various configuration settings you can specify before boot time.
|
||||
This is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default the setting is like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"connectionsHttpClient": {
|
||||
"default": {}
|
||||
},
|
||||
----
|
||||
Possible configuration options are:
|
||||
|
||||
establish-connection-timeout-millis::
|
||||
Timeout for establishing a socket connection.
|
||||
|
||||
socket-timeout-millis::
|
||||
If an outgoing request does not receive data for this amount of time, timeout the connection.
|
||||
|
||||
connection-pool-size::
|
||||
How many connections can be in the pool (128 by default).
|
||||
|
||||
max-pooled-per-route::
|
||||
How many connections can be pooled per host (64 by default).
|
||||
|
||||
connection-ttl-millis::
|
||||
Maximum connection time to live in milliseconds.
|
||||
Not set by default.
|
||||
|
||||
max-connection-idle-time-millis::
|
||||
Maximum time the connection might stay idle in the connection pool (900 seconds by default). Will start background cleaner thread of Apache HTTP client.
|
||||
Set to -1 to disable this checking and the background thread.
|
||||
|
||||
disable-cookies::
|
||||
`true` by default.
|
||||
When set to true, this will disable any cookie caching.
|
||||
|
||||
client-keystore::
|
||||
This is the file path to a Java keystore file.
|
||||
This keystore contains client certificate for two-way SSL.
|
||||
|
||||
client-keystore-password::
|
||||
Password for the client keystore.
|
||||
This is _REQUIRED_ if `client-keystore` is set.
|
||||
|
||||
client-key-password::
|
||||
_Not supported yet, but we will support in future versions. Password for the client's key.
|
||||
This is _REQUIRED_ if `client-keystore` is set.
|
||||
|
||||
[[_truststore]]
|
||||
=== Securing Outgoing Server HTTP Requests
|
||||
|
||||
When Keycloak connects out to remote HTTP endpoints over secure https connection, it has to validate the other server's certificate in order to ensure it is connecting to a trusted server.
|
||||
That is necessary in order to prevent man-in-the-middle attacks.
|
||||
|
||||
How certificates are validated is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default truststore provider is not configured, and any https connections fall back to standard java truststore configuration as described in https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[
|
||||
Java's JSSE Reference Guide] - using `javax.net.ssl.trustStore system property`, otherwise `cacerts` file that comes with java is used.
|
||||
|
||||
Truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications.
|
||||
Some of these facilities may - in case when no trusted certificate is found in your configured truststore - fallback to using the JSSE provided truststore.
|
||||
The default JavaMail API implementation used to send out emails behaves in this way, for example.
|
||||
|
||||
You can add your truststore configuration by using the following template:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"truststore": {
|
||||
"file": {
|
||||
"file": "path to your .jks file containing public certificates",
|
||||
"password": "password",
|
||||
"hostname-verification-policy": "WILDCARD",
|
||||
"disabled": false
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Possible configuration options are:
|
||||
|
||||
file::
|
||||
The value is the file 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.
|
||||
Truststore file should only contain public certificates of your secured hosts.
|
||||
This is _REQUIRED_ if `disabled` is not true.
|
||||
|
||||
password::
|
||||
Password for the truststore.
|
||||
This is _REQUIRED_ if `disabled` is not true.
|
||||
|
||||
hostname-verification-policy::
|
||||
`WILDCARD` by default.
|
||||
For HTTPS requests, this verifies the hostname of the server's certificate.
|
||||
`ANY` means that the hostname is not verified. `WILDCARD` Allows wildcards in subdomain names i.e.
|
||||
*.foo.com. `STRICT` CN must match hostname exactly.
|
||||
|
||||
disabled::
|
||||
If true (default value), truststore configuration will be ignored, and certificate checking will fall back to JSSE configuration as described.
|
||||
If set to false, you must configure `file`, and `password` for the truststore.
|
||||
|
||||
You can use _keytool_ to create a new truststore file and add trusted host certificates to it:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer
|
||||
----
|
||||
|
||||
[[_ssl_modes]]
|
||||
=== SSL/HTTPS Requirement/Modes
|
||||
|
||||
WARNING: Keycloak is not set up by default to handle SSL/HTTPS.
|
||||
It is highly recommended that you either enable SSL on the Keycloak server itself or on a reverse proxy in front of the Keycloak server.
|
||||
|
||||
Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
|
||||
If you try to access Keycloak from a non-IP adress you will get an error.
|
||||
|
||||
Keycloak has 3 SSL/HTTPS modes which you can set up in the admin console under the Settings->Login page and the `Require SSL` select box.
|
||||
Each adapter config should mirror this server-side setting.
|
||||
See adapter config section for more details.
|
||||
|
||||
external::
|
||||
Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
|
||||
If you try to access Keycloak from a non-IP adress you will get an error.
|
||||
|
||||
none::
|
||||
Keycloak does not require SSL.
|
||||
|
||||
all::
|
||||
Keycloak requires SSL for all IP addresses.
|
||||
|
||||
=== SSL/HTTPS Setup
|
||||
|
||||
First enable SSL on Keycloak or on a reverse proxy in front of Keycloak.
|
||||
Then configure the Keycloak Server to enforce HTTPS connections.
|
||||
|
||||
==== Enable SSL on Keycloak
|
||||
|
||||
The following things need to be done
|
||||
|
||||
* keytool
|
||||
* Enable Wildfly to use this certificate and turn on SSL/HTTPS.
|
||||
|
||||
===== Creating the Certificate and Java Keystore
|
||||
|
||||
In order to allow HTTPS connections, you need to obtain a self signed or third-party signed certificate and import it into a Java keystore before you can enable HTTPS in the web container you are deploying the Keycloak Server to.
|
||||
|
||||
====== Self Signed Certificate
|
||||
|
||||
In development, you will probably not have a third party signed certificate available to test a Keycloak deployment so you'll need to generate a self-signed on.
|
||||
Generate one is very easy to do with the `keytool` utility that comes with the Java jdk.
|
||||
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
|
||||
Enter keystore password: secret
|
||||
Re-enter new password: secret
|
||||
What is your first and last name?
|
||||
[Unknown]: localhost
|
||||
What is the name of your organizational unit?
|
||||
[Unknown]: Keycloak
|
||||
What is the name of your organization?
|
||||
[Unknown]: Red Hat
|
||||
What is the name of your City or Locality?
|
||||
[Unknown]: Westford
|
||||
What is the name of your State or Province?
|
||||
[Unknown]: MA
|
||||
What is the two-letter country code for this unit?
|
||||
[Unknown]: US
|
||||
Is CN=localhost, OU=Keycloak, O=Test, L=Westford, ST=MA, C=US correct?
|
||||
[no]: yes
|
||||
----
|
||||
|
||||
You should answer `What is your first and last name ?` question with the DNS name of the machine you're installing the server on.
|
||||
For testing purposes, `localhost` should be used.
|
||||
After executing this command, the `keycloak.jks` file will be generated in the same directory as you executed the `keytool` command in.
|
||||
|
||||
If you want a third-party signed certificate, but don't have one, you can obtain one for free at http://cacert.org[cacert.org].
|
||||
You'll have to do a little set up first before doing this though.
|
||||
|
||||
The first thing to do is generate a Certificate Request:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq
|
||||
----
|
||||
|
||||
Where `yourdomain` is a DNS name for which this certificate is generated for.
|
||||
Keytool generates the request:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
-----BEGIN NEW CERTIFICATE REQUEST-----
|
||||
MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
|
||||
ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
|
||||
Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
|
||||
29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
|
||||
H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
|
||||
Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
|
||||
2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
|
||||
n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
|
||||
PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
|
||||
9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
|
||||
MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
|
||||
vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
|
||||
-----END NEW CERTIFICATE REQUEST-----
|
||||
----
|
||||
|
||||
Send this ca request to your CA.
|
||||
The CA will issue you a signed certificate and send it to you.
|
||||
Before you import your new cert, you must obtain and import the root certificate of the CA.
|
||||
You can download the cert from CA (ie.: root.crt) and import as follows:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -keystore keycloak.jks -file root.crt -alias root
|
||||
----
|
||||
|
||||
Last step is import your new CA generated certificate to your keystore:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer
|
||||
----
|
||||
|
||||
===== Installing the keystore to WildFly
|
||||
|
||||
Now that you have a Java keystore with the appropriate certificates, you need to configure your Wildfly installation to use it.
|
||||
First step is to move the keystore file to a directory you can reference in configuration.
|
||||
I like to put it in `standalone/configuration`.
|
||||
Then you need to edit `standalone/configuration/standalone.xml` to enable SSL/HTTPS.
|
||||
|
||||
To the `security-realms` element add:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<security-realm name="UndertowRealm">
|
||||
<server-identities>
|
||||
<ssl>
|
||||
<keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
|
||||
</ssl>
|
||||
</server-identities>
|
||||
</security-realm>
|
||||
----
|
||||
|
||||
Find the element `server name="default-server"` (it's a child element of `subsystem xmlns="urn:jboss:domain:undertow:1.0"`) and add:
|
||||
|
||||
[source]
|
||||
----
|
||||
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
|
||||
----
|
||||
|
||||
Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[Wildfly Undertow] documentation for more information on fine tuning the socket connections.
|
||||
|
||||
==== Enable SSL on a Reverse Proxy
|
||||
|
||||
Follow the documentation for your web server to enable SSL and configure reverse proxy for Keycloak.
|
||||
It is important that you make sure the web server sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to Keycloak.
|
||||
Next you need to enable `proxy-address-forwarding` on the Keycloak http connector.
|
||||
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.
|
||||
|
||||
===== Configure WildFly
|
||||
|
||||
. Open `standalone/configuration/standalone.xml` in your favorite editor.
|
||||
|
||||
. First add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element:
|
||||
|
||||
[source]
|
||||
----
|
||||
<subsystem xmlns="urn:jboss:domain:undertow:1.1">
|
||||
...
|
||||
<http-listener name="default" socket-binding="http"
|
||||
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
|
||||
...
|
||||
</subsystem>
|
||||
----
|
||||
|
||||
Then add a new `socket-binding` element to the `socket-binding-group` element:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<socket-binding-group name="standard-sockets" default-interface="public"
|
||||
port-offset="${jboss.socket.binding.port-offset:0}">
|
||||
...
|
||||
<socket-binding name="proxy-https" port="443"/>
|
||||
...
|
||||
</socket-binding-group>
|
||||
----
|
||||
|
||||
Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[WildFly] documentation for more information.
|
||||
|
||||
== Keycloak server in Domain Mode
|
||||
|
||||
In domain mode, you start the server with the "domain" command instead of the "standalone" command.
|
||||
In this case, the Keycloak subsystem is defined in domain/configuration/domain.xml instead of standalone/configuration.standalone.xml.
|
||||
Inside domain.xml, you will see more than one profile.
|
||||
The Keycloak subsystem is defined for all initial profiles.
|
||||
|
||||
THe server is also added to server profiles.
|
||||
By default two servers are started in the main-server-group which uses the full profile.
|
||||
|
||||
You need to make sure `domain/servers/SERVER NAME/configuration` is identical for all servers in a group.
|
||||
|
||||
To deploy custom providers and themes you should deploys these as modules and make sure the modules are available to all servers in the group.
|
||||
See <<_providers,Providers>> and <<_themes,Themes>> sections for more information on how to do this.
|
||||
|
||||
== Installing Keycloak Server as Root Context
|
||||
|
||||
The Keycloak server can be installed as the default web application.
|
||||
In doing so, the server can be referenced at `http://mydomain.com/` instead of `http://mydomain.com/auth`.
|
||||
|
||||
To do this, add the `default-web-module` attribute in the Undertow subystem in standalone.xml.
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<subsystem xmlns="urn:jboss:domain:undertow:2.0">
|
||||
<server name="default-server">
|
||||
<host name="default-host" alias="localhost" default-web-module="keycloak-server.war">
|
||||
<location name="/" handler="welcome-content"/>
|
||||
</host>
|
||||
----
|
||||
|
||||
`keycloak-server.war` is the runtime name of the Keycloak server application.
|
||||
Note that the WAR file does not exist as a file.
|
||||
If its name changes (ie. `keycloak-server.war`) in the future, find its new name from the Keycloak log entry with `runtime-name:`.
|
||||
|
||||
|
||||
|
||||
NOTE: If you have run your server before altering the root context, your database will contain references to the old /auth context. Your clients may also have incorrect references.
|
||||
To fix this on the server side, you will need to export your database to json, make corrections, and then import.
|
||||
Client-side `keycloak.json` files will need to be updated manually as well.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_openshift]]
|
||||
|
||||
== Running Keycloak Server on OpenShift
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_operating_mode]]
|
||||
|
||||
== Choosing an Operating Mode
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_domain-mode]]
|
||||
=== Domain Clustered Mode
|
||||
|
||||
|
|
@ -72,7 +73,7 @@ The `auth-server-standalone` profile is a non-clustered setup. The `auth-server
|
|||
|
||||
If you scroll down further, you'll see various `socket-binding-groups` defined.
|
||||
|
||||
.socket-binding-grous
|
||||
.socket-binding-groups
|
||||
[source,xml]
|
||||
----
|
||||
<socket-binding-groups>
|
||||
|
|
@ -86,7 +87,8 @@ If you scroll down further, you'll see various `socket-binding-groups` defined.
|
|||
<socket-binding-group name="load-balancer-sockets" default-interface="public">
|
||||
...
|
||||
</socket-binding-group>
|
||||
</socket-binding-groups>----
|
||||
</socket-binding-groups>
|
||||
----
|
||||
|
||||
|
||||
This config defines the default port mappings for various connectors that are opened with each
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_standalone-ha-mode]]
|
||||
|
||||
=== Standalone Clustered Mode
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_standalone-mode]]
|
||||
=== Standalone Mode
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
== Guide Overview
|
||||
|
||||
The purpose of this guide is to walk through the steps that need to be completed prior to booting up the
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
=== Recommended Additional External Documentation
|
||||
|
||||
{{book.project.name}} is built upon a derivative of the {{book.appserver.name}} Application Server and projects embedded
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
[[_proxy]]
|
||||
== Keycloak Security Proxy
|
||||
|
||||
|
|
@ -147,7 +148,7 @@ adapter-config::
|
|||
Same configuration as any other keycloak adapter.
|
||||
See <<_adapter_config,Adapter Config>>
|
||||
|
||||
===== Constraint Config
|
||||
==== Constraint Config
|
||||
|
||||
Next under each application you can define one or more constraints in the `constraints` array attribute.
|
||||
A constraint defines a URL pattern relative to the base-path.
|
||||
|
|
|
|||
Loading…
Reference in a new issue