Configure Knox SSO for DataPlane

This topic provides an overview of how to configure Knox SSO in your cluster to work with DataPlane. Refer to the Hortonworks Data Platform or Hortonworks DataFlow documentation for details that might be applicable to your specific cluster configuration and setup.

	Note
	As part of configuring Knox SSO to work with DataPlane, you will be setting up Knox topologies for token exchanges to allow your DP instance to communicate and handle SSO requests. It is strongly recommended that in your cluster, you configure Ranger to restrict access to these token topologies to be only from your DP instance. See Configure Ranger in your Cluster section for more information.

You will be configuring Knox SSO in your cluster to work with your DP instance.

You must have installed and configured DataPlane.

Minimally, Knox SSO should be configured for Ambari.

	Note
	If you are using Ambari 2.7 or later, Ambari provides a helper “setup-sso” command to simplify the setup of Knox SSO for Ambari and certain cluster services. Refer to the Ambari Security Guide for more information.

Knox host FQDN must be DNS addressable and available from your DataPlane environment. If your Knox configuration is setup for High Availability (HA) with more than one Knox instance running behind a proxy, the FQDN/IP of that proxy must be DNS addressable and available from your DataPlane environment.
If it is not, the Knox IP address must be in the /etc/hosts file on the DP environment. Refer to the DP Administration Guidefor details on how to add Knox to the DataPlane environment hosts.
You must have an SSL certificate (such as a .pem file) available and have access to the public key in the file.

	Note
	Use the following information to register the cluster in DataPlane. Currently, DataPlane does not allow changing the value of cookie to anything other than `hadoop-jwt`. This value is used internally by DataPlane. `<param><name>knox.token.client.data</name>` `<value>cookie.name=hadoop-jwt</value></param>`

In a terminal, SSH to the DP host.
Navigate to $DP_INSTALL_HOME/certs/.
```
cd /usr/dp/current/core/bin/certs/
```
Display the content of the ssl-cert.pem file.
```
cat ssl-cert.pem
```

Copy and retain the DataPlane public key displayed in the certificate between “Begin Certificate” and “End Certificate”, because you need it in a succeeding step.

The public key looks similar to the following:

-----BEGIN CERTIFICATE-----


MIIEpDCCAowCCQDgyOmhg8r5wjANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDDAlk
YXRhcGxhbmUwHhcVEBgwNjA2MDMzMzEyWhcNMTkwNjA2MDMzMzEyWjAUMRIwEAYD
VQQDDAlkYXRhcGxhbmUwggIiMYu7ncDA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAo
fTf6/5drxlYa5EeHDetQo3I50Vx+Tj9jpd8t1x+3zJMO3xI6UCtHFiZlxS8IToTw
V2BEOPH1K7qqRQjTagZtqNU7JNiEouBxO+lRYXdyaqhCIIUcgspsop9W5C9T2aM6
HWx73MapoP5r4dRTpYCITWJW7GkvJGhplIK51MhWD2dL9+bzsZ/sY9nwGJ2iUZ39
VGKMRC8TQlR2uwmRl2GziOCjMrfJIDDBxNm2xCbpYbNo8prle2EcntLgrw/EBNyA
Fbp8a506gL7TbbjnqFM4iHhr7vVzbOzl14Qci+GLdTl51yNLER1k5sC/TEFpKBXP
IcY8UOuU6bbXrF/ZYR5FjYu7ncDOp0wDLz0lmLPwU27tE9D9SR+k0PYo8xvLIw31
iPsw0UuF4ouWJI9UaZ2i0vGJJcU8TtH7cOEyUL+wv0sCNHp5eI1hXgdCTkyFZv7s
2xWNA12L0TSd/49nHA9fIrXHYp5inmHrJiRP4wJlxFDvbZFltFepaG4I2pWhdrwY
2Sj0G084J294FNLad2xpoIacwaKWzdJ6HTvYo09Pqiu0YAchGicGCjwUU0omeK61
mZRmwENGYlzKXsrBAAGU1QuzZTFevA36d71iCcTZOwKp7KeHL0e8RJ7fTfgEXvRT
WzmnVdOCfpflmaXoVhyATIRVAF5RDdnYdK+QUPDpVwIDAQABMA0GCSqGSIb3DQEB
ViNN1eA4ICAQCNpcF0UJVAs7OhAf3DE2IjdWoiiUUr1x8jt5icWOS48Mw8mM9ADd
tGZ3IMrSB3qerixBN7tlFS/NCTXvS78imNXJT5xnJvNUYekWj/uLi4Vh9/Vg/l/2
zm7uLn5gTLwzDr9QGUF8Hb7+o/nW3pYLwrSoay5ApIysMd/mOykzFuLf4P7CHOMe
cFImfN82xSD46W2zLbW/aJ5jdwXRa27L075TA91sqRRO0tObn+vCBgsehvT1EBFy
U7puKS9fv2QHMS7rmt3ixhWw5AJ8wG9D4/nJq0cJhIKaqiDn9nqGiY8GBUwa/YAc
tAuIqo+LcvoIr/J+yc+7SXxDJXM+SlbS+lA0Fp/EdIMuDbey2T6Sabor4khzi78E
PeCBKHnZ2V8MTtcAXKw6RTSToBhIGozm9oRGU1xfT61xAein+ba4UH1yZUanna7o
NbRQIKjSYC48oxYyWEA6HlZbTjy/uaBU3WP78mcoYUfFronK7fGkGvB8+xMYlYc+
aM1t87Z/KpY2d2CtDEG6qMl5wWTJqwocN5cYNwubgJM8vt1uD1IhsezHjr1Tuv1x
988ztA/raNLF921ZAc5W1Xly5JF4z1lhZQZqDBpMsdo05HWKU4bgdLLoCN7bFVPX
Sclm0TtyUSXblXfPqXqBfnPJNiimmLk1+SmOxX9h+dOHfcNMsSNa5g==

