Set Up HeaderPreAuth Federation Provider

How to configure the HeaderPreAuth federation provider.

The Knox Gateway supports federation solution providers by accepting HTTP header tokens. This section explains how to configure HTTP header fields for SSO or Federation solutions that have simple HTTP header-type tokens.

The gateway extracts the user identifier from the HTTP header field. The gateway can also extract the group information and propagate it to the Identity-Assertion provider.

	Note
	The Knox Gateway federation plug-in, HeaderPreAuth, trusts that the content provided in the authenticated header is valid. Using this provider requires proper network security.

Only use the HeaderPreAuth federation provider in environments where the identity system does not allow direct access to the Knox Gateway. Allowing direct access exposes the gateway to identity spoofing. Hortonworks recommends defining the preauth.ip.addresses parameter to ensure requests come from a specific IP addresses only.

1. Open the cluster topology descriptor file, $cluster-name.xml, in a text editor.
2. 
   
   Add a HeaderPreAuth federation provider to topology/gateway as follows:

   <provider>
       <role>federation</role>
       <name>HeaderPreAuth</name>
       <enabled>true</enabled>
       <param>
           <name>preauth.validation.method</name>
           <value>$validation_type</value>
       </param>
       <param>
           <name>preauth.ip.addresses</name>
           <value>$trusted_ip</value>
       </param>
       <param>
           <name>preauth.custom.header</name>
           <value>$user_field</value>
       </param>
       <param>
           <name>preauth.custom.group.header</name>
           <value>$group_field</value>
       </param>
   </provider>

   Where the values of the parameters are specific to your environment:

   • $validation_type (Optional, recommended)

     Indicates the type of trust, use either preauth.ip.validation indicating to trust only connections from the address defined in preauth.ip.addresses OR null (omitted) indicating to trust all IP addresses.

   • $trusted_ip (Required when the pre-authentication method is set to preauth.ip.validation)

     A comma-separated list of IP addresses, addresses may contain a wild card to indicate a subnet, such as 10.0.0.*.

   • $user_field

     The name of the field in the header that contains the user name that the gateway extracts. Any incoming request that is missing the field is refused with HTTP status 401, unauthorized. If not otherwise specified, the default value is SM_USER.

   • $group_field (Optional)

     The name of the field in the header that contains the group name that the gateway extracts. Any incoming request that is missing the field results in no group name being extracted and the connection is allowed.

3. Save the file.
   The gateway creates a new WAR file with modified timestamp in $gateway/data/deployments.

<provider>
    <role>federation</role>
    <name>HeaderPreAuth</name>
    <enabled>true</enabled>
    <param>
        <name>preauth.custom.header</name>
        <value>SM_USER</value>
    </param>
    <param>
        <name>preauth.ip.addresses</name>
        <value>10.10.0.*</value>
    </param>
</provider>