DPS Installation and Setup
Also available as:
loading table of contents...

Chapter 6. Configuring DPS for Secure Clusters

Before installing Hortonworks DataPlane Service (DPS), you should configure your clusters for the security options you plan to use.

Task Overview

Following is a high-level overview of the process for setting up security for DPS:

  • Copy the public key from the ssl-cert.pem certificate.

  • Create a token.xml file and add the public key.

  • Add or copy the token.xml file, with the same configuration, to all other Knox nodes in each cluster.

  • Configure Ranger for use with DPS.


  • Clusters used with DPS must have DPS version 2.6.3 installed and be managed by Apache Ambari 2.6.0 or later.

  • You need to have your corporate LDAP settings available.

Enabling DPS to Interact with HDP Clusters

DPS services, such as DLM, must communicate with services on the HDP cluster like Ambari, DLM Engine, Atlas, Ranger, etc. The services perform actions on behalf of the user logged into DPS Platform, using the Knox token service. Therefore, you must use the Knox SSO service to provide federated single sign-on authentication between DPS Platform and all clusters enabled in DPS.


Knox host IP mapping must be in the /etc/hosts file on DPS service container.

About This Task

To perform this task, you must have root user privileges on the DPS host and on all nodes that have Knox enabled.

To set up SSO for DPS, you must create a new topology file for Knox on all cluster nodes that have Knox enabled. This new topology file must be configured to contain the DPS public key, which is used to establish a trust relationship between DPS and the HDP Knox instance.


  1. In a terminal, SSH to the DPS host.

  2. Navigate to $DP_INSTALL_HOME/certs/.

    For example:

    cd /usr/dp/current/core/bin/certs/
  3. Display the content of the ssl-cert.pem file.

    For example:

    cat ssl-cert.pem
  4. Copy and retain the DPS 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:

    -----END CERTIFICATE-----
  5. Create a token.xml topology file.

    vi /etc/knox/conf/topologies/token.xml
  6. Add the required content to the token.xml file:

    1. Add the basic topology content.

      You can copy and paste the following content into the file.

      <?xml version="1.0" encoding="UTF-8"?>

      The HadoopGroupProvider provider enables the Hadoop user-group mapping, to identify the groups to which users belong.

    2. Replace $knox-hostname-FQDN with the fully qualified domain name of the host.

    3. In the sso.token.verification.pem parameter, paste in the public key value that you copied in a previous step, replacing $ADD-THE-PUBLIC-KEY-HERE.

    4. If using Ranger, also add the following content after the public key, within the gateway parameter:


      This parameter enables Ranger authorization with the token topologies in Knox.

  7. Perform a secure copy of the token.xml topology file to a Knox-enabled node on the HDP cluster.

  8. Verify that Knox has picked up the files:

    • Log in to the Knox-enabled node.

    • Ensure that a directory called token.topo.<number> is present in the path /var/lib/knox/data-<version>/deployments/.

      If the file is not present, verify that the content in the token.xml file is correct. You can check the Knox gateway logs for error information.

  9. Log in to each additional cluster used with DPS and repeat Step 5 (create a token.xml file) through Step 8 (verify copy of the file).

Next Steps

Configure Ranger to Restrict Access to DPS

More Information

Add Host Entries to the /etc/hosts File on the Container

Defining Cluster Topologies

Overview of Knox Integration with DPS

Security guide, Defining Cluster Topologies

Configure Ranger to Restrict Access to DPS

You must configure a Ranger policy for the new Knox topology, in order to restrict access to only authorized users of DPS.

  1. Navigate to the Ranger UI.

  2. Click Access Manager, and then click the Knox repository link (<cluster-name>_knox).

    <cluster-name> Policies.

  3. Click Add New Policy, and then enter the following values:

    Policy TypeAccess
    Knox Topologytoken
    Knox Service*
  4. Enter groups or user names in Select Group or Select User.

  5. Optional: Under Policy Conditions click Add Condition and enter the IP addresses of the DPS host.

    This adds an IP-based filter to ensure that only known DPS Core hosts can access cluster services through the token topology.

  6. Under Permissions, click Add Permission and select Allow.

Overview of Knox Integration with DPS

DPS enables multi-cluster data management and monitoring capabilities using several different services, such as DLM and DSS, that plug into the DPS Platform. In addition, DPS Platform provides a set of functions for all of the services that plug into DPS. This set of functions includes centralized authentication, HDP cluster registration and service endpoint discovery, and communication to data lake (cluster) services. Knox provides users and services with simplified and consistent access to clusters, data, and other services.

DPS authenticates users against a centralized identity provider in the organization, such as an LDAP or AD store. Knox ensures that those users and services are authorized to perform specific actions on the respective clusters, and propagates the identity of the user or service from DPS to the cluster services. DPS services include a deployment of Knox that is independent of all HDP clusters.

DPS and associated clusters can be in different domains, so DPS KnoxSSO cookies must be exchanged for KnoxToken responses that contain tokens. The tokens can subsequently be used as cookies for API calls to the services (Ambari, Ranger, Atlas) that accept SSO cookies but do not support trusted proxy access.

After Knox SSO configuration is completed successfully, when you log into DPS Platform, you are redirected to a Knox login screen. After you have successfully logged in through Knox, you are redirected to the URL of the SSO-enabled DPS Platform service.


Whatever URL you use the first time you log in is the URL you must continue to use, or log-in fails. For example, if you use the IP address of the DPS host first to log in, then you will not be able to log in using the FQDN of the DPS host later, and vice versa.

This is because Knox supports a whitelist of URLs to which it can validly redirect. DPS Platform automatically sets the whitelisted URL as the URL first used to access DPS. Typically, the host name is used for the URL, because using the host name simplifies administrative activities, such as replacing hardware.