KEYCLOAK-8397 Remove deprecated proxy from docs
This commit is contained in:
stianst
Bruno Oliveira da Silva
parent
8cb975d273
commit
cf7e0253f3
2 changed files with 1 additions and 255 deletions
|
|
@ -45,7 +45,4 @@ include::topics/cache.adoc[]
|
||||||
include::topics/cache/eviction.adoc[]
|
include::topics/cache/eviction.adoc[]
|
||||||
include::topics/cache/replication.adoc[]
|
include::topics/cache/replication.adoc[]
|
||||||
include::topics/cache/disable.adoc[]
|
include::topics/cache/disable.adoc[]
|
||||||
include::topics/cache/clear.adoc[]
|
include::topics/cache/clear.adoc[]
|
||||||
ifeval::[{project_community}==true]
|
|
||||||
include::topics/proxy.adoc[]
|
|
||||||
endif::[]
|
|
||||||
|
|
@ -1,251 +0,0 @@
|
||||||
|
|
||||||
[[_proxy]]
|
|
||||||
== {project_name} Security Proxy
|
|
||||||
|
|
||||||
{project_name} has an HTTP(S) proxy that you can put in front of web applications and services where it is not possible to install the {project_name} adapter.
|
|
||||||
You can set up URL filters so that certain URLs are secured either by browser login and/or bearer token authentication.
|
|
||||||
You can also define role constraints for URL patterns within your applications.
|
|
||||||
|
|
||||||
=== Proxy Install and Run
|
|
||||||
|
|
||||||
Download the {project_name} proxy distribution from the {project_name} download pages and unzip it.
|
|
||||||
[source]
|
|
||||||
----
|
|
||||||
|
|
||||||
$ unzip keycloak-proxy-dist.zip
|
|
||||||
----
|
|
||||||
|
|
||||||
To run it you must have a proxy config file (which we'll discuss in a moment).
|
|
||||||
[source]
|
|
||||||
----
|
|
||||||
|
|
||||||
$ java -jar bin/launcher.jar [your-config.json]
|
|
||||||
----
|
|
||||||
|
|
||||||
If you do not specify a path to the proxy config file, the launcher will look in the current working directory for the file named `proxy.json`
|
|
||||||
|
|
||||||
=== Proxy Configuration
|
|
||||||
|
|
||||||
Here's an example configuration file.
|
|
||||||
[source,json]
|
|
||||||
----
|
|
||||||
|
|
||||||
{
|
|
||||||
"target-url": "http://localhost:8082",
|
|
||||||
"target-request-timeout": "60000",
|
|
||||||
"send-access-token": true,
|
|
||||||
"bind-address": "localhost",
|
|
||||||
"http-port": "8080",
|
|
||||||
"https-port": "8443",
|
|
||||||
"keystore": "classpath:ssl.jks",
|
|
||||||
"keystore-password": "password",
|
|
||||||
"key-password": "password",
|
|
||||||
"applications": [
|
|
||||||
{
|
|
||||||
"base-path": "/customer-portal",
|
|
||||||
"error-page": "/error.html",
|
|
||||||
"adapter-config": {
|
|
||||||
"realm": "demo",
|
|
||||||
"resource": "customer-portal",
|
|
||||||
"realm-public-key": "MIGfMA0GCSqGSIb",
|
|
||||||
"auth-server-url": "http://localhost:8081/auth",
|
|
||||||
"ssl-required" : "external",
|
|
||||||
"principal-attribute": "name",
|
|
||||||
"credentials": {
|
|
||||||
"secret": "password"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
,
|
|
||||||
"constraints": [
|
|
||||||
{
|
|
||||||
"pattern": "/users/*",
|
|
||||||
"roles-allowed": [
|
|
||||||
"user"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"pattern": "/admins/*",
|
|
||||||
"roles-allowed": [
|
|
||||||
"admin"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"pattern": "/users/permit",
|
|
||||||
"permit": true
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"pattern": "/users/deny",
|
|
||||||
"deny": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
||||||
==== Basic Config
|
|
||||||
|
|
||||||
The basic configuration options for the server are as follows:
|
|
||||||
|
|
||||||
target-url::
|
|
||||||
The URL this server is proxying. _REQUIRED_.
|
|
||||||
|
|
||||||
target-request-timeout::
|
|
||||||
The timeout (in ms) for the proxied request. _OPTIONAL_.
|
|
||||||
Default is 30000.
|
|
||||||
|
|
||||||
send-access-token::
|
|
||||||
Boolean flag.
|
|
||||||
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_.
|
|
||||||
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_.
|
|
||||||
|
|
||||||
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_.
|
|
||||||
|
|
||||||
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_.
|
|
||||||
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_.
|
|
||||||
|
|
||||||
buffers-per-region::
|
|
||||||
HTTP server socket buffers per region.
|
|
||||||
Usually the default is good enough. _OPTIONAL_.
|
|
||||||
|
|
||||||
io-threads::
|
|
||||||
Number of threads to handle IO.
|
|
||||||
Usually default is good enough.
|
|
||||||
_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_.
|
|
||||||
The default is the number of available processors * 16.
|
|
||||||
|
|
||||||
=== Application Config
|
|
||||||
|
|
||||||
Next under the `applications` array attribute, you can define one or more applications per host you are proxying.
|
|
||||||
|
|
||||||
base-path::
|
|
||||||
The base context root for the application.
|
|
||||||
Must start with '/'. _REQUIRED_.
|
|
||||||
|
|
||||||
error-page::
|
|
||||||
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_.
|
|
||||||
Same configuration as any other {project_name} adapter.
|
|
||||||
// See <<_adapter_config,Adapter Config>>
|
|
||||||
|
|
||||||
proxy-address-forwarding::
|
|
||||||
Enable usage of X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto when hosted behind another proxy/load-balancer.
|
|
||||||
|
|
||||||
==== 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.
|
|
||||||
You can deny, permit, or require authentication for a specific URL pattern.
|
|
||||||
You can specify roles allowed for that path as well.
|
|
||||||
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._
|
|
||||||
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_.
|
|
||||||
|
|
||||||
methods::
|
|
||||||
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_.
|
|
||||||
|
|
||||||
deny::
|
|
||||||
Deny all access to this URL pattern. _OPTIONAL_.
|
|
||||||
|
|
||||||
permit::
|
|
||||||
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_.
|
|
||||||
|
|
||||||
authenticate::
|
|
||||||
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 <<_identity_headers, {project_name} Identity Headers>>). This mapping is optional.
|
|
||||||
|
|
||||||
keycloak-subject::
|
|
||||||
e.g.
|
|
||||||
MYAPP_USER_ID
|
|
||||||
|
|
||||||
keycloak-username::
|
|
||||||
e.g.
|
|
||||||
MYAPP_USER_NAME
|
|
||||||
|
|
||||||
keycloak-email::
|
|
||||||
e.g.
|
|
||||||
MYAPP_USER_EMAIL
|
|
||||||
|
|
||||||
keycloak-name::
|
|
||||||
e.g.
|
|
||||||
MYAPP_USER_ID
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
KEYCLOAK_SUBJECT::
|
|
||||||
User id.
|
|
||||||
Corresponds to JWT `sub` and will be the user id {project_name} uses to store this user.
|
|
||||||
|
|
||||||
KEYCLOAK_USERNAME::
|
|
||||||
Username.
|
|
||||||
Corresponds to JWT `preferred_username`.
|
|
||||||
|
|
||||||
KEYCLOAK_EMAIL::
|
|
||||||
Email address of user if set.
|
|
||||||
|
|
||||||
KEYCLOAK_NAME::
|
|
||||||
Full name of user if set.
|
|
||||||
|
|
||||||
KEYCLOAK_ACCESS_TOKEN::
|
|
||||||
Send the access token in this header if the proxy was configured to send it.
|
|
||||||
This token can be used to make bearer token requests. Header field names can be configured using a map of `header-names` in configuration file:
|
|
||||||
+
|
|
||||||
[source,json]
|
|
||||||
----
|
|
||||||
|
|
||||||
{
|
|
||||||
"header-names" {
|
|
||||||
"keycloak-subject": "MY_SUBJECT"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
|
||||||
Loading…
Reference in a new issue