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 2016/11/02 00:45:34 UTC
svn commit: r1767595 [3/7] - in /knox: site/ site/books/knox-0-4-0/
site/books/knox-0-5-0/ site/books/knox-0-6-0/ site/books/knox-0-7-0/
site/books/knox-0-8-0/ site/books/knox-0-9-0/ site/books/knox-0-9-1/ trunk/
trunk/books/0.10.0/ trunk/books/0.10.0/...
Added: knox/trunk/books/0.10.0/config_advanced_ldap.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_advanced_ldap.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_advanced_ldap.md (added)
+++ knox/trunk/books/0.10.0/config_advanced_ldap.md Wed Nov 2 00:45:33 2016
@@ -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 configuration parameter ldapRealm.userDnTemplate.
+Typical value 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 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 can not 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 LDAP directory
+instead of interpolating 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"
+
+LDAP Filter for doing a search to find the bind DN would be
+
+ (&(uid=guest)(objectclass=person))
+
+This could find 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"
+
+LDAP Filter for doing a search to find the bind DN would be
+
+ (&(email=bill.clinton@gmail.com)(objectclass=person))
+
+This could find 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.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.hadoop.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/0.10.0/config_audit.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_audit.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_audit.md (added)
+++ knox/trunk/books/0.10.0/config_audit.md Wed Nov 2 00:45:33 2016
@@ -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.hadoop.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/0.10.0/config_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_authn.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_authn.md (added)
+++ knox/trunk/books/0.10.0/config_authn.md Wed Nov 2 00:45:33 2016
@@ -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 param 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 doGetAuhtorizationInfo 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 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 selfsigned 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.
+
+#### 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 topoloogy 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.
\ No newline at end of file
Added: knox/trunk/books/0.10.0/config_authz.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_authz.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_authz.md (added)
+++ knox/trunk/books/0.10.0/config_authz.md Wed Nov 2 00:45:33 2016
@@ -0,0 +1,319 @@
+<!---
+ 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.
+
+#### 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 param 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/0.10.0/config_ha.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_ha.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_ha.md (added)
+++ knox/trunk/books/0.10.0/config_ha.md Wed Nov 2 00:45:33 2016
@@ -0,0 +1,127 @@
+<!---
+ 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.
+
+#### Configure Knox instances ####
+
+All Knox instances must be synced to use the same topology credential keystores.
+These files are located under `{GATEWAY_HOME}/conf/security/keystores/{TOPOLOGY_NAME}-credentials.jceks`.
+They are generated after the first topology deployment.
+Currently these files need to be synced manually.
+Here are the steps to sync topologies credentials 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
+
+#### 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 /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/0.10.0/config_hadoop_auth_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_hadoop_auth_provider.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_hadoop_auth_provider.md (added)
+++ knox/trunk/books/0.10.0/config_hadoop_auth_provider.md Wed Nov 2 00:45:33 2016
@@ -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 params. 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/0.10.0/config_id_assertion.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_id_assertion.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_id_assertion.md (added)
+++ knox/trunk/books/0.10.0/config_id_assertion.md Wed Nov 2 00:45:33 2016
@@ -0,0 +1,189 @@
+<!---
+ 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 in order for 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 then 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".
+
+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"}
Added: knox/trunk/books/0.10.0/config_kerberos.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_kerberos.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_kerberos.md (added)
+++ knox/trunk/books/0.10.0/config_kerberos.md Wed Nov 2 00:45:33 2016
@@ -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/0.10.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_knox_sso.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_knox_sso.md (added)
+++ knox/trunk/books/0.10.0/config_knox_sso.md Wed Nov 2 00:45:33 2016
@@ -0,0 +1,86 @@
+## 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/psuedo. 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.
+
+This document describes the overall setup requirements for KnoxSSO and participating applications.
+
+### KnoxSSO 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.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. OPEN ISSUE - not currently being populated in WebSSOResource. | empty
+knoxsso.redirect.whitelist.regex | A semicolon separated list of regex expressions. The incoming originalUrl must match one of the expressions in order for KnoxSSO to redirect to it after authentication. Defaults to only relative paths and localhost with or without SSL for development usecases. This needs to be opened up for production use and actual participating applications. Note that cookie use is still constrained to redirect destinations in the same domain as the KnoxSSO service - regardless of the expressions specified here. | ^/.\*$;^https?://localhost:\\d{0,9}/.\*$
+
+
+### 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.
\ No newline at end of file
Added: knox/trunk/books/0.10.0/config_ldap_authc_cache.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.10.0/config_ldap_authc_cache.md?rev=1767595&view=auto
==============================================================================
--- knox/trunk/books/0.10.0/config_ldap_authc_cache.md (added)
+++ knox/trunk/books/0.10.0/config_ldap_authc_cache.md Wed Nov 2 00:45:33 2016
@@ -0,0 +1,211 @@
+<!---
+ 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.
+--->
+
+### LDAP Authentication Caching ###
+
+Knox can be configured to cache LDAP authentication information. Knox leverages Shiro's built in
+caching mechanisms and has been tested with Shiro's EhCache cache manager implementation.
+
+The following provider snippet demonstrates how to configure turning on the cache using the ShiroProvider. In addition to
+using `org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm` in the Shiro configuration, and setting up the cache you *must* set
+the flag for enabling caching authentication to true. Please see the property, `main.ldapRealm.authenticationCachingEnabled` below.
+
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapGroupContextFactory</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapGroupContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</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.authorizationEnabled</name>
+ <!-- defaults to: false -->
+ <value>true</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.searchBase</name>
+ <value>ou=groups,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.cacheManager</name>
+ <value>org.apache.shiro.cache.ehcache.EhCacheManager</value>
+ </param>
+ <param>
+ <name>main.securityManager.cacheManager</name>
+ <value>$cacheManager</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.authenticationCachingEnabled</name>
+ <value>true</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.memberAttributeValueTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.systemUsername</name>
+ <value>uid=guest,ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.systemPassword</name>
+ <value>guest-password</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+
+### Trying out caching ###
+
+Knox bundles a template topology files that can be used to try out the caching functionality.
+The template file located under `{GATEWAY_HOME}/templates` is `sandbox.knoxrealm.ehcache.xml`.
+
+To try this out
+
+ cd {GATEWAY_HOME}
+ cp templates/sandbox.knoxrealm.ehcache.xml conf/topologies/sandbox.xml
+ bin/ldap.sh start
+ bin/gateway.sh start
+
+The following call to WebHDFS should report: {"Path":"/user/tom"}
+
+ curl -i -v -k -u tom:tom-password -X GET https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY
+
+In order to see the cache working, LDAP can now be shutdown and the user will still authenticate successfully.
+
+ bin/ldap.sh stop
+
+and then the following should still return successfully like it did earlier.
+
+ curl -i -v -k -u tom:tom-password -X GET https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY
+
+
+#### Advanced Caching Config ####
+
+By default the ehcache support in shiro contains a ehcache.xml in its classpath which is the following
+
+ <ehcache>
+
+ <!-- Sets the path to the directory where cache .data files are created.
+
+ If the path is a Java System Property it is replaced by
+ its value in the running VM. The following properties are translated:
+
+ user.home - User's home directory
+ user.dir - User's current working directory
+ java.io.tmpdir - Default temp file path
+ -->
+ <diskStore path="java.io.tmpdir/shiro-ehcache"/>
+
+
+ <!--Default Cache configuration. These will applied to caches programmatically created through
+ the CacheManager.
+
+ The following attributes are required:
+
+ maxElementsInMemory - Sets the maximum number of objects that will be created in memory
+ eternal - Sets whether elements are eternal. If eternal, timeouts are ignored and the
+ element is never expired.
+ overflowToDisk - Sets whether elements can overflow to disk when the in-memory cache
+ has reached the maxInMemory limit.
+
+ The following attributes are optional:
+ timeToIdleSeconds - Sets the time to idle for an element before it expires.
+ i.e. The maximum amount of time between accesses before an element expires
+ Is only used if the element is not eternal.
+ Optional attribute. A value of 0 means that an Element can idle for infinity.
+ The default value is 0.
+ timeToLiveSeconds - Sets the time to live for an element before it expires.
+ i.e. The maximum time between creation time and when an element expires.
+ Is only used if the element is not eternal.
+ Optional attribute. A value of 0 means that and Element can live for infinity.
+ The default value is 0.
+ diskPersistent - Whether the disk store persists between restarts of the Virtual Machine.
+ The default value is false.
+ diskExpiryThreadIntervalSeconds- The number of seconds between runs of the disk expiry thread. The default value
+ is 120 seconds.
+ memoryStoreEvictionPolicy - Policy would be enforced upon reaching the maxElementsInMemory limit. Default
+ policy is Least Recently Used (specified as LRU). Other policies available -
+ First In First Out (specified as FIFO) and Less Frequently Used
+ (specified as LFU)
+ -->
+
+ <defaultCache
+ maxElementsInMemory="10000"
+ eternal="false"
+ timeToIdleSeconds="120"
+ timeToLiveSeconds="120"
+ overflowToDisk="false"
+ diskPersistent="false"
+ diskExpiryThreadIntervalSeconds="120"
+ />
+
+ <!-- We want eternal="true" and no timeToIdle or timeToLive settings because Shiro manages session
+ expirations explicitly. If we set it to false and then set corresponding timeToIdle and timeToLive properties,
+ ehcache would evict sessions without Shiro's knowledge, which would cause many problems
+ (e.g. "My Shiro session timeout is 30 minutes - why isn't a session available after 2 minutes?"
+ Answer - ehcache expired it due to the timeToIdle property set to 120 seconds.)
+
+ diskPersistent=true since we want an enterprise session management feature - ability to use sessions after
+ even after a JVM restart. -->
+ <cache name="shiro-activeSessionCache"
+ maxElementsInMemory="10000"
+ overflowToDisk="true"
+ eternal="true"
+ timeToLiveSeconds="0"
+ timeToIdleSeconds="0"
+ diskPersistent="true"
+ diskExpiryThreadIntervalSeconds="600"/>
+
+ <cache name="org.apache.shiro.realm.text.PropertiesRealm-0-accounts"
+ maxElementsInMemory="1000"
+ eternal="true"
+ overflowToDisk="true"/>
+
+ </ehcache>
+
+A custom configuration file (ehcache.xml) can be used in place of this in order to set specific caching configuration.
+
+In order to set the ehcache.xml file to use for a particular topology, set the following parameter in the configuration
+for the ShiroProvider:
+
+ <param>
+ <name>main.cacheManager.cacheManagerConfigFile</name>
+ <value>classpath:ehcache.xml</value>
+ </param>
+
+In the above example, place the ehcache.xml file under `{GATEWAY_HOME}/conf` and restart the gateway server.