libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

Fix typos and improve readability in server installation

Browse source
This commit is contained in:
Kohei Tamura 2018-02-21 18:05:21 +09:00 committed by Stian Thorgersen
parent 28a76a04fa
commit 96f58b746d
11 changed files with 38 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
server_installation/topics/cache/eviction.adoc vendored
View file

@ -5,7 +5,7 @@ There are multiple different caches configured for {project_name}.
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 10000 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 implicitely and has twice the configured size.
This cache is created implicitly and has twice the configured size.
There are also separate caches for user sessions, offline tokens, and login failures. These caches are unbounded in size as well.
The eviction policy and max entries for these caches can be configured in the _standalone.xml_, _standalone-ha.xml_, or

2
server_installation/topics/clustering/load-balancer.adoc
View file

@ -23,7 +23,7 @@ so that the actual client IP address is forwarded to and processed by the {proje
* Configure your reverse proxy or loadbalancer to properly set `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers.
* Configure your reverse proxy or loadbalancer to preserve the original 'Host' HTTP header.
* Configure the authentication server to read the client's IP address from `X-Forwarded-For header`.
* Configure the authentication server to read the client's IP address from `X-Forwarded-For` header.
Configuring your proxy to generate the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers and preserving the
original `Host` HTTP header is beyond the scope of this guide. Take extra precautions to ensure that the

2
server_installation/topics/clustering/serialized.adoc
View file

@ -2,7 +2,7 @@
[[_clustering_db_lock]]
=== Serialized Cluster Startup
{project_name} cluster nodes are allowed to boot concurrenty.
{project_name} cluster nodes are allowed to boot concurrently.
When {project_name} 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.

2
server_installation/topics/database/unicode-considerations.adoc
View file

@ -51,7 +51,7 @@ Unicode characters are properly handled provided the database was created with U
fields in the `CREATE DATABASE` command (e.g. by using `utf8` character set as the default database character set in
MySQL 5.5. Please note that `utf8mb4` character set does not work due to different storage requirements to `utf8`
character set footnote:[Tracked as https://issues.jboss.org/browse/KEYCLOAK-3873]). Note that in this case, length
restriction to non-special fields does not apply because columns are created to accomodate given amount of characters,
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.

2
server_installation/topics/installation/directory-structure.adoc
View file

@ -26,5 +26,5 @@ _standalone/_::
This contains configuration files and working directory when running {project_name} in <<_standalone-mode,standalone mode>>.
_themes/_::
This directory contains all the html, style sheets, javascript files, and images used to display any UI screen displayed by the server.
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:{developerguide_link}[{developerguide_name}] for more information on this.

2
server_installation/topics/network/bind-address.adoc
View file

@ -40,7 +40,7 @@ interface corresponds to sockets opened up by the management layer of the {appse
which allow you to use the `jboss-cli.sh` command line interface and the {appserver_name} web console.
In looking at the `public` interface you see that it has a special string `${jboss.bind.address:127.0.0.1}`. This string
denotes a value `127.0.0.1` that can be overriden on the command line by setting a Java system property, i.e.:
denotes a value `127.0.0.1` that can be overridden on the command line by setting a Java system property, i.e.:
[source]
----

2
server_installation/topics/network/outgoing.adoc
View file

@ -132,7 +132,7 @@ The truststore is used when connecting securely to identity brokers, LDAP identi
WARNING: By default, a 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]. If there is no trust
establised, then these outgoing HTTPS requests will fail.
established, then these outgoing HTTPS requests will fail.
You can use _keytool_ to create a new truststore file or add trusted host certificates to an existing one:

2
server_installation/topics/network/ports.adoc
View file

@ -3,7 +3,7 @@
=== Socket Port Bindings
The ports opened for each socket have a pre-defined default that can be overriden at the command line or within configuration.
The ports opened for each socket have a pre-defined default that can be overridden at the command line or within configuration.
To illustrate this configuration, let's pretend you are running in <<_standalone-mode,standalone mode>> and
open up the _.../standalone/configuration/standalone.xml_. Search for `socket-binding-group`.

4
server_installation/topics/operating-mode/crossdc.adoc
View file

@ -551,7 +551,7 @@ WARNING: These steps usually need to be done for all the {project_name} caches m
**Automatically** - After some amount of failed backups, the `site2` will usually be taken offline automatically. This is done due the configuration of `take-offline` element inside the cache configuration as configured in <<jdgsetup>>.
```
```xml
<take-offline min-wait="60000" after-failures="3" />
```
@ -666,7 +666,7 @@ For the environments with slower network between data centers and probability of
* It is recommended to keep the `sessions` and `clientSessions` caches in `SYNC`. Switching them to `ASYNC` is possible only if you are sure that user requests and backchannel requests (requests from client applications to {project_name} as described in <<requestprocessing>>) will be always processed on same site. This is true, for example, if:
** You use active/passive mode as described <<modes>>.
** All your client applications are using the {project_name} link:http://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter[Javascript Adapter]. The Javascript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
** All your client applications are using the {project_name} link:http://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter[JavaScript Adapter]. The JavaScript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
** Your load balancer is able to serve the requests based on client IP address (location) and the client applications are deployed on both sites.
+
For example you have 2 sites LON and NYC. As long as your applications are deployed in both LON and NYC sites too, you can ensure that all the user requests from London users will be redirected to the applications in LON site and also to the {project_name} servers in LON site. Backchannel requests from the LON site client deployments will end on {project_name} servers in LON site too. On the other hand, for the American users, all the {project_name} requests, application requests and backchannel requests will be processed on NYC site.

8
server_installation/topics/operating-mode/domain.adoc
View file

@ -83,7 +83,7 @@ If you scroll down further, you'll see various `socket-binding-groups` defined.
<socket-binding-group name="ha-sockets" default-interface="public">
...
</socket-binding-group>
<!-- load-balancer-sockets should be removed in production systems and replaced with a better softare or hardare based one -->
<!-- load-balancer-sockets should be removed in production systems and replaced with a better software or hardware based one -->
<socket-binding-group name="load-balancer-sockets" default-interface="public">
...
</socket-binding-group>
@ -92,7 +92,7 @@ If you scroll down further, you'll see various `socket-binding-groups` defined.
This config defines the default port mappings for various connectors that are opened with each
{project_name} server instance. Any value that contains `${...}` is a value that can be overriden on the command line
{project_name} server instance. Any value that contains `${...}` is a value that can be overridden on the command line
with the `-D` switch, i.e.
----
@ -107,7 +107,7 @@ binds a `socket-binding-group` to the server group.
[source,xml]
----
<server-groups>
<!-- load-balancer-group should be removed in production systems and replaced with a better softare or hardare based one -->
<!-- load-balancer-group should be removed in production systems and replaced with a better software or hardware based one -->
<server-group name="load-balancer-group" profile="load-balancer">
<jvm name="default">
<heap size="64m" max-size="512m"/>
@ -285,4 +285,4 @@ $ domain.sh --host-config=host-master.xml
$ domain.sh --host-config=host-slave.xml
----
To try it out, open your browser and go to http://localhost:8080/auth
To try it out, open your browser and go to http://localhost:8080/auth.

47
server_installation/topics/proxy.adoc
View file

@ -87,47 +87,47 @@ Here's an example configuration file.
The basic configuration options for the server are as follows:
target-url::
The URL this server is proxying _REQUIRED._.
The URL this server is proxying. _REQUIRED_.
send-access-token::
Boolean flag.
If true, this will send the access token via the KEYCLOAK_ACCESS_TOKEN header to the proxied server. _OPTIONAL._.
If true, this will send the access token via the KEYCLOAK_ACCESS_TOKEN header to the proxied server. _OPTIONAL_.
Default is false.
bind-address::
DNS name or IP address to bind the proxy server's sockets to. _OPTIONAL._.
DNS name or IP address to bind the proxy server's sockets to. _OPTIONAL_.
The default value is _localhost_
http-port::
Port to listen for HTTP requests.
If you do not specify this value, then the proxy will not listen for regular HTTP requests. _OPTIONAL._.
If you do not specify this value, then the proxy will not listen for regular HTTP requests. _OPTIONAL_.
https-port::
Port to listen for HTTPS requests.
If you do not specify this value, then the proxy will not listen for HTTPS requests. _OPTIONAL._.
If you do not specify this value, then the proxy will not listen for HTTPS requests. _OPTIONAL_.
keystore::
Path to a Java keystore file that contains private key and certificate for the server to be able to handle HTTPS requests.
Can be a file path, or, if you prefix it with `classpath:` it will look for this file in the classpath. _OPTIONAL._.
Can be a file path, or, if you prefix it with `classpath:` it will look for this file in the classpath. _OPTIONAL_.
If you have enabled HTTPS, but have not defined a keystore, the proxy will auto-generate a self-signed certificate and use that.
buffer-size::
HTTP server socket buffer size.
Usually the default is good enough. _OPTIONAL._.
Usually the default is good enough. _OPTIONAL_.
buffers-per-region::
HTTP server socket buffers per region.
Usually the default is good enough. _OPTIONAL._.
Usually the default is good enough. _OPTIONAL_.
io-threads::
Number of threads to handle IO.
Usually default is good enough.
_OPTIONAL._.
_OPTIONAL_.
The default is the number of available processors * 2.
worker-threads::
Number of threads to handle requests.
Usually the default is good enough. _OPTIONAL._.
Usually the default is good enough. _OPTIONAL_.
The default is the number of available processors * 16.
=== Application Config
@ -136,15 +136,15 @@ Next under the `applications` array attribute, you can define one or more applic
base-path::
The base context root for the application.
Must start with '/' _REQUIRED._.
Must start with '/'. _REQUIRED_.
error-page::
If the proxy has an error, it will display the target application's error page relative URL _OPTIONAL._.
If the proxy has an error, it will display the target application's error page relative URL. _OPTIONAL_.
This is a relative path to the base-path.
In the example above it would be `/customer-portal/error.html`.
adapter-config::
_REQUIRED._.
_REQUIRED_.
Same configuration as any other {project_name} adapter.
// See <<_adapter_config,Adapter Config>>
@ -161,36 +161,36 @@ More specific constraints will take precedence over more general ones.
pattern::
URL pattern to match relative to the base-path of the application.
Must start with '/' _REQUIRED._
Must start with '/'. _REQUIRED._
You may only have one wildcard and it must come at the end of the pattern.
* Valid: [x-]`/foo/bar/*` and [x-]`/foo/*.txt`
* Not valid: [x-]`/*/foo/*`.
roles-allowed::
Array of strings of roles allowed to access this url pattern. _OPTIONAL._.
Array of strings of roles allowed to access this url pattern. _OPTIONAL_.
methods::
Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. _OPTIONAL._.
Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. _OPTIONAL_.
excluded-methods::
Array of strings of HTTP methods that will be ignored when match this pattern. _OPTIONAL._.
Array of strings of HTTP methods that will be ignored when match this pattern. _OPTIONAL_.
deny::
Deny all access to this URL pattern. _OPTIONAL._.
Deny all access to this URL pattern. _OPTIONAL_.
permit::
Permit all access without requiring authentication or a role mapping. _OPTIONAL._.
Permit all access without requiring authentication or a role mapping. _OPTIONAL_.
permit-and-inject::
Permit all access, but inject the headers, if user is already authenticated._OPTIONAL._.
Permit all access, but inject the headers, if user is already authenticated. _OPTIONAL_.
authenticate::
Require authentication for this pattern, but no role mapping. _OPTIONAL._.
Require authentication for this pattern, but no role mapping. _OPTIONAL_.
==== Header Names Config
Next under the list of applications you can override the defaults for the names of the header fields injected by the proxy (see {project_name} Identity Headers). This mapping is optional.
Next under the list of applications you can override the defaults for the names of the header fields injected by the proxy (see <<_identity_headers, {project_name} Identity Headers>>). This mapping is optional.
keycloak-subject::
e.g.
@ -212,6 +212,7 @@ keycloak-access-token::
e.g.
MYAPP_ACCESS_TOKEN
[[_identity_headers]]
=== {project_name} Identity Headers
When forwarding requests to the proxied server, {project_name} Proxy will set some additional headers with values from the OIDC identity token it received for authentication.
@ -222,7 +223,7 @@ KEYCLOAK_SUBJECT::
KEYCLOAK_USERNAME::
Username.
Corresponds to JWT `preferred_username`
Corresponds to JWT `preferred_username`.
KEYCLOAK_EMAIL::
Email address of user if set.