You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by lm...@apache.org on 2019/07/23 21:27:16 UTC
svn commit: r1863668 [4/9] - in /knox: site/ site/books/knox-0-12-0/
site/books/knox-0-13-0/ site/books/knox-0-14-0/ site/books/knox-1-0-0/
site/books/knox-1-1-0/ site/books/knox-1-2-0/ site/books/knox-1-3-0/ trunk/
trunk/books/1.4.0/ trunk/books/1.4.0...
Added: knox/trunk/books/1.4.0/config_advanced_ldap.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_advanced_ldap.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_advanced_ldap.md (added)
+++ knox/trunk/books/1.4.0/config_advanced_ldap.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,281 @@
+### Advanced LDAP Authentication
+
+The default configuration computes the bind DN for incoming user based on userDnTemplate.
+This does not work in enterprises where users could belong to multiple branches of LDAP tree.
+You could instead enable advanced configuration that would compute bind DN of incoming user with an LDAP search.
+
+#### Problem with userDnTemplate based Authentication
+
+UserDnTemplate based authentication uses the configuration parameter `ldapRealm.userDnTemplate`.
+Typical values of userDNTemplate would look like `uid={0},ou=people,dc=hadoop,dc=apache,dc=org`.
+
+To compute bind DN of the client, we swap the place holder `{0}` with the login id provided by the client.
+For example, if the login id provided by the client is "guest',
+the computed bind DN would be `uid=guest,ou=people,dc=hadoop,dc=apache,dc=org`.
+
+This keeps configuration simple.
+
+However, this does not work if users belong to different branches of LDAP DIT.
+For example, if there are some users under `ou=people,dc=hadoop,dc=apache,dc=org`
+and some users under `ou=contractors,dc=hadoop,dc=apache,dc=org`,
+we cannot come up with userDnTemplate that would work for all the users.
+
+#### Using advanced LDAP Authentication
+
+With advanced LDAP authentication, we find the bind DN of the user by searching the LDAP directory
+instead of interpolating the bind DN from userDNTemplate.
+
+
+#### Example search filter to find the client bind DN
+
+Assuming
+
+* ldapRealm.userSearchAttributeName=uid
+* ldapRealm.userObjectClass=person
+* client specified login id = "guest"
+
+The LDAP Filter for doing a search to find the bind DN would be
+
+ (&(uid=guest)(objectclass=person))
+
+This could find the bind DN to be
+
+ uid=guest,ou=people,dc=hadoop,dc=apache,dc=org
+
+Please note that the `userSearchAttributeName` need not be part of bindDN.
+
+For example, you could use
+
+* ldapRealm.userSearchAttributeName=email
+* ldapRealm.userObjectClass=person
+* client specified login id = "bill.clinton@gmail.com"
+
+The LDAP Filter for doing a search to find the bind DN would be
+
+ (&(email=bill.clinton@gmail.com)(objectclass=person))
+
+This could find the bind DN to be
+
+ uid=billc,ou=contractors,dc=hadoop,dc=apache,dc=org
+
+#### Advanced LDAP configuration parameters
+The table below provides a brief description and sample of the available advanced bind and search configuration parameters.
+
+| Parameter | Description | Default | Sample |
+|-----------------------------|----------------------------------------------------------------|---------|--------------------------------------------------------------------|
+| principalRegex | Parses the principal for insertion into templates via regex. | (.*) | (.\*?)\\\\(.\*) _(e.g. match US\tom: {0}=US\tom, {1}=US, {2}=tom)_ |
+| userDnTemplate | Direct user bind DN template. | {0} | cn={2},dc={1},dc=qa,dc=company,dc=com |
+| userSearchBase | Search based template. Used with config below. | none | dc={1},dc=qa,dc=company,dc=com |
+| userSearchAttributeName | Attribute name for simplified search filter. | none | sAMAccountName |
+| userSearchAttributeTemplate | Attribute template for simplified search filter. | {0} | {2} |
+| userSearchFilter | Advanced search filter template. Note \& is \& in XML. | none | (\&(objectclass=person)(sAMAccountName={2})) |
+| userSearchScope | Search scope: subtree, onelevel, object. | subtree | onelevel |
+
+#### Advanced LDAP configuration combinations
+There are also only certain valid combinations of advanced LDAP configuration parameters.
+
+* User DN Template
+ * userDnTemplate (Required)
+ * principalRegex (Optional)
+* User Search by Attribute
+ * userSearchBase (Required)
+ * userAttributeName (Required)
+ * userAttributeTemplate (Optional)
+ * userSearchScope (Optional)
+ * principalRegex (Optional)
+* User Search by Filter
+ * userSearchBase (Required)
+ * userSearchFilter (Required)
+ * userSearchScope (Optional)
+ * principalRegex (Optional)
+
+#### Advanced LDAP configuration precedence
+The presence of multiple configuration combinations should be avoided.
+The rules below clarify which combinations take precedence when present.
+
+1. userSearchBase takes precedence over userDnTemplate
+2. userSearchFilter takes precedence over userSearchAttributeName
+
+#### Example provider configuration to use advanced LDAP authentication
+
+The example configuration appears verbose due to the presence of liberal comments
+and illustration of optional parameters and default values.
+The configuration that you would use could be much shorter if you rely on default values.
+
+ <provider>
+
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.knox.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+
+ <!-- update the value based on your ldap directory protocol, host and port -->
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://hdp.example.com:389</value>
+ </param>
+
+ <!-- optional, default value: simple
+ Update the value based on mechanisms supported by your ldap directory -->
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+
+ <!-- optional, default value: {0}
+ update the value based on your ldap DIT(directory information tree).
+ ignored if value is defined for main.ldapRealm.userSearchAttributeName -->
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- optional, default value: null
+ If you specify a value for this attribute, useDnTemplate
+ specified above would be ignored and user bind DN would be computed using
+ ldap search
+ update the value based on your ldap DIT(directory information layout)
+ value of search attribute should identity the user uniquely -->
+ <param>
+ <name>main.ldapRealm.userSearchAttributeName</name>
+ <value>uid</value>
+ </param>
+
+ <!-- optional, default value: false
+ If the value is true, groups in which user is a member are looked up
+ from LDAP and made available for service level authorization checks -->
+ <param>
+ <name>main.ldapRealm.authorizationEnabled</name>
+ <value>true</value>
+ </param>
+
+ <!-- bind DN used to search for groups and user bind DN.
+ Required if a value is defined for main.ldapRealm.userSearchAttributeName
+ or if the value of main.ldapRealm.authorizationEnabled is true -->
+ <param>
+ <name>main.ldapRealm.contextFactory.systemUsername</name>
+ <value>uid=guest,ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- password for systemUserName.
+ Required if a value is defined for main.ldapRealm.userSearchAttributeName
+ or if the value of main.ldapRealm.authorizationEnabled is true -->
+ <param>
+ <name>main.ldapRealm.contextFactory.systemPassword</name>
+ <value>${ALIAS=ldcSystemPassword}</value>
+ </param>
+
+ <!-- optional, default value: simple
+ Update the value based on mechanisms supported by your ldap directory -->
+ <param>
+ <name>main.ldapRealm.contextFactory.systemAuthenticationMechanism</name>
+ <value>simple</value>
+ </param>
+
+ <!-- optional, default value: person
+ Objectclass to identify user entries in ldap, used to build search
+ filter to search for user bind DN -->
+ <param>
+ <name>main.ldapRealm.userObjectClass</name>
+ <value>person</value>
+ </param>
+
+ <!-- search base used to search for user bind DN and groups -->
+ <param>
+ <name>main.ldapRealm.searchBase</name>
+ <value>dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- search base used to search for user bind DN.
+ Defaults to the value of main.ldapRealm.searchBase.
+ If main.ldapRealm.userSearchAttributeName is defined,
+ value for main.ldapRealm.searchBase or main.ldapRealm.userSearchBase
+ should be defined -->
+ <param>
+ <name>main.ldapRealm.userSearchBase</name>
+ <value>dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- search base used to search for groups.
+ Defaults to the value of main.ldapRealm.searchBase.
+ If value of main.ldapRealm.authorizationEnabled is true,
+ value for main.ldapRealm.searchBase or main.ldapRealm.groupSearchBase should be defined -->
+ <param>
+ <name>main.ldapRealm.groupSearchBase</name>
+ <value>dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- optional, default value: groupOfNames
+ Objectclass to identify group entries in ldap, used to build search
+ filter to search for group entries -->
+ <param>
+ <name>main.ldapRealm.groupObjectClass</name>
+ <value>groupOfNames</value>
+ </param>
+
+ <!-- optional, default value: member
+ If value is memberUrl, we treat found groups as dynamic groups -->
+ <param>
+ <name>main.ldapRealm.memberAttribute</name>
+ <value>member</value>
+ </param>
+
+ <!-- optional, default value: uid={0}
+ Ignored if value is defined for main.ldapRealm.userSearchAttributeName -->
+ <param>
+ <name>main.ldapRealm.memberAttributeValueTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+
+ <!-- optional, default value: cn -->
+ <param>
+ <name>main.ldapRealm.groupIdAttribute</name>
+ <value>cn</value>
+ </param>
+
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+
+ <!-- optional, default value: 30min -->
+ <param>
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+
+ </provider>
+
+#### Special note on parameter main.ldapRealm.contextFactory.systemPassword
+
+The value for this could have one of the following 2 formats
+
+* plaintextpassword
+* ${ALIAS=ldcSystemPassword}
+
+The first format specifies the password in plain text in the provider configuration.
+Use of this format should be limited for testing and troubleshooting.
+
+We strongly recommend using the second format `${ALIAS=ldcSystemPassword}` in production.
+This format uses an alias for the password stored in credential store.
+In the example `${ALIAS=ldcSystemPassword}`,
+ldcSystemPassword is the alias for the password stored in credential store.
+
+Assuming the plain text password is "hadoop", and your topology file name is "hdp.xml",
+you would use following command to create the right password alias in credential store.
+
+ {GATEWAY_HOME}/bin/knoxcli.sh create-alias ldcSystemPassword --cluster hdp --value hadoop
Added: knox/trunk/books/1.4.0/config_audit.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_audit.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_audit.md (added)
+++ knox/trunk/books/1.4.0/config_audit.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,72 @@
+<!---
+ 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
+
+ http://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.
+--->
+
+### Audit ###
+
+The Audit facility within the Knox Gateway introduces functionality for tracking actions that are executed by Knox per user's request or that are produced by Knox internal events like topology deploy, etc.
+The Knox Audit module is based on [Apache log4j](http://logging.apache.org/log4j/1.2/).
+
+#### Configuration needed ####
+
+Out of the box, the Knox Gateway includes preconfigured auditing capabilities. To change its configuration please read the following sections.
+
+#### Where audit logs go ####
+
+The Audit module is preconfigured to write audit records to the log file `{GATEWAY_HOME}/log/gateway-audit.log`.
+
+This behavior can be changed in the `{GATEWAY_HOME}/conf/gateway-log4j.properties` file. `app.audit.file` can be used to change the location. The `log4j.appender.auditfile.*` properties can be used for further customization. For detailed information read the [Apache log4j](http://logging.apache.org/log4j/1.2/) documentation.
+
+#### Audit format ####
+
+Out of the box, the audit record format is defined by `org.apache.knox.gateway.audit.log4j.layout.AuditLayout`.
+Its structure is as follows:
+
+ EVENT_PUBLISHING_TIME ROOT_REQUEST_ID|PARENT_REQUEST_ID|REQUEST_ID|LOGGER_NAME|TARGET_SERVICE_NAME|USER_NAME|PROXY_USER_NAME|SYSTEM_USER_NAME|ACTION|RESOURCE_TYPE|RESOURCE_NAME|OUTCOME|LOGGING_MESSAGE
+
+The audit record format can be changed by setting `log4j.appender.auditfile.layout` property in `{GATEWAY_HOME}/conf/gateway-log4j.properties` to another class that extends `org.apache.log4j.Layout` or its subclasses.
+
+For detailed information read [Apache log4j](http://logging.apache.org/log4j/1.2/).
+
+##### How to interpret audit log #####
+
+Component | Description
+---------|-----------
+EVENT_PUBLISHING_TIME | Time when audit record was published.
+ROOT_REQUEST_ID | The root request ID if this is a sub-request. Currently it is empty.
+PARENT_REQUEST_ID | The parent request ID if this is a sub-request. Currently it is empty.
+REQUEST_ID | A unique value representing the current, active request. If the current request id value is different from the current parent request id value then the current request id value is moved to the parent request id before it is replaced by the provided request id. If the root request id is not set it will be set with the first non-null value of either the parent request id or the passed request id.
+LOGGER_NAME | The name of the logger
+TARGET_SERVICE_NAME | Name of Hadoop service. Can be empty if audit record is not linked to any Hadoop service, for example, audit record for topology deployment.
+USER_NAME | Name of user that initiated session with Knox
+PROXY_USER_NAME | Mapped user name. For detailed information read #[Identity Assertion].
+SYSTEM_USER_NAME | Currently is empty.
+ACTION | Type of action that was executed. Following actions are defined: authentication, authorization, redeploy, deploy, undeploy, identity-mapping, dispatch, access.
+RESOURCE_TYPE | Type of resource for which action was executed. Following resource types are defined: uri, topology, principal.
+RESOURCE_NAME | Name of resource. For resource of type topology it is name of topology. For resource of type uri it is inbound or dispatch request path. For resource of type principal it is a name of mapped user.
+OUTCOME | Action result type. Following outcomes are defined: success, failure, unavailable.
+LOGGING_MESSAGE | Logging message. Contains additional tracking information.
+
+#### Audit log rotation ####
+
+Audit logging is preconfigured with `org.apache.log4j.DailyRollingFileAppender`.
+[Apache log4j](http://logging.apache.org/log4j/1.2/) contains information about other Appenders.
+
+#### How to change the audit level or disable it ####
+
+All audit messages are logged at `INFO` level and this behavior can't be changed.
+
+Disabling auditing can be done by decreasing the log level for the Audit appender or setting it to `OFF`.
Added: knox/trunk/books/1.4.0/config_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_authn.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_authn.md (added)
+++ knox/trunk/books/1.4.0/config_authn.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,159 @@
+<!---
+ 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
+
+ http://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.
+--->
+
+### Authentication ###
+
+There are two types of providers supported in Knox for establishing a user's identity:
+
+1. Authentication Providers
+2. Federation Providers
+
+Authentication providers directly accept a user's credentials and validates them against some particular user store. Federation providers, on the other hand, validate a token that has been issued for the user by a trusted Identity Provider (IdP).
+
+The current release of Knox ships with an authentication provider based on the Apache Shiro project and is initially configured for BASIC authentication against an LDAP store. This has been specifically tested against Apache Directory Server and Active Directory.
+
+This section will cover the general approach to leveraging Shiro within the bundled provider including:
+
+1. General mapping of provider config to `shiro.ini` config
+2. Specific configuration for the bundled BASIC/LDAP configuration
+3. Some tips into what may need to be customized for your environment
+4. How to setup the use of LDAP over SSL or LDAPS
+
+#### General Configuration for Shiro Provider ####
+
+As is described in the configuration section of this document, providers have a name-value based configuration - as is the common pattern in the rest of Hadoop.
+
+The following example shows the format of the configuration for a given provider:
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>{name}</name>
+ <value>{value}</value>
+ </param>
+ </provider>
+
+Conversely, the Shiro provider currently expects a `shiro.ini` file in the `WEB-INF` directory of the cluster specific web application.
+
+The following example illustrates a configuration of the bundled BASIC/LDAP authentication config in a `shiro.ini` file:
+
+ [urls]
+ /**=authcBasic
+ [main]
+ ldapRealm=org.apache.shiro.realm.ldap.JndiLdapRealm
+ ldapRealm.contextFactory.authenticationMechanism=simple
+ ldapRealm.contextFactory.url=ldap://localhost:33389
+ ldapRealm.userDnTemplate=uid={0},ou=people,dc=hadoop,dc=apache,dc=org
+
+In order to fit into the context of an INI file format, at deployment time we interrogate the parameters provided in the provider configuration and parse the INI section out of the parameter names. The following provider config illustrates this approach. Notice that the section names in the above shiro.ini match the beginning of the parameter names that are in the following config:
+
+ <gateway>
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.shiro.realm.ldap.JndiLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+This happens to be the way that we are currently configuring Shiro for BASIC/LDAP authentication. This same config approach may be used to achieve other authentication mechanisms or variations on this one. We however have not tested additional uses for it for this release.
+
+#### LDAP Configuration ####
+
+This section discusses the LDAP configuration used above for the Shiro Provider. Some of these configuration elements will need to be customized to reflect your deployment environment.
+
+**main.ldapRealm** - this element indicates the fully qualified class name of the Shiro realm to be used in authenticating the user. The class name provided by default in the sample is the `org.apache.shiro.realm.ldap.JndiLdapRealm` this implementation provides us with the ability to authenticate but by default has authorization disabled. In order to provide authorization - which is seen by Shiro as dependent on an LDAP schema that is specific to each organization - an extension of JndiLdapRealm is generally used to override and implement the doGetAuthorizationInfo method. In this particular release we are providing a simple authorization provider that can be used along with the Shiro authentication provider.
+
+**main.ldapRealm.userDnTemplate** - in order to bind a simple username to an LDAP server that generally requires a full distinguished name (DN), we must provide the template into which the simple username will be inserted. This template allows for the creation of a DN by injecting the simple username into the common name (CN) portion of the DN. **This element will need to be customized to reflect your deployment environment.** The template provided in the sample is only an example and is valid only within the LDAP schema distributed with Knox and is represented by the `users.ldif` file in the `{GATEWAY_HOME}/conf` directory.
+
+**main.ldapRealm.contextFactory.url** - this element is the URL that represents the host and port of the LDAP server. It also includes the scheme of the protocol to use. This may be either `ldap` or `ldaps` depending on whether you are communicating with the LDAP over SSL (highly recommended). **This element will need to be customized to reflect your deployment environment.**.
+
+**main.ldapRealm.contextFactory.authenticationMechanism** - this element indicates the type of authentication that should be performed against the LDAP server. The current default value is `simple` which indicates a simple bind operation. This element should not need to be modified and no mechanism other than a simple bind has been tested for this particular release.
+
+**urls./**** - this element represents a single URL_Ant_Path_Expression and the value the Shiro filter chain to apply to it. This particular sample indicates that all paths into the application have the same Shiro filter chain applied. The paths are relative to the application context path. The use of the value `authcBasic` here indicates that BASIC authentication is expected for every path into the application. Adding an additional Shiro filter to that chain for validating that the request isSecure() and over SSL can be achieved by changing the value to `ssl, authcBasic`. It is not likely that you need to change this element for your environment.
+
+#### Active Directory - Special Note ####
+
+You would use LDAP configuration as documented above to authenticate against Active Directory as well.
+
+Some Active Directory specific things to keep in mind:
+
+Typical AD `main.ldapRealm.userDnTemplate` value looks slightly different, such as
+
+ cn={0},cn=users,DC=lab,DC=sample,dc=com
+
+Please compare this with a typical Apache DS `main.ldapRealm.userDnTemplate` value and make note of the difference:
+
+ `uid={0},ou=people,dc=hadoop,dc=apache,dc=org`
+
+If your AD is configured to authenticate based on just the cn and password and does not require user DN, you do not have to specify value for `main.ldapRealm.userDnTemplate`.
+
+
+#### LDAP over SSL (LDAPS) Configuration ####
+In order to communicate with your LDAP server over SSL (again, highly recommended), you will need to modify the topology file in a couple ways and possibly provision some keying material.
+
+1. **main.ldapRealm.contextFactory.url** must be changed to have the `ldaps` protocol scheme and the port must be the SSL listener port on your LDAP server.
+2. Identity certificate (keypair) provisioned to LDAP server - your LDAP server specific documentation should indicate what is required for providing a cert or keypair to represent the LDAP server identity to connecting clients.
+3. Trusting the LDAP Server's public key - if the LDAP Server's identity certificate is issued by a well known and trusted certificate authority and is already represented in the JRE's cacerts truststore then you don't need to do anything for trusting the LDAP server's cert. If, however, the cert is self-signed or issued by an untrusted authority you will need to either add it to the cacerts keystore or to another truststore that you may direct Knox to utilize through a system property (`javax.net.ssl.trustStore` and `javax.net.ssl.trustStorePassword`).
+
+#### Session Configuration ####
+
+Knox maps each cluster topology to a web application and leverages standard JavaEE session management.
+
+To configure session idle timeout for the topology, please specify value of parameter sessionTimeout for ShiroProvider in your topology file. If you do not specify the value for this parameter, it defaults to 30 minutes.
+
+The definition would look like the following in the topology file:
+
+ ...
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <!--
+ Session timeout in minutes. This is really idle timeout.
+ Defaults to 30 minutes, if the property value is not defined.
+ Current client authentication will expire if client idles
+ continuously for more than this value
+ -->
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <provider>
+ ...
+
+At present, ShiroProvider in Knox leverages JavaEE session to maintain authentication state for a user across requests using JSESSIONID cookie. So, a client that authenticated with Knox could pass the JSESSIONID cookie with repeated requests as long as the session has not timed out instead of submitting userid/password with every request. Presenting a valid session cookie in place of userid/password would also perform better as additional credential store lookups are avoided.
Added: knox/trunk/books/1.4.0/config_authz.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_authz.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_authz.md (added)
+++ knox/trunk/books/1.4.0/config_authz.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,321 @@
+<!--
+ 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
+
+ http://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.
+-->
+
+### Authorization ###
+
+#### Service Level Authorization ####
+
+The Knox Gateway has an out-of-the-box authorization provider that allows administrators to restrict access to the individual services within a Hadoop cluster.
+
+This provider utilizes a simple and familiar pattern of using ACLs to protect Hadoop resources by specifying users, groups and ip addresses that are permitted access.
+
+Note: This feature will not work as expected if 'anonymous' authentication is used.
+
+#### Configuration ####
+
+ACLs are bound to services within the topology descriptors by introducing the authorization provider with configuration like:
+
+ <provider>
+ <role>authorization</role>
+ <name>AclsAuthz</name>
+ <enabled>true</enabled>
+ </provider>
+
+The above configuration enables the authorization provider but does not indicate any ACLs yet and therefore there is no restriction to accessing the Hadoop services. In order to indicate the resources to be protected and the specific users, groups or ip's to grant access, we need to provide parameters like the following:
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>username[,*|username...];group[,*|group...];ipaddr[,*|ipaddr...]</value>
+ </param>
+
+where `{serviceName}` would need to be the name of a configured Hadoop service within the topology.
+
+NOTE: ipaddr is unique among the parts of the ACL in that you are able to specify a wildcard within an ipaddr to indicate that the remote address must being with the String prior to the asterisk within the ipaddr ACL. For instance:
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>*;*;192.168.*</value>
+ </param>
+
+This indicates that the request must come from an IP address that begins with '192.168.' in order to be granted access.
+
+Note also that configuration without any ACLs defined is equivalent to:
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>*;*;*</value>
+ </param>
+
+meaning: all users, groups and IPs have access.
+Each of the elements of the ACL parameter support multiple values via comma separated list and the `*` wildcard to match any.
+
+For instance:
+
+ <param>
+ <name>webhdfs.acl</name>
+ <value>hdfs;admin;127.0.0.2,127.0.0.3</value>
+ </param>
+
+this configuration indicates that ALL of the following have to be satisfied to be granted access:
+
+1. The user name must be "hdfs" AND
+2. the user must be in the group "admin" AND
+3. the user must come from either 127.0.0.2 or 127.0.0.3
+
+This allows us to craft policy that restricts the members of a large group to a subset that should have access.
+The user being removed from the group will allow access to be denied even though their username may have been in the ACL.
+
+An additional configuration element may be used to alter the processing of the ACL to be OR instead of the default AND behavior:
+
+ <param>
+ <name>{serviceName}.acl.mode</name>
+ <value>OR</value>
+ </param>
+
+this processing behavior requires that the effective user satisfy one of the parts of the ACL definition in order to be granted access.
+For instance:
+
+ <param>
+ <name>webhdfs.acl</name>
+ <value>hdfs,guest;admin;127.0.0.2,127.0.0.3</value>
+ </param>
+
+You may also set the ACL processing mode at the top level for the topology. This essentially sets the default for the managed cluster.
+It may then be overridden at the service level as well.
+
+ <param>
+ <name>acl.mode</name>
+ <value>OR</value>
+ </param>
+
+this configuration indicates that ONE of the following must be satisfied to be granted access:
+
+1. The user is "hdfs" or "guest" OR
+2. the user is in "admin" group OR
+3. the request is coming from 127.0.0.2 or 127.0.0.3
+
+
+Following are a few concrete examples on how to use this feature.
+
+Note: In the examples below `{serviceName}` represents a real service name (e.g. WEBHDFS) and would be replaced with these values in an actual configuration.
+
+##### Usecases #####
+
+###### USECASE-1: Restrict access to specific Hadoop services to specific Users
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;*;*</value>
+ </param>
+
+###### USECASE-2: Restrict access to specific Hadoop services to specific Groups
+
+ <param>
+ <name>{serviceName}.acls</name>
+ <value>*;admins;*</value>
+ </param>
+
+###### USECASE-3: Restrict access to specific Hadoop services to specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>*;*;127.0.0.1</value>
+ </param>
+
+###### USECASE-4: Restrict access to specific Hadoop services to specific Users OR users within specific Groups
+
+ <param>
+ <name>{serviceName}.acl.mode</name>
+ <value>OR</value>
+ </param>
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;admin;*</value>
+ </param>
+
+###### USECASE-5: Restrict access to specific Hadoop services to specific Users OR users from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl.mode</name>
+ <value>OR</value>
+ </param>
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;*;127.0.0.1</value>
+ </param>
+
+###### USECASE-6: Restrict access to specific Hadoop services to users within specific Groups OR from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl.mode</name>
+ <value>OR</value>
+ </param>
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>*;admin;127.0.0.1</value>
+ </param>
+
+###### USECASE-7: Restrict access to specific Hadoop services to specific Users OR users within specific Groups OR from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl.mode</name>
+ <value>OR</value>
+ </param>
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;admin;127.0.0.1</value>
+ </param>
+
+###### USECASE-8: Restrict access to specific Hadoop services to specific Users AND users within specific Groups
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;admin;*</value>
+ </param>
+
+###### USECASE-9: Restrict access to specific Hadoop services to specific Users AND users from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;*;127.0.0.1</value>
+ </param>
+
+###### USECASE-10: Restrict access to specific Hadoop services to users within specific Groups AND from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>*;admins;127.0.0.1</value>
+ </param>
+
+###### USECASE-11: Restrict access to specific Hadoop services to specific Users AND users within specific Groups AND from specific Remote IPs
+
+ <param>
+ <name>{serviceName}.acl</name>
+ <value>guest;admins;127.0.0.1</value>
+ </param>
+
+###### USECASE-12: Full example including identity assertion/principal mapping ######
+
+The principal mapping aspect of the identity assertion provider is important to understand in order to fully utilize the authorization features of this provider.
+
+This feature allows us to map the authenticated principal to a runAs or impersonated principal to be asserted to the Hadoop services in the backend. It is fully documented in the Identity Assertion section of this guide.
+
+These additional mapping capabilities are used together with the authorization ACL policy.
+An example of a full topology that illustrates these together is below.
+
+ <topology>
+ <gateway>
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.shiro.realm.ldap.JndiLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ <param>
+ <name>principal.mapping</name>
+ <value>guest=hdfs;</value>
+ </param>
+ <param>
+ <name>group.principal.mapping</name>
+ <value>*=users;hdfs=admin</value>
+ </param>
+ </provider>
+ <provider>
+ <role>authorization</role>
+ <name>AclsAuthz</name>
+ <enabled>true</enabled>
+ <param>
+ <name>acl.mode</name>
+ <value>OR</value>
+ </param>
+ <param>
+ <name>webhdfs.acl.mode</name>
+ <value>AND</value>
+ </param>
+ <param>
+ <name>webhdfs.acl</name>
+ <value>hdfs;admin;127.0.0.2,127.0.0.3</value>
+ </param>
+ <param>
+ <name>webhcat.acl</name>
+ <value>hdfs;admin;127.0.0.2,127.0.0.3</value>
+ </param>
+ </provider>
+ <provider>
+ <role>hostmap</role>
+ <name>static</name>
+ <enabled>true</enabled>
+ <param>
+ <name>localhost</name>
+ <value>sandbox,sandbox.hortonworks.com</value>
+ </param>
+ </provider>
+ </gateway>
+
+ <service>
+ <role>JOBTRACKER</role>
+ <url>rpc://localhost:8050</url>
+ </service>
+
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+
+ <service>
+ <role>OOZIE</role>
+ <url>http://localhost:11000/oozie</url>
+ </service>
+
+ <service>
+ <role>WEBHBASE</role>
+ <url>http://localhost:8080</url>
+ </service>
+
+ <service>
+ <role>HIVE</role>
+ <url>http://localhost:10001/cliservice</url>
+ </service>
+ </topology>
Added: knox/trunk/books/1.4.0/config_ha.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_ha.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_ha.md (added)
+++ knox/trunk/books/1.4.0/config_ha.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,165 @@
+<!---
+ 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
+
+ http://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.
+--->
+
+### High Availability ###
+
+This describes how Knox itself can be made highly available.
+
+All Knox instances must be configured to use the same topology credential keystores.
+These files are located under `{GATEWAY_HOME}/data/security/keystores/{TOPOLOGY_NAME}-credentials.jceks`.
+They are generated after the first topology deployment.
+
+In addition to these topology-specific credentials, gateway credentials and topologies must also be kept in-sync for Knox to operate in an HA manner.
+
+#### Manually Synchronize Knox Instances ####
+
+Here are the steps to manually sync topology credential keystores:
+
+1. Choose a Knox instance that will be the source for topology credential keystores. Let's call it _keystores master_
+2. Replace the topology credential keystores in the other Knox instances with topology credential keystores from the _keystores master_
+3. Restart Knox instances
+
+Manually synchronizing the gateway credentials and topologies involves using ssh/scp to copy the topology-related files to all the participating Knox instances, and running the Knox CLI on each participating instance to define the gateway credential aliases.
+
+This manual process can be tedious and error-prone. As such, [ZooKeeper-based HA](#High+Availability+with+Apache+ZooKeeper) is recommended to simplify the management of these deployments.
+
+#### High Availability with Apache ZooKeeper ####
+
+Rather than manually keeping Knox HA instances in sync (in terms of credentials and topology), Knox can get it's state from Apache ZooKeeper.
+By configuring all the Knox instances to monitor the same ZooKeeper ensemble, they can be kept in-sync by modifying the topology-related
+configuration and/or credential aliases at only one of the instances (using the Admin UI, Admin API, or Knox CLI).
+
+##### What is Automatically Synchronized Across Instances?
+
+* Provider Configurations
+* Descriptors
+* *Topologies* (generated only)
+* Credential Aliases
+
+When a provider configuration or descriptor is added or updated to the ZooKeeper ensemble, all of the participating Knox instances will get the change, and the affected topologies will be [re]generated and [re]deployed. Similarly, if one of these is deleted, the affected topologies will be deleted and undeployed.
+
+When provider configurations and descriptors are added, modified or removed using the Admin UI or API (when the Knox instance is configured to monitor a ZooKeeper ensemble), then those changes will be automatically reflected in the associated ZooKeeper ensemble. Those changes will subsequently be consumed by all the other Knox instances monitoring that ensemble.
+By using the Admin UI or API, ssh/scp access to the Knox hosts can be avoided completely for the purpose of effecting topology changes.
+
+Similarly, when the Knox CLI is used to create or delete a gateway alias (when the Knox instance is configured to monitor a ZooKeeper ensemble), that alias change is reflected in the ZooKeeper ensemble, and all other Knox instances montoring that ensemble will apply the change.
+
+
+##### What is NOT Automatically Synchronized Across Instances?
+
+* Topologies (XML)
+* Gateway config (e.g., gateway-site, gateway-logging, etc...)
+
+If you're creating/modifying topology XML files directly, then there is no automated support for keeping these in sync across Knox HA instances.
+
+However, if the Knox instances are running in an Apache Ambari-managed cluster, there is limited support for keeping topology XML files and gateway configuration synchronized across those instances.
+
+<br>
+
+#### High Availability with Apache HTTP Server + mod_proxy + mod_proxy_balancer ####
+
+##### 1 - Requirements #####
+
+###### openssl-devel ######
+
+openssl-devel is required for Apache Module mod_ssl.
+
+ sudo yum install openssl-devel
+
+###### Apache HTTP Server ######
+
+Apache HTTP Server 2.4.6 or later is required. See this document for installing and setting up Apache HTTP Server: http://httpd.apache.org/docs/2.4/install.html
+
+Hint: pass `--enable-ssl` to the `./configure` command to enable the generation of the Apache Module _mod_ssl_.
+
+###### Apache Module mod_proxy ######
+
+See this document for setting up Apache Module mod_proxy: http://httpd.apache.org/docs/2.4/mod/mod_proxy.html
+
+###### Apache Module mod_proxy_balancer ######
+
+See this document for setting up Apache Module mod_proxy_balancer: http://httpd.apache.org/docs/2.4/mod/mod_proxy_balancer.html
+
+###### Apache Module mod_ssl ######
+
+See this document for setting up Apache Module mod_ssl: http://httpd.apache.org/docs/2.4/mod/mod_ssl.html
+
+##### 2 - Configuration example #####
+
+###### Generate certificate for Apache HTTP Server ######
+
+See this document for an example: http://www.akadia.com/services/ssh_test_certificate.html
+
+By convention, Apache HTTP Server and Knox certificates are put into the `/etc/apache2/ssl/` folder.
+
+###### Update Apache HTTP Server configuration file ######
+
+This file is located under {APACHE_HOME}/conf/httpd.conf.
+
+Following directives have to be added or uncommented in the configuration file:
+
+* LoadModule proxy_module modules/mod_proxy.so
+* LoadModule proxy_http_module modules/mod_proxy_http.so
+* LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
+* LoadModule ssl_module modules/mod_ssl.so
+* LoadModule lbmethod_byrequests_module modules/mod_lbmethod_byrequests.so
+* LoadModule lbmethod_bytraffic_module modules/mod_lbmethod_bytraffic.so
+* LoadModule lbmethod_bybusyness_module modules/mod_lbmethod_bybusyness.so
+* LoadModule lbmethod_heartbeat_module modules/mod_lbmethod_heartbeat.so
+* LoadModule slotmem_shm_module modules/mod_slotmem_shm.so
+
+Also following lines have to be added to file. Replace placeholders (${...}) with real data:
+
+ Listen 443
+ <VirtualHost *:443>
+ SSLEngine On
+ SSLProxyEngine On
+ SSLCertificateFile ${PATH_TO_CERTIFICATE_FILE}
+ SSLCertificateKeyFile ${PATH_TO_CERTIFICATE_KEY_FILE}
+ SSLProxyCACertificateFile ${PATH_TO_PROXY_CA_CERTIFICATE_FILE}
+
+ ProxyRequests Off
+ ProxyPreserveHost Off
+
+ RequestHeader set X-Forwarded-Port "443"
+ Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
+ <Proxy balancer://mycluster>
+ BalancerMember ${HOST_#1} route=1
+ BalancerMember ${HOST_#2} route=2
+ ...
+ BalancerMember ${HOST_#N} route=N
+
+ ProxySet failontimeout=On lbmethod=${LB_METHOD} stickysession=ROUTEID
+ </Proxy>
+
+ ProxyPass / balancer://mycluster/
+ ProxyPassReverse / balancer://mycluster/
+ </VirtualHost>
+
+Note:
+
+* SSLProxyEngine enables SSL between Apache HTTP Server and Knox instances;
+* SSLCertificateFile and SSLCertificateKeyFile have to point to certificate data of Apache HTTP Server. User will use this certificate for communications with Apache HTTP Server;
+* SSLProxyCACertificateFile has to point to Knox certificates.
+
+###### Start/stop Apache HTTP Server ######
+
+ APACHE_HOME/bin/apachectl -k start
+ APACHE_HOME/bin/apachectl -k stop
+
+###### Verify ######
+
+Use Knox samples.
Added: knox/trunk/books/1.4.0/config_hadoop_auth_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_hadoop_auth_provider.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_hadoop_auth_provider.md (added)
+++ knox/trunk/books/1.4.0/config_hadoop_auth_provider.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,98 @@
+<!---
+ 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
+
+ http://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.
+--->
+
+### HadoopAuth Authentication Provider ###
+The HadoopAuth authentication provider for Knox integrates the use of the Apache Hadoop module for SPNEGO and delegation token based authentication. This introduces the same authentication pattern used across much of the Hadoop ecosystem to Apache Knox and allows clients to using the strong authentication and SSO capabilities of Kerberos.
+
+#### Configuration ####
+##### Overview #####
+As with all providers in the Knox gateway, the HadoopAuth provider is configured through provider parameters. The configuration parameters are the same parameters used within Apache Hadoop for the same capabilities. In this section, we provide an example configuration and description of each of the parameters. We do encourage the reader to refer to the Hadoop documentation for this as well. (see http://hadoop.apache.org/docs/current/hadoop-auth/Configuration.html)
+
+One of the interesting things to note about this configuration is the use of the `config.prefix` parameter. In Hadoop there may be multiple components with their own specific configuration values for these parameters and since they may get mixed into the same Configuration object - there needs to be a way to identify the component specific values. The `config.prefix` parameter is used for this and is prepended to each of the configuration parameters for this provider. Below, you see an example configuration where the value for config.prefix happens to be `hadoop.auth.config`. You will also notice that this same value is prepended to the name of the rest of the configuration parameters.
+
+ <provider>
+ <role>authentication</role>
+ <name>HadoopAuth</name>
+ <enabled>true</enabled>
+ <param>
+ <name>config.prefix</name>
+ <value>hadoop.auth.config</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.signature.secret</name>
+ <value>knox-signature-secret</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.type</name>
+ <value>kerberos</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.simple.anonymous.allowed</name>
+ <value>false</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.token.validity</name>
+ <value>1800</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.cookie.domain</name>
+ <value>novalocal</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.cookie.path</name>
+ <value>gateway/default</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.kerberos.principal</name>
+ <value>HTTP/lmccay-knoxft-24m-r6-sec-160422-1327-2.novalocal@EXAMPLE.COM</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.kerberos.keytab</name>
+ <value>/etc/security/keytabs/spnego.service.keytab</value>
+ </param>
+ <param>
+ <name>hadoop.auth.config.kerberos.name.rules</name>
+ <value>DEFAULT</value>
+ </param>
+ </provider>
+
+
+#### Descriptions ####
+The following tables describes the configuration parameters for the HadoopAuth provider:
+
+###### Config
+
+Name | Description | Default
+---------|-----------|----
+config.prefix | If specified, all other configuration parameter names must start with the prefix. | none
+signature.secret|This is the secret used to sign the delegation token in the hadoop.auth cookie. This same secret needs to be used across all instances of the Knox gateway in a given cluster. Otherwise, the delegation token will fail validation and authentication will be repeated each request. | A simple random number
+type | This parameter needs to be set to `kerberos` | none, would throw exception
+simple.anonymous.allowed | This should always be false for a secure deployment. | true
+token.validity | The validity -in seconds- of the generated authentication token. This is also used for the rollover interval when `signer.secret.provider` is set to random or ZooKeeper. | 36000 seconds
+cookie.domain | Domain to use for the HTTP cookie that stores the authentication token | null
+cookie.path | Path to use for the HTTP cookie that stores the authentication token | null
+kerberos.principal | The web-application Kerberos principal name. The Kerberos principal name must start with HTTP/.... For example: `HTTP/localhost@LOCALHOST` | null
+kerberos.keytab | The path to the keytab file containing the credentials for the kerberos principal. For example: `/Users/lmccay/lmccay.keytab` | null
+kerberos.name.rules | The name of the ruleset for extracting the username from the kerberos principal. | DEFAULT
+
+###### REST Invocation
+Once a user logs in with kinit then their Kerberos session may be used across client requests with things like curl.
+The following curl command can be used to request a directory listing from HDFS while authenticating with SPNEGO via the `--negotiate` flag
+
+ curl -k -i --negotiate -u : https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
+
+
Added: knox/trunk/books/1.4.0/config_id_assertion.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_id_assertion.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_id_assertion.md (added)
+++ knox/trunk/books/1.4.0/config_id_assertion.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,299 @@
+<!---
+ 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
+
+ http://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.
+-->
+
+### Identity Assertion ###
+The identity assertion provider within Knox plays the critical role of communicating the identity principal to be used within the Hadoop cluster to represent the identity that has been authenticated at the gateway.
+
+The general responsibilities of the identity assertion provider is to interrogate the current Java Subject that has been established by the authentication or federation provider and:
+
+1. determine whether it matches any principal mapping rules and apply them appropriately
+2. determine whether it matches any group principal mapping rules and apply them
+3. if it is determined that the principal will be impersonating another through a principal mapping rule then a Subject.doAS is required so providers farther downstream can determine the appropriate effective principal name and groups for the user
+
+#### Default Identity Assertion Provider ####
+The following configuration is required for asserting the users identity to the Hadoop cluster using Pseudo or Simple "authentication" and for using Kerberos/SPNEGO for secure clusters.
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+
+This particular configuration indicates that the Default identity assertion provider is enabled and that there are no principal mapping rules to apply to identities flowing from the authentication in the gateway to the backend Hadoop cluster services. The primary principal of the current subject will therefore be asserted via a query parameter or as a form parameter - ie. `?user.name={primaryPrincipal}`
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ <param>
+ <name>principal.mapping</name>
+ <value>guest=hdfs;</value>
+ </param>
+ <param>
+ <name>group.principal.mapping</name>
+ <value>*=users;hdfs=admin</value>
+ </param>
+ </provider>
+
+This configuration identifies the same identity assertion provider but does provide principal and group mapping rules. In this case, when a user is authenticated as "guest" his identity is actually asserted to the Hadoop cluster as "hdfs". In addition, since there are group principal mappings defined, he will also be considered as a member of the groups "users" and "admin". In this particular example the wildcard "*" is used to indicate that all authenticated users need to be considered members of the "users" group and that only the user "hdfs" is mapped to be a member of the "admin" group.
+
+**NOTE: These group memberships are currently only meaningful for Service Level Authorization using the AclsAuthorization provider. The groups are not currently asserted to the Hadoop cluster at this time. See the Authorization section within this guide to see how this is used.**
+
+The principal mapping aspect of the identity assertion provider is important to understand in order to fully utilize the authorization features of this provider.
+
+This feature allows us to map the authenticated principal to a runAs or impersonated principal to be asserted to the Hadoop services in the backend.
+
+When a principal mapping is defined that results in an impersonated principal, this impersonated principal is then the effective principal.
+
+If there is no mapping to another principal then the authenticated or primary principal is the effective principal.
+
+#### Principal Mapping ####
+
+ <param>
+ <name>principal.mapping</name>
+ <value>{primaryPrincipal}[,...]={impersonatedPrincipal}[;...]</value>
+ </param>
+
+For instance:
+
+ <param>
+ <name>principal.mapping</name>
+ <value>guest=hdfs</value>
+ </param>
+
+For multiple mappings:
+
+ <param>
+ <name>principal.mapping</name>
+ <value>guest,alice=hdfs;mary=alice2</value>
+ </param>
+
+#### Group Principal Mapping ####
+
+ <param>
+ <name>group.principal.mapping</name>
+ <value>{userName[,*|userName...]}={groupName[,groupName...]}[,...]</value>
+ </param>
+
+For instance:
+
+ <param>
+ <name>group.principal.mapping</name>
+ <value>*=users;hdfs=admin</value>
+ </param>
+
+this configuration indicates that all (*) authenticated users are members of the "users" group and that user "hdfs" is a member of the admin group. Group principal mapping has been added along with the authorization provider described in this document.
+
+#### Concat Identity Assertion Provider ####
+The Concat identity assertion provider allows for composition of a new user principal through the concatenation of optionally configured prefix and/or suffix provider parameters. This is a useful assertion provider for converting an incoming identity into a disambiguated identity within the Hadoop cluster based on what topology is used to access Hadoop.
+
+The following configuration would convert the user principal into a value that represents a domain specific identity where the identities used inside the Hadoop cluster represent this same separation.
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Concat</name>
+ <enabled>true</enabled>
+ <param>
+ <name>concat.suffix</name>
+ <value>_domain1</value>
+ </param>
+ </provider>
+
+The above configuration will result in all user interactions through that topology to have their principal communicated to the Hadoop cluster with a domain designator concatenated to the username. Possibly useful for multi-tenant deployment scenarios.
+
+In addition to the concat.suffix parameter, the provider supports the setting of a prefix through a `concat.prefix` parameter.
+
+#### SwitchCase Identity Assertion Provider ####
+The SwitchCase identity assertion provider solves issues where down stream ecosystem components require user and group principal names to be a specific case.
+An example of how this provider is enabled and configured within the `<gateway>` section of a topology file is shown below.
+This particular example will switch user principals names to lower case and group principal names to upper case.
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>SwitchCase</name>
+ <param>
+ <name>principal.case</name>
+ <value>lower</value>
+ </param>
+ <param>
+ <name>group.principal.case</name>
+ <value>upper</value>
+ </param>
+ <enabled>true</enabled>
+ </provider>
+
+These are the configuration parameters used to control the behavior of the provider.
+
+Param | Description
+---------------------|------------
+principal.case | The case mapping of user principal names. Choices are: lower, upper, none. Defaults to lower.
+group.principal.case | The case mapping of group principal names. Choices are: lower, upper, none. Defaults to setting of principal.case.
+
+If no parameters are provided the full defaults will results in both user and group principal names being switched to lower case.
+A setting of "none" or anything other than "upper" or "lower" leaves the case of the principal name unchanged.
+
+#### Regular Expression Identity Assertion Provider ####
+The regular expression identity assertion provider allows incoming identities to be translated using a regular expression, template and lookup table.
+This will probably be most useful in conjunction with the HeaderPreAuth federation provider.
+
+There are three configuration parameters used to control the behavior of the provider.
+
+Param | Description
+------|-----------
+input | This is a regular expression that will be applied to the incoming identity. The most critical part of the regular expression is the group notation within the expression. In regular expressions, groups are expressed within parenthesis. For example in the regular expression "`(.*)@(.*?)\..*`" there are two groups. When this regular expression is applied to "nobody@us.imaginary.tld" group 1 matches "nobody" and group 2 matches "us".
+output| This is a template that assembles the result identity. The result is assembled from the static text and the matched groups from the input regular expression. In addition, the matched group values can be looked up in the lookup table. An output value of "`{1}_{2}`" of will result in "nobody_us".
+lookup| This lookup table provides a simple (albeit limited) way to translate text in the incoming identities. This configuration takes the form of "=" separated name values pairs separated by ";". For example a lookup setting is "us=USA;ca=CANADA". The lookup is invoked in the output setting by surrounding the desired group number in square brackets (i.e. []). Putting it all together, output setting of "`{1}_[{2}]`" combined with input of "`(.*)@(.*?)\..*`" and lookup of "us=USA;ca=CANADA" will turn "nobody@us.imaginary.tld" into "nobody@USA".
+use.original.on.lookup.failure | (Optional) Default value is false. If set to true, it will preserve the original string if there is no match. e.g. In the above lookup case for email nobody@uk.imaginary.tld, it will be transformed to nobody@ , if this property is set to true it will be transformed to nobody@uk.
+
+Within the topology file the provider configuration might look like this.
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Regex</name>
+ <enabled>true</enabled>
+ <param>
+ <name>input</name>
+ <value>(.*)@(.*?)\..*</value>
+ </param>
+ <param>
+ <name>output</name>
+ <value>{1}_{[2]}</value>
+ </param>
+ <param>
+ <name>lookup</name>
+ <value>us=USA;ca=CANADA</value>
+ </param>
+ </provider>
+
+Using curl with this type of configuration might produce the following results.
+
+ curl -k --header "SM_USER: nobody@us.imaginary.tld" 'https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY'
+
+ {"Path":"/user/member_USA"}
+
+ url -k --header "SM_USER: nobody@ca.imaginary.tld" 'https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY'
+
+ {"Path":"/user/member_CANADA"}
+
+### Hadoop Group Lookup Provider ###
+
+An identity assertion provider that looks up user's 'group membership' for authenticated users using Hadoop's group mapping service (GroupMappingServiceProvider).
+
+This allows existing investments in the Hadoop to be leveraged within Knox and used within the access control policy enforcement at the perimeter.
+
+The 'role' for this provider is 'identity-assertion' and name is 'HadoopGroupProvider'.
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>HadoopGroupProvider</name>
+ <enabled>true</enabled>
+ <<param> ... </param>
+ </provider>
+
+### Configuration ###
+
+All the configuration for 'HadoopGroupProvider' resides in the provider section in a gateway topology file.
+The 'hadoop.security.group.mapping' property determines the implementation. This configuration may be centralized within the gateway-site.xml through the use of a special param to this provider called CENTRAL_GROUP_CONFIG_PREFIX. This indicates to the provider that the required configuration can be found within the gateway-site.xml file with the provided prefix.
+
+ <param>
+ <name>CENTRAL_GROUP_CONFIG_PREFIX</name>
+ <value>gateway.group.config.</value>
+ </param>
+
+ Some of the valid implementations are as follows:
+#### org.apache.hadoop.security.JniBasedUnixGroupsMappingWithFallback
+
+This is the default implementation and will be picked up if 'hadoop.security.group.mapping' is not specified. This implementation will determine if the Java Native Interface (JNI) is available. If JNI is available, the implementation will use the API within Hadoop to resolve a list of groups for a user. If JNI is not available then the shell implementation, `org.apache.hadoop.security.ShellBasedUnixGroupsMapping`, is used, which shells out with the `bash -c id -gn <user> ; id -Gn <user>` command (for a Linux/Unix environment) or the `groups -F <user>` command (for a Windows environment) to resolve a list of groups for a user.
+
+#### org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMappingWithFallback
+
+As above, if JNI is available then we get the netgroup membership using Hadoop native API, else fallback on ShellBasedUnixGroupsNetgroupMapping to resolve list of groups for a user.
+
+#### org.apache.hadoop.security.ShellBasedUnixGroupsMapping
+
+Uses the `bash -c id -gn <user> ; id -Gn <user>` command (for a Linux/Unix environment) or the `groups -F <user>` command (for a Windows environment) to resolve list of groups for a user.
+
+#### org.apache.hadoop.security.ShellBasedUnixGroupsNetgroupMapping
+
+Similar to `org.apache.hadoop.security.ShellBasedUnixGroupsMapping` except it uses `getent netgroup` command to get netgroup membership.
+
+#### org.apache.hadoop.security.LdapGroupsMapping
+
+This implementation connects directly to an LDAP server to resolve the list of groups. However, this should only be used if the required groups reside exclusively in LDAP, and are not materialized on the Unix servers.
+
+#### org.apache.hadoop.security.CompositeGroupsMapping
+
+This implementation asks multiple other group mapping providers for determining group membership, see [Composite Groups Mapping](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/GroupsMapping.html#Composite_Groups_Mapping) for more details.
+
+For more information on the implementation and properties refer to Hadoop Group Mapping.
+
+### Example ###
+
+The following example snippet works with the demo ldap server that ships with Apache Knox. Replace the existing 'Default' identity-assertion provider with the one below (HadoopGroupProvider).
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>HadoopGroupProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>hadoop.security.group.mapping</name>
+ <value>org.apache.hadoop.security.LdapGroupsMapping</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.bind.user</name>
+ <value>uid=tom,ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.bind.password</name>
+ <value>tom-password</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.base</name>
+ <value></value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.search.filter.user</name>
+ <value>(&(|(objectclass=person)(objectclass=applicationProcess))(cn={0}))</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.search.filter.group</name>
+ <value>(objectclass=groupOfNames)</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.search.attr.member</name>
+ <value>member</value>
+ </param>
+ <param>
+ <name>hadoop.security.group.mapping.ldap.search.attr.group.name</name>
+ <value>cn</value>
+ </param>
+ </provider>
+
+
+Here, we are working with the demo LDAP server running at 'ldap://localhost:33389' which populates some dummy users for testing that we will use in this example. This example uses the user 'tom' for LDAP binding. If you have different LDAP/AD settings, you will have to update the properties accordingly.
+
+Let's test our setup using the following command (assuming the gateway is started and listening on localhost:8443). Note that we are using credentials for the user 'sam' along with the command.
+
+ curl -i -k -u sam:sam-password -X GET 'https://localhost:8443/gateway/sandbox/webhdfs/v1/?op=LISTSTATUS'
+
+The command should be executed successfully and you should see the groups 'scientist' and 'analyst' to which user 'sam' belongs to in gateway-audit.log i.e.
+
+ ||a99aa0ab-fc06-48f2-8df3-36e6fe37c230|audit|WEBHDFS|sam|||identity-mapping|principal|sam|success|Groups: [scientist, analyst]
Added: knox/trunk/books/1.4.0/config_kerberos.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_kerberos.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_kerberos.md (added)
+++ knox/trunk/books/1.4.0/config_kerberos.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,68 @@
+<!---
+ 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
+
+ http://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.
+--->
+
+### Secure Clusters ###
+
+See the Hadoop documentation for setting up a secure Hadoop cluster
+http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/SecureMode.html
+
+Once you have a Hadoop cluster that is using Kerberos for authentication, you have to do the following to configure Knox to work with that cluster.
+
+#### Create Unix account for Knox on Hadoop master nodes ####
+
+ useradd -g hadoop knox
+
+#### Create Kerberos principal, keytab for Knox ####
+
+One way of doing this, assuming your KDC realm is EXAMPLE.COM, is to ssh into your host running KDC and execute `kadmin.local`
+That will result in an interactive session in which you can execute commands.
+
+ssh into your host running KDC
+
+ kadmin.local
+ add_principal -randkey knox/knox@EXAMPLE.COM
+ ktadd -k knox.service.keytab -norandkey knox/knox@EXAMPLE.COM
+ exit
+
+
+#### Copy knox keytab to Knox host ####
+
+Add unix account for the knox user on Knox host
+
+ useradd -g hadoop knox
+
+Copy knox.service.keytab created on KDC host on to your Knox host `{GATEWAY_HOME}/conf/knox.service.keytab`
+
+ chown knox knox.service.keytab
+ chmod 400 knox.service.keytab
+
+#### Update `krb5.conf` at `{GATEWAY_HOME}/conf/krb5.conf` on Knox host ####
+
+You could copy the `{GATEWAY_HOME}/templates/krb5.conf` file provided in the Knox binary download and customize it to suit your cluster.
+
+#### Update `krb5JAASLogin.conf` at `/etc/knox/conf/krb5JAASLogin.conf` on Knox host ####
+
+You could copy the `{GATEWAY_HOME}/templates/krb5JAASLogin.conf` file provided in the Knox binary download and customize it to suit your cluster.
+
+#### Update `gateway-site.xml` on Knox host ####
+
+Update `conf/gateway-site.xml` in your Knox installation and set the value of `gateway.hadoop.kerberos.secured` to true.
+
+#### Restart Knox ####
+
+After you do the above configurations and restart Knox, Knox would use SPNEGO to authenticate with Hadoop services and Oozie.
+There is no change in the way you make calls to Knox whether you use curl or Knox DSL.
Added: knox/trunk/books/1.4.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_knox_sso.md?rev=1863668&view=auto
==============================================================================
--- knox/trunk/books/1.4.0/config_knox_sso.md (added)
+++ knox/trunk/books/1.4.0/config_knox_sso.md Tue Jul 23 21:27:15 2019
@@ -0,0 +1,151 @@
+## KnoxSSO Setup and Configuration
+
+### Introduction
+---
+
+Authentication of the Hadoop component UIs, and those of the overall ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the user's browser) and simple/pseudo. This often results in the UIs not being secured - even in secured clusters. This is where KnoxSSO provides value by providing WebSSO capabilities to the Hadoop cluster.
+
+By leveraging the hadoop-auth module in Hadoop common, we have introduced the ability to consume a common SSO cookie for web UIs while retaining the non-web browser authentication through kerberos/SPNEGO. We do this by extending the AltKerberosAuthenticationHandler class which provides the useragent based multiplexing.
+
+We also provide integration guidance within the developers guide for other applications to be able to participate in these SSO capabilities.
+
+The flexibility of the Apache Knox authentication and federation providers allows KnoxSSO to provide a normalization of authentication events through token exchange resulting in a common JWT (JSON WebToken) based token.
+
+KnoxSSO provides an abstraction for integrating any number of authentication systems and SSO solutions and enables participating web applications to scale to those solutions more easily. Without the token exchange capabilities offered by KnoxSSO each component UI would need to integrate with each desired solution on its own. With KnoxSSO they only need to integrate with the single solution and common token.
+
+In addition, KnoxSSO comes with its own form-based IdP. This allows for easily integrating a form-based login with the enterprise AD/LDAP server.
+
+This document describes the overall setup requirements for KnoxSSO and participating applications.
+
+### Form-based IdP Setup
+By default the `knoxsso.xml` topology contains an application element for the knoxauth login application. This is a simple single page application for providing a login page and authenticating the user with HTTP basic auth against AD/LDAP.
+
+ <application>
+ <name>knoxauth</name>
+ </application>
+
+The Shiro Provider has specialized configuration beyond the typical HTTP Basic authentication requirements for REST APIs or other non-knoxauth applications. You will notice below that there are a couple additional elements - namely, **redirectToUrl** and **restrictedCookies with WWW-Authenticate**. These are used to short-circuit the browser's HTTP basic dialog challenge so that we can use a form instead.
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>redirectToUrl</name>
+ <value>/gateway/knoxsso/knoxauth/login.html</value>
+ </param>
+ <param>
+ <name>restrictedCookies</name>
+ <value>rememberme,WWW-Authenticate</value>
+ </param>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.knox.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.authenticationCachingEnabled</name>
+ <value>false</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+### KnoxSSO Service Setup
+
+#### knoxsso.xml Topology
+To enable KnoxSSO, we use the KnoxSSO topology for exposing an API that can be used to abstract the use of any number of enterprise or customer IdPs. By default, the `knoxsso.xml` file is configured for using the simple KnoxAuth application for form-based authentication against LDAP/AD. By swapping the Shiro authentication provider that is there out-of-the-box with another authentication or federation provider, an admin may leverage many of the existing providers for SSO for the UI components that participate in KnoxSSO.
+
+Just as with any Knox service, the KNOXSSO service is protected by the gateway providers defined above it. In this case, the ShiroProvider is taking care of HTTP Basic Auth against LDAP for us. Once the user authenticates the request processing continues to the KNOXSSO service that will create the required cookie and do the necessary redirects.
+
+The knoxsso.xml topology will result in a KnoxSSO URL that looks something like:
+
+ https://{gateway_host}:{gateway_port}/gateway/knoxsso/api/v1/websso
+
+This URL is needed when configuring applications that participate in KnoxSSO for a given deployment. We will refer to this as the Provider URL.
+
+#### KnoxSSO Configuration Parameters
+
+Parameter | Description | Default
+-------------------------------- |------------ |-----------
+knoxsso.cookie.name | This optional setting allows the admin to set the name of the sso cookie to use to represent a successful authentication event. | hadoop-jwt
+knoxsso.cookie.secure.only | This determines whether the browser is allowed to send the cookie over unsecured channels. This should always be set to true in production systems. If during development a relying party is not running SSL then you can turn this off. Running with it off exposes the cookie and underlying token for capture and replay by others. | true
+knoxsso.cookie.max.age | optional: This indicates that a cookie can only live for a specified amount of time - in seconds. This should probably be left to the default which makes it a session cookie. Session cookies are discarded once the browser session is closed. | session
+knoxsso.cookie.domain.suffix | optional: This indicates the portion of the request hostname that represents the domain to be used for the cookie domain. For single host development scenarios, the default behavior should be fine. For production deployments, the expected domain should be set and all configured URLs that are related to SSO should use this domain. Otherwise, the cookie will not be presented by the browser to mismatched URLs. | Default cookie domain or a domain derived from a hostname that includes more than 2 dots.
+knoxsso.token.ttl | This indicates the lifespan of the token within the cookie. Once it expires a new cookie must be acquired from KnoxSSO. This is in milliseconds. The 36000000 in the topology above gives you 10 hrs. | 30000 That is 30 seconds.
+knoxsso.token.audiences | This is a comma separated list of audiences to add to the JWT token. This is used to ensure that a token received by a participating application knows that the token was intended for use with that application. It is optional. In the event that an application has expected audiences and they are not present the token must be rejected. In the event where the token has audiences and the application has none expected then the token is accepted.| empty
+knoxsso.redirect.whitelist.regex | A semicolon-delimited list of regular expressions. The incoming originalUrl must match one of the expressions in order for KnoxSSO to redirect to it after authentication. Note that cookie use is still constrained to redirect destinations in the same domain as the KnoxSSO service - regardless of the expressions specified here. | The value of the gateway-site property named *gateway.dispatch.whitelist*. If that is not defined, the default allows only relative paths, localhost or destinations in the same domain as the Knox host (with or without SSL). This may need to be opened up for production use and actual participating applications.
+knoxsso.expected.params | Optional: Comma separated list of query parameters that are expected and consumed by KnoxSSO and will not be passed on to originalUrl | empty
+knoxsso.signingkey.keystore.name | Optional: name of a JKS keystore in gateway security directory that has required signing key certificate | empty
+knoxsso.signingkey.keystore.alias | Optional: alias of the signing key certificate in the `knoxsso.signingkey.keystore.name` keystore | empty
+knoxsso.signingkey.keystore.passphrase.alias | Optional: passphrase alias for the signing key certificate | empty
+
+### Participating Application Configuration
+#### Hadoop Configuration Example
+The following is used as the KnoxSSO configuration in the Hadoop JWTRedirectAuthenticationHandler implementation. Any participating application will need similar configuration. Since JWTRedirectAuthenticationHandler extends the AltKerberosAuthenticationHandler, the typical Kerberos configuration parameters for authentication are also required.
+
+
+ <property>
+ <name>hadoop.http.authentication.type</name
+ <value>org.apache.hadoop.security.authentication.server.JWTRedirectAuthenticationHandler</value>
+ </property>
+
+
+This is the handler classname in Hadoop auth for JWT token (KnoxSSO) support.
+
+
+ <property>
+ <name>hadoop.http.authentication.authentication.provider.url</name>
+ <value>https://c6401.ambari.apache.org:8443/gateway/knoxsso/api/v1/websso</value>
+ </property>
+
+
+The above property is the SSO provider URL that points to the knoxsso endpoint.
+
+ <property>
+ <name>hadoop.http.authentication.public.key.pem</name>
+ <value>MIICVjCCAb+gAwIBAgIJAPPvOtuTxFeiMA0GCSqGSIb3DQEBBQUAMG0xCzAJBgNV
+ BAYTAlVTMQ0wCwYDVQQIEwRUZXN0MQ0wCwYDVQQHEwRUZXN0MQ8wDQYDVQQKEwZI
+ YWRvb3AxDTALBgNVBAsTBFRlc3QxIDAeBgNVBAMTF2M2NDAxLmFtYmFyaS5hcGFj
+ aGUub3JnMB4XDTE1MDcxNjE4NDcyM1oXDTE2MDcxNTE4NDcyM1owbTELMAkGA1UE
+ BhMCVVMxDTALBgNVBAgTBFRlc3QxDTALBgNVBAcTBFRlc3QxDzANBgNVBAoTBkhh
+ ZG9vcDENMAsGA1UECxMEVGVzdDEgMB4GA1UEAxMXYzY0MDEuYW1iYXJpLmFwYWNo
+ ZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMFs/rymbiNvg8lDhsdA
+ qvh5uHP6iMtfv9IYpDleShjkS1C+IqId6bwGIEO8yhIS5BnfUR/fcnHi2ZNrXX7x
+ QUtQe7M9tDIKu48w//InnZ6VpAqjGShWxcSzR6UB/YoGe5ytHS6MrXaormfBg3VW
+ tDoy2MS83W8pweS6p5JnK7S5AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEANyVg6EzE
+ 2q84gq7wQfLt9t047nYFkxcRfzhNVL3LB8p6IkM4RUrzWq4kLA+z+bpY2OdpkTOe
+ wUpEdVKzOQd4V7vRxpdANxtbG/XXrJAAcY/S+eMy1eDK73cmaVPnxPUGWmMnQXUi
+ TLab+w8tBQhNbq6BOQ42aOrLxA8k/M4cV1A=</value>
+ </property>
+
+The above property holds the KnoxSSO server's public key for signature verification. Adding it directly to the config like this is convenient and is easily done through Ambari to existing config files that take custom properties. Config is generally protected as root access only as well - so it is a pretty good solution.
+
+Individual UIs within the Hadoop ecosystem will have similar configuration for participating in the KnoxSSO websso capabilities.
+
+Blogs will be provided on the Apache Knox project site for these usecases as they become available.