-----END CERTIFICATE-----

On your cluster Knox host, create three topology files - token.xml, redirect.xml, and redirecttoken.xml topology files.

vi /etc/knox/conf/topologies/token.xml

vi /etc/knox/conf/topologies/redirect.xml

vi /etc/knox/conf/topologies/redirecttoken.xml

	Note
	The `redirecttoken.xml` topology file should be exactly same as the `token.xml` topology file. For security purposes, the TTL of the token should be kept very low. It is recommended to keep the value at 10 seconds.

Add the required content to the token.xml file on each cluster host running a Knox instance:

Add the basic topology content.

You can copy and paste the following content into the file and modify the content as needed.


<?xml version="1.0" encoding="UTF-8"?>
<topology>
   <uri>https://$KNOX_HOSTNAME_FQDN:8443/gateway/token</uri>
   <name>token</name>
   <gateway>
      <provider>
         <role>federation</role>
         <name>SSOCookieProvider</name>
         <enabled>true</enabled>
         <param>
            <name>sso.authentication.provider.url</name>
            <value>https://$KNOX_HOSTNAME_FQDN:8443/gateway/knoxsso/api/v1/websso</value>
         </param>
         <param>
            <name>sso.token.verification.pem</name>
            <value>
                $ADD_THE_PUBLIC_KEY_HERE
            </value>
         </param>
      </provider>
      <provider>
         <role>identity-assertion</role>
         <name>HadoopGroupProvider</name>
         <enabled>true</enabled>
      </provider>
      
   </gateway>

   <service>
      <role>KNOXTOKEN</role>
      <param>
         <name>knox.token.ttl</name>
         <value>100000</value>
      </param>
      <param>
         <name>knox.token.client.data</name>
         <value>cookie.name=hadoop-jwt</value>
      </param>
      <param>
         <name>main.ldapRealm.authorizationEnabled</name>
         <value>true</value>
      </param>
   </service>
</topology>

Provide the following details in the topology file:


Property	Values	Description
`sso.token.verification.pem`	Certificate	Paste in the public key value that you copied in a previous step, replacing $ADD_THE_PUBLIC_KEY_HERE (be sure to exclude the BEGIN CERTIFICATE and END CERTIFICATE text).
`knox.token.ttl`	milliseconds	Expiry time of the token. A value of -1 means no expiry. For security purposes, the TTL of the token should be kept very low. It is recommended to keep the value at 10 seconds (10000).
`sso.authentication.provider.url`	Knox SSO URL	The URL to your cluster Knox SSO endpoint. Replace $KNOX_HOSTNAME_FQDN with the fully qualified domain name of the host.
`identity-assertion`	true \| false	Enables the “HadoopGroupProvider” Hadoop user-group mapping, which identifies the groups to which users belong

	Note
	The `authorization=XASecurePDPKnox` parameter and `main.ldapRealm.authorizationEnabled=true` parameter enable Ranger authorization with the token topologies in Knox.

Add the required content to the redirect.xml file on each cluster host running a Knox instance:

Add the basic topology content.
You can copy and paste the following content into the files and modify the content as needed.

<topology>
    <name>tokensso</name>
    <gateway>
        <provider>
            <role>federation</role>
            <name>JWTProvider</name>
            <enabled>true</enabled>
        </provider>
        <provider>
            <role>identity-assertion</role>
            <name>Default</name>
            <enabled>true</enabled>
        </provider>
    </gateway>
    <service>
        <role>KNOXSSO</role>
        <param>
            <name>knoxsso.cookie.secure.only</name>
            <value>true</value>
        </param>
        <param>
            <name>knoxsso.token.ttl</name>
            <value>600000</value>
        </param>
        <param>
            <name>knoxsso.redirect.whitelist.regex</name>
            <value>^https?:\/\/(DOMAIN_OF_CLUSTER|localhost|127\.0\.0\.1|0:0:0:0:0:0:0:1|::1):[0-9].*$</value>
        </param>
    </service>
</topology>

Provide the following details in the topology file:


Property	Values	Description
`knoxsso.cookie.secure`	true \| false	This sets if a session cookie is require or not. If your cluster Ambari is configured for SSL, then set this value to true. Otherwise, set to false.This value is true if the secure cookie is required.
`knox.token.ttl`	milliseconds	Expiry time of the token. A value of -1 means no expiry.
`knoxsso.redirect.whitelist.regex`	regex	This should have the regex which matches the URL in the to or original Url query parameter for the two separate calls. Be sure to replace “DOMAIN_OF_CLUSTER” in the example regex provided.

Verify that Knox has picked up the files:
1. Log in to the Knox-enabled node.
2. Ensure that a directory called token.topo.<number> is present in the path /var/lib/knox/data-<version>/deployments/.
  If the files are not present, verify that the content in the token.xml file is correct. You can check the Knox gateway logs for error information.