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/replication.adoc[]
|
||||
include::topics/cache/disable.adoc[]
|
||||
include::topics/cache/clear.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::topics/proxy.adoc[]
|
||||
endif::[]
|
||||
include::topics/cache/clear.adoc[]
|
||||
|
|
@ -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