Added: knox/trunk/books/2.1.0/config_preauth_sso_provider.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_preauth_sso_provider.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/config_preauth_sso_provider.md (added) +++ knox/trunk/books/2.1.0/config_preauth_sso_provider.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,87 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +---> + +### Preauthenticated SSO Provider ### + +A number of SSO solutions provide mechanisms for federating an authenticated identity across applications. These mechanisms are at times simple HTTP Header type tokens that can be used to propagate the identity across process boundaries. + +Knox Gateway needs a pluggable mechanism for consuming these tokens and federating the asserted identity through an interaction with the Hadoop cluster. + +**CAUTION: The use of this provider requires that proper network security and identity provider configuration and deployment does not allow requests directly to the Knox gateway. Otherwise, this provider will leave the gateway exposed to identity spoofing.** + +#### Configuration #### +##### Overview ##### +This provider was designed for use with identity solutions such as those provided by CA's SiteMinder and IBM's Tivoli Access Manager. While direct testing with these products has not been done, there has been extensive unit and functional testing that ensure that it should work with such providers. + +The HeaderPreAuth provider is configured within the topology file and has a minimal configuration that assumes SM_USER for CA SiteMinder. The following example is the bare minimum configuration for SiteMinder (with no IP address validation). + + <provider> + <role>federation</role> + <name>HeaderPreAuth</name> + <enabled>true</enabled> + </provider> + +The following table describes the configuration options for the web app security provider: + +##### Descriptions ##### + +Name | Description | Default +---------|-----------|-------- +preauth.validation.method | Optional parameter that indicates the types of trust validation to perform on incoming requests. There could be one or more comma-separated validators defined in this property. If there are multiple validators, Apache Knox validates each validator in the same sequence as it is configured. This works similar to short-circuit AND operation i.e. if any validator fails, Knox does not perform further validation and returns overall failure immediately. Possible values are: null, preauth.default.validation, preauth.ip.validation, custom validator (details described in [Custom Validator](dev-guide.html#Validator)). Failure results in a 403 forbidden HTTP status response.| null - which means 'preauth.default.validation' that is no validation will be performed and that we are assuming that the network security and external authentication system is sufficient. +preauth.ip.addresses | Optional parameter that indicates the list of trusted ip addresses. When preauth.ip.validation is indicated as the validation method this parameter must be provided to indicate the trusted ip address set. Wildcarded IPs may be used to indicate subnet level trust. ie. 127.0.* | null - which means that no validation will be performed. +preauth.custom.header | Required parameter for indicating a custom header to use for extracting the preauthenticated principal. The value extracted from this header is utilized as the PrimaryPrincipal within the established Subject. An incoming request that is missing the configured header will be refused with a 401 unauthorized HTTP status. | SM_USER for SiteMinder usecase +preauth.custom.group.header | Optional parameter for indicating a HTTP header name that contains a comma separated list of groups. These are added to the authenticated Subject as group principals. A missing group header will result in no groups being extracted from the incoming request and a log entry but processing will continue. | null - which means that there will be no group principals extracted from the request and added to the established Subject. + +NOTE: Mutual authentication can be used to establish a strong trust relationship between clients and servers while using the Preauthenticated SSO provider. See the configuration for Mutual Authentication with SSL in this document. + +##### Configuration for SiteMinder +The following is an example of a configuration of the preauthenticated SSO provider that leverages the default SM_USER header name - assuming use with CA SiteMinder. It further configures the validation based on the IP address from the incoming request. + + <provider> + <role>federation</role> + <name>HeaderPreAuth</name> + <enabled>true</enabled> + <param><name>preauth.validation.method</name><value>preauth.ip.validation</value></param> + <param><name>preauth.ip.addresses</name><value>127.0.0.2,127.0.0.1</value></param> + </provider> + +##### REST Invocation for SiteMinder +The following curl command can be used to request a directory listing from HDFS while passing in the expected header SM_USER. + + curl -k -i --header "SM_USER: guest" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS + +Omitting the `--header "SM_USER: guest"` above will result in a rejected request. + +##### Configuration for IBM Tivoli AM +As an example for configuring the preauthenticated SSO provider for another SSO provider, the following illustrates the values used for IBM's Tivoli Access Manager: + + <provider> + <role>federation</role> + <name>HeaderPreAuth</name> + <enabled>true</enabled> + <param><name>preauth.custom.header</name><value>iv_user</value></param> + <param><name>preauth.custom.group.header</name><value>iv_group</value></param> + <param><name>preauth.validation.method</name><value>preauth.ip.validation</value></param> + <param><name>preauth.ip.addresses</name><value>127.0.0.2,127.0.0.1</value></param> + </provider> + +##### REST Invocation for Tivoli AM +The following curl command can be used to request a directory listing from HDFS while passing in the expected headers of iv_user and iv_group. Note that the iv_group value in this command matches the expected ACL for webhdfs in the above topology file. Changing this from "admin" to "admin2" should result in a 401 unauthorized response. + + curl -k -i --header "iv_user: guest" --header "iv_group: admin" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS + +Omitting the `--header "iv_user: guest"` above will result in a rejected request.
Added: knox/trunk/books/2.1.0/config_sandbox.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_sandbox.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/config_sandbox.md (added) +++ knox/trunk/books/2.1.0/config_sandbox.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,51 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +---> + +## Sandbox Configuration ## + +### Sandbox 2.x Configuration ### + +TODO + +### Sandbox 1.x Configuration ### + +TODO - Update this section to use hostmap if that simplifies things. + +This version of the Apache Knox Gateway is tested against [Hortonworks Sandbox 1.x][sandbox] + +Currently there is an issue with Sandbox that prevents it from being easily used with the gateway. +In order to correct the issue, you can use the commands below to login to the Sandbox VM and modify the configuration. +This assumes that the name sandbox is setup to resolve to the Sandbox VM. +It may be necessary to use the IP address of the Sandbox VM instead. +*This is frequently but not always `192.168.56.101`.* + + ssh root@sandbox + cp /usr/lib/hadoop/conf/hdfs-site.xml /usr/lib/hadoop/conf/hdfs-site.xml.orig + sed -e s/localhost/sandbox/ /usr/lib/hadoop/conf/hdfs-site.xml.orig > /usr/lib/hadoop/conf/hdfs-site.xml + shutdown -r now + +In addition to make it very easy to follow along with the samples for the gateway you can configure your local system to resolve the address of the Sandbox by the names `vm` and `sandbox`. +The IP address that is shown below should be that of the Sandbox VM as it is known on your system. +*This will likely, but not always, be `192.168.56.101`.* + +On Linux or Macintosh systems add a line like this to the end of the file `/etc/hosts` on your local machine, *not the Sandbox VM*. +_Note: The character between the 192.168.56.101 and vm below is a *tab* character._ + + 192.168.56.101 vm sandbox + +On Windows systems a similar but different mechanism can be used. On recent +versions of windows the file that should be modified is `%systemroot%\system32\drivers\etc\hosts` Added: knox/trunk/books/2.1.0/config_sso_cookie_provider.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_sso_cookie_provider.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/config_sso_cookie_provider.md (added) +++ knox/trunk/books/2.1.0/config_sso_cookie_provider.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,122 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +---> + +### SSO Cookie Provider ### + +#### Overview #### +The SSOCookieProvider enables the federation of the authentication event that occurred through KnoxSSO. KnoxSSO is a typical SP initiated websso mechanism that sets a cookie to be presented by browsers to participating applications and cryptographically verified. + +Knox Gateway needs a pluggable mechanism for consuming these cookies and federating the KnoxSSO authentication event as an asserted identity in its interaction with the Hadoop cluster for REST API invocations. This provider is useful when an application that is integrated with KnoxSSO for authentication also consumes REST APIs through the Knox Gateway. + +Based on our understanding of the WebSSO flow it should behave like: + +* SSOCookieProvider checks for hadoop-jwt cookie and in its absence redirects to the configured SSO provider URL (knoxsso endpoint) +* The configured Provider on the KnoxSSO endpoint challenges the user in a provider specific way (presents form, redirects to SAML IdP, etc.) +* The authentication provider on KnoxSSO validates the identity of the user through credentials/tokens +* The WebSSO service exchanges the normalized Java Subject into a JWT token and sets it on the response as a cookie named `hadoop-jwt` +* The WebSSO service then redirects the user agent back to the originally requested URL - the requested Knox service subsequent invocations will find the cookie in the incoming request and not need to engage the WebSSO service again until it expires. + +#### Configuration #### +##### sandbox.json Topology Example +Configuring one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider would look something like the following: + +sso-provider.json + + { + "providers": [ + { + "role": "federation", + "name": "SSOCookieProvider", + "enabled": "true", + "params": { + "sso.authentication.provider.url": "https://localhost:9443/gateway/idp/api/v1/websso"; + } + } + ] + } + +sandbox.json + + { + "provider-config-ref": "sso-provider", + "services": [ + { + "name": "WEBHDFS", + "urls": [ + "http://localhost:50070/webhdfs"; + ] + }, + { + "name": "WEBHCAT", + "urls": [ + "http://localhost:50111/templeton"; + ] + } + ] + } + +The following table describes the configuration options for the sso cookie provider: + +##### Descriptions ##### + +Name | Description | Default +---------|-----------|--------- +sso.authentication.provider.url | Required parameter that indicates the location of the KnoxSSO endpoint and where to redirect the useragent when no SSO cookie is found in the incoming request. | N/A +sso.token.verification.pem | Optional parameter that specifies public key used to validate hadoop-jwt token. The key must be in PEM encoded format excluding the header and footer lines.| N/A +sso.expected.audiences | Optional parameter used to constrain the use of tokens on this endpoint to those that have tokens with at least one of the configured audience claims. | N/A +sso.unauthenticated.path.list | Optional - List of paths that should bypass the SSO flow. | favicon.ico + +### JWT Provider ### + +#### Overview #### +The JWT federation provider accepts JWT tokens as Bearer tokens within the Authorization header of the incoming request. Upon successfully extracting and verifying the token, the request is then processed on behalf of the user represented by the JWT token. + +This provider is closely related to the [Knox Token Service](#KnoxToken+Configuration) and is essentially the provider that is used to consume the tokens issued by the [Knox Token Service](#KnoxToken+Configuration). + +Typical deployments have the KnoxToken service defined in a topology that authenticates users based on username and password with the ShiroProvider. They also have another topology dedicated to clients that wish to use KnoxTokens to access Hadoop resources through Knox. +The following provider configuration can be used with such a topology. + + "providers": [ + { + "role": "federation", + "name": "JWTProvider", + "enabled": "true", + "params": { + "knox.token.audiences": "tokenbased" + } + } + ] + +The `knox.token.audiences` parameter above indicates that any token in an incoming request must contain an audience claim called "tokenbased". In this case, the idea is that the issuing KnoxToken service will be configured to include such an audience claim and that the resulting token is valid to use in the topology that contains configuration like above. This would generally be the name of the topology but you can standardize on anything. + +The following table describes the configuration options for the JWT federation provider: + +##### Descriptions ##### + +Name | Description | Default +---------|-----------|-------- +knox.token.audiences | Optional parameter. This parameter allows the administrator to constrain the use of tokens on this endpoint to those that have tokens with at least one of the configured audience claims. These claims have associated configuration within the KnoxToken service as well. This provides an interesting way to make sure that the token issued based on authentication to a particular LDAP server or other IdP is accepted but not others.|N/A +knox.token.exp.server-managed | Optional parameter for specifying that server-managed token state should be referenced for evaluating token validity. | false +knox.token.verification.pem | Optional parameter that specifies public key used to validate the token. The key must be in PEM encoded format excluding the header and footer lines.| N/A +knox.token.use.cookie | Optional parameter that indicates if the JWT token can be retrieved from an HTTP cookie instead of the Authorization header. If this is set to `true`, then Knox will first check if the `hadoop-jwt` cookie (the cookie name is configurable) is available in the request and, if that's the case, Knox will try to fetch a JWT from that cookie. If the cookie is not present in the request, Knox will continue its authentication flow using the Authorization header. If the cookie is there, but it holds an invalid JWT, then authentication will fail. Sample use cases and `curl` commands are available in this [GitHub Pull Request](https://github.com/apache/knox/pull/623). | false +knox.token.cookie.name | Optional parameter to use a custom cookie name in the request if `knox.token.use.cookie = true`. | hadoop-jwt +knox.token.allowed.jws.types | With [KNOX-2149](https://issues.apache.org/jira/browse/KNOX-2149), one can define their own JWKS URL which Knox can use for verification. Previous Knox implementations only supported JWTs with `"typ: JWT"` in their headers (or not type definition at all). In previous JOSE versions, there were other supported types such as `at+jwt` which Knox can support from now on. Please note, this configuration is only applied if token verification goes through the JWKS verification path. | `JWT` + + +The optional `knox.token.exp.server-managed` parameter indicates that Knox is managing the state of tokens it issues (e.g., expiration) external from the token, and this external state should be referenced when validating tokens. This parameter can be ommitted if the global default is configured in gateway-site (see [gateway.knox.token.exp.server-managed](#Gateway+Server+Configuration)), and matches the requirements of this provider. Otherwise, this provider parameter overrides the gateway configuration for the provider's deployment. + +See the [documentation for the Knox Token service](#KnoxToken+Configuration) for related details. Added: knox/trunk/books/2.1.0/config_tls_client_certificate_authentication_provider.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_tls_client_certificate_authentication_provider.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/config_tls_client_certificate_authentication_provider.md (added) +++ knox/trunk/books/2.1.0/config_tls_client_certificate_authentication_provider.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,31 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +---> + +## TLS Client Certificate Provider ## + +The TLS client certificate authentication provider enables establishing the user based on the client provided TLS certificate. The user will be the DN from the certificate. This provider requires that the gateway is configured to require client authentication with either `gateway.client.auth.wanted` or `gateway.client.auth.needed` ( #[Mutual Authentication with SSL] ). + +### Configuration ### + +```xml +<provider> + <role>authentication</role> + <name>ClientCert</name> + <enabled>true</enabled> +</provider> +``` + Added: knox/trunk/books/2.1.0/config_webappsec_provider.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_webappsec_provider.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/config_webappsec_provider.md (added) +++ knox/trunk/books/2.1.0/config_webappsec_provider.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,147 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +---> + +### Web App Security Provider ### +Knox is a Web API (REST) Gateway for Hadoop. The fact that REST interactions are HTTP based means that they are vulnerable to a number of web application security vulnerabilities. This project introduces a web application security provider for plugging in various protection filters. + +#### Configuration #### +##### Overview ##### +As with all providers in the Knox gateway, the web app security provider is configured through provider parameters. Unlike many other providers, the web app security provider may actually host multiple vulnerability/security filters. Currently, we only have implementations for CSRF, CORS and HTTP STS but others might follow, and you may be interested in creating your own. + +Because of this one-to-many provider/filter relationship, there is an extra configuration element for this provider per filter. As you can see in the sample below, the actual filter configuration is defined entirely within the parameters of the WebAppSec provider. + + <provider> + <role>webappsec</role> + <name>WebAppSec</name> + <enabled>true</enabled> + <param><name>csrf.enabled</name><value>true</value></param> + <param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param> + <param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param> + <param><name>cors.enabled</name><value>false</value></param> + <param><name>xframe.options.enabled</name><value>true</value></param> + <param><name>xss.protection.enabled</name><value>true</value></param> + <param><name>strict.transport.enabled</name><value>true</value></param> + </provider> + +#### Descriptions #### +The following tables describes the configuration options for the web app security provider: + +##### CSRF + +Cross site request forgery (CSRF) attacks attempt to force an authenticated user to +execute functionality without their knowledge. By presenting them with a link or image that when clicked invokes a request to another site with which the user may have already established an active session. + +CSRF is entirely a browser-based attack. Some background knowledge of how browsers work enables us to provide a filter that will prevent CSRF attacks. HTTP requests from a web browser performed via form, image, iframe, etc. are unable to set custom HTTP headers. The only way to create a HTTP request from a browser with a custom HTTP header is to use a technology such as JavaScript XMLHttpRequest or Flash. These technologies can set custom HTTP headers but have security policies built in to prevent web sites from sending requests to each other +unless specifically allowed by policy. + +This means that a website www.bad.com cannot send a request to http://bank.example.com with the custom header X-XSRF-Header unless they use a technology such as a XMLHttpRequest. That technology would prevent such a request from being made unless the bank.example.com domain specifically allowed it. This then results in a REST endpoint that can only be called via XMLHttpRequest (or similar technology). + +NOTE: by enabling this protection within the topology, this custom header will be required for *all* clients that interact with it - not just browsers. + +###### Config + +Name | Description | Default +---------------------|-------------|-------- +csrf.enabled | This parameter enables the CSRF protection capabilities | false +csrf.customHeader | This is an optional parameter that indicates the name of the header to be used in order to determine that the request is from a trusted source. It defaults to the header name described by the NSA in its guidelines for dealing with CSRF in REST. | X-XSRF-Header +csrf.methodsToIgnore | This is also an optional parameter that enumerates the HTTP methods to allow through without the custom HTTP header. This is useful for allowing things like GET requests from the URL bar of a browser, but it assumes that the GET request adheres to REST principals in terms of being idempotent. If this cannot be assumed then it would be wise to not include GET in the list of methods to ignore. | GET,OPTIONS,HEAD + +###### REST Invocation +The following curl command can be used to request a directory listing from HDFS while passing in the expected header X-XSRF-Header. + + curl -k -i --header "X-XSRF-Header: valid" -v -u guest:guest-password https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS + +Omitting the `--header "X-XSRF-Header: valid"` above should result in an HTTP 400 bad_request. + +Disabling the provider will then allow a request that is missing the header through. + +##### CORS + +For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts. For example, XMLHttpRequest follows the same-origin policy. So, a web application using XMLHttpRequest could only make HTTP requests to its own domain. To improve web applications, developers asked browser vendors to allow XMLHttpRequest to make cross-domain requests. + +Cross Origin Resource Sharing is a way to explicitly alter the same-origin policy for a given application or API. In order to allow for applications to make cross domain requests through Apache Knox, we need to configure the CORS filter of the WebAppSec provider. + +###### Config + +Name | Description | Default +-----------------------------|-------------|--------- +cors.enabled | Setting this parameter to true allows cross origin requests. The default of false prevents cross origin requests.|false +cors.allowGenericHttpRequests| {true\|false} defaults to true. If true, generic HTTP requests will be allowed to pass through the filter, else only valid and accepted CORS requests will be allowed (strict CORS filtering).|true +cors.allowOrigin | {"\*"\|origin-list} defaults to "\*". Whitespace-separated list of origins that the CORS filter must allow. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to \* (asterisk) any origin will be allowed.|"\*" +cors.allowSubdomains | {true\|false} defaults to false. If true, the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name / IP address and optional port number).|false +cors.supportedMethods | {method-list} defaults to GET, POST, HEAD, OPTIONS. List of the supported HTTP methods. These are advertised through the Access-Control-Allow-Methods header and must also be implemented by the actual CORS web service. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.| GET, POST, HEAD, OPTIONS +cors.supportedHeaders | {"\*"\|header-list} defaults to \*. The names of the supported author request headers. These are advertised through the Access-Control-Allow-Headers header. If the configuration property value is set to \* (asterisk) any author request header will be allowed. The CORS Filter implements this by simply echoing the requested value back to the browser.|\* +cors.exposedHeaders | {header-list} defaults to empty list. List of the response headers other than simple response headers that the browser should expose to the author of the cross-domain request through the XMLHttpRequest.getResponseHeader() method. The CORS filter supplies this information through the Access-Control-Expose-Headers header.| empty +cors.supportsCredentials | {true\|false} defaults to true. Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported. The CORS filter uses this value in constructing the Access-Control-Allow-Credentials header.|true +cors.maxAge | {int} defaults to -1 (unspecified). Indicates how long the results of a preflight request can be cached by the web browser, in seconds. If -1 unspecified. This information is passed to the browser via the Access-Control-Max-Age header.| -1 +cors.tagRequests | {true\|false} defaults to false (no tagging). Enables HTTP servlet request tagging to provide CORS information to downstream handlers (filters and/or servlets).| false + +##### X-Frame-Options + +Cross Frame Scripting and Clickjacking are attacks that can be prevented by controlling the ability for a third-party to embed an application or resource within a Frame, IFrame or Object html element. This can be done adding the X-Frame-Options HTTP header to responses. + +###### Config + +Name | Description | Default +-----------------------|-------------|--------- +xframe.options.enabled | This parameter enables the X-Frame-Options capabilities|false +xframe.options.value | This parameter specifies a particular value for the X-Frame-Options header. Most often the default value of DENY will be most appropriate. You can also use SAMEORIGIN or ALLOW-FROM uri|DENY + +##### X-XSS-Protection + +Cross-site Scripting (XSS) type attacks can be prevented by adding the X-XSS-Protection header to HTTP response. The `1; mode=block` value will force browser to stop rendering the page if XSS attack is detected. + +###### Config + +Name | Description | Default +-----------------------|-------------|--------- +xss.protection.enabled | This parameter specifies a particular value for the X-XSS-Protection header. When it is set to true, it will add `X-Xss-Protection: '1; mode=block'` header to HTTP response|false + +##### X-Content-Type-Options + +Browser MIME content type sniffing can be exploited for malicious purposes. Adding the X-Content-Type-Options HTTP header to responses directs the browser to honor the type specified in the Content-Type header, rather than trying to determine the type from the content itself. Most modern browsers support this. + +###### Config + +Name | Description | Default +-----------------------------|-------------|--------- +xcontent-type.options.enabled | This param enables the X-Content-Type-Options header inclusion|false +xcontent-type.options | This param specifies a particular value for the X-Content-Type-Options header. The default value is really the only meaningful value|nosniff + +##### HTTP Strict Transport Security + +HTTP Strict Transport Security (HSTS) is a web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking. It allows web servers to declare that web browsers (or other complying user agents) should only interact with it using secure HTTPS connections and never via the insecure HTTP protocol. + +###### Config + +Name | Description | Default +-------------------------|-------------|--------- +strict.transport.enabled | This parameter enables the HTTP Strict-Transport-Security response header|false +strict.transport | This parameter specifies a particular value for the HTTP Strict-Transport-Security header. Default value is max-age=31536000. You can also use `max-age=<expire-time>` or `max-age=<expire-time>; includeSubDomains` or `max-age=<expire-time>;preload`|max-age=31536000 + +##### Rate limiting + +Rate limiting is very useful for limiting exposure to abuse from request flooding, whether malicious, or as a result of a misconfigured client. +The configuration options are the same as Jetty's DoSFilter: https://www.eclipse.org/jetty/documentation/jetty-9/index.html#dos-filter, except that a `rate.limiting.` prefix has to be added to the configuration and when using the +`rate.limiting.delayMs` with a non-negative value (including `0`) the `gateway.servlet.async.supported` property in the `gateway-site.xml` has to be set to `true` (it is false by default). +When using the gateway with long running requests the `rate.limiting.maxRequestMs` parameter should be configured accordingly, otherwise the requests running longer then the default `30000ms` value, will be unsuccessful. + +###### Config + +Name | Description | Default +-------------------------|-------------|--------- +rate.limiting.enabled | This parameter enables the rate limiting feature|false Added: knox/trunk/books/2.1.0/dev-guide/admin-ui.md URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/dev-guide/admin-ui.md?rev=1912849&view=auto ============================================================================== --- knox/trunk/books/2.1.0/dev-guide/admin-ui.md (added) +++ knox/trunk/books/2.1.0/dev-guide/admin-ui.md Tue Oct 10 06:33:21 2023 @@ -0,0 +1,52 @@ +###Introduction + +The Admin UI is a work in progress. It has started with viewpoint of being a simple web interface for + Admin API functions but will hopefully grow into being able to also provide visibility into the gateway + in terms of logs and metrics. + +###Source and Binaries + +The Admin UI application follows the architecture of a hosted application in Knox. To that end it needs to be +packaged up in the gateway-applications module in the source tree so that in the installation it can wind up here + +`<GATEWAY_HOME>/data/applications/admin-ui` + +However since the application is built using angular and various node modules the source tree is not something +we want to place into the gateway-applications module. Instead we will place the production 'binaries' in gateway-applications + and have the source in a module called 'gateway-admin-ui'. + +To work with the angular application you need to install some prerequisite tools. + +The main tool needed is the [angular cli](https://github.com/angular/angular-cli#installation) and while installing that you + will get its dependencies which should fulfill any other requirements [Prerequisites](https://github.com/angular/angular-cli#prerequisites) + +###Manager Topology + +The Admin UI is deployed to a fixed topology. The topology file can be found under + +`<GATEWAY_HOME>/conf/topologies/manager.xml` + +The topology hosts an instance of the Admin API for the UI to use. The reason for this is that the existing Admin API needs + to have a different security model from that used by the Admin UI. The key components of this topology are: + +```xml +<provider> + <role>webappsec</role> + <name>WebAppSec</name> + <enabled>true</enabled> + <param><name>csrf.enabled</name><value>true</value></param> + <param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param> + <param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param> + <param><name>xframe-options.enabled</name><value>true</value></param> + <param><name>strict.transport.enabled</name><value>true</value></param> +</provider> +``` + +and + +```xml +<application> + <role>admin-ui</role> +</application> +``` +
