:original_name: mrs_07_020001.html

.. _mrs_07_020001:

Security Authentication Principles and Mechanisms
=================================================

Function
--------

For clusters in security mode with Kerberos authentication enabled, security authentication is required during application development.

Kerberos, named after the ferocious three-headed guard dog of Hades from Greek mythology, is now used to a concept in authentication. The Kerberos protocol adopts a client-server model and cryptographic algorithms such as AES (Advanced Encryption Standard). It provides mutual authentication, that is, both the client and the server can verify each other's identity. Kerberos is used to prevent interception and replay attacks and protect data integrity. It is a system that manages keys by using a symmetric key mechanism.

Architecture
------------

Kerberos architecture is shown in :ref:`Figure 1 <mrs_07_020001__en-us_topic_0269458072_f203af1d5f55e4832ba0f6891e6c38839>` and module description in :ref:`Table 1 <mrs_07_020001__en-us_topic_0269458072_t16ccb1745d994539a7b6d7b4d728ff02>`.

.. _mrs_07_020001__en-us_topic_0269458072_f203af1d5f55e4832ba0f6891e6c38839:

.. figure:: /_static/images/en-us_image_0000001349137697.png
   :alt: **Figure 1** Kerberos architecture

   **Figure 1** Kerberos architecture

.. _mrs_07_020001__en-us_topic_0269458072_t16ccb1745d994539a7b6d7b4d728ff02:

.. table:: **Table 1** Module description

   +--------------------+--------------------------------------------------------------------------------------------+
   | Module             | Description                                                                                |
   +====================+============================================================================================+
   | Application Client | An application client, which is usually an application that submits tasks or jobs          |
   +--------------------+--------------------------------------------------------------------------------------------+
   | Application Server | An application server, which is usually an application that an application client accesses |
   +--------------------+--------------------------------------------------------------------------------------------+
   | Kerberos           | A service that provides security authentication                                            |
   +--------------------+--------------------------------------------------------------------------------------------+
   | KerberosAdmin      | A process that provides authentication user management                                     |
   +--------------------+--------------------------------------------------------------------------------------------+
   | KerberosServer     | A process that provides authentication ticket distribution                                 |
   +--------------------+--------------------------------------------------------------------------------------------+

The process and principle are described as follows:

An application client can be a service in a cluster or a secondary development application of the customer. An application client can submit tasks or jobs to an application service.

#. Before submitting a task or job, the application client needs to apply for a ticket granting ticket (TGT) from the Kerberos service to establish a secure session with the Kerberos server.
#. After receiving the TGT request, the Kerberos service resolves parameters in the request to generate a TGT, and uses the key of the username specified by the client to encrypt the response.
#. After receiving the TGT response, the application client (based on the underlying RPC) resolves the response and obtains the TGT, and then applies for a server ticket (ST) of the application server from the Kerberos service.
#. After receiving the ST request, the Kerberos service verifies the TGT validity in the request and generates an ST of the application service, and then uses the application service key to encrypt the response.
#. After receiving the ST response, the application client packages the ST into a request and sends the request to the application server.
#. After receiving the request, the application server uses its local application service key to resolve the ST. After successful verification, the request becomes valid.

Basic Concepts
--------------

The following concepts can help users learn the Kerberos architecture quickly and understand the Kerberos service better. The following uses security authentication for HDFS as an example.

**TGT**

A TGT is generated by the Kerberos service and used to establish a secure session between an application and the Kerberos server. The validity period of a TGT is 24 hours. After 24 hours, the TGT expires automatically.

The following describes how to apply for a TGT (HDFS is used as an example):

#. Obtain a TGT through an API provided by HDFS.

   .. code-block::

      /**
        * login Kerberos to get TGT, if the cluster is in security mode
        * @throws IOException if login is failed
        */
        private void login() throws IOException {
        // not security mode, just return
          if (! "kerberos".equalsIgnoreCase(conf.get("hadoop.security.authentication"))) {
              return;
          }

          //security mode
          System.setProperty("java.security.krb5.conf", PATH_TO_KRB5_CONF);

          UserGroupInformation.setConfiguration(conf);
          UserGroupInformation.loginUserFromKeytab(PRNCIPAL_NAME, PATH_TO_KEYTAB);
        }

#. Run shell commands on the client in kinit mode.

**ST**

An ST is generated by the Kerberos service and used to establish a secure session between an application and application service. An ST is valid only once.

In FusionInsight products, the generation of an ST is based on the Hadoop-RPC communication. The underlying RPC submits a request to the Kerberos server and the Kerberos server generates an ST.

Sample Authentication Code
--------------------------

.. code-block::

   import java.io.IOException;

   import org.apache.hadoop.conf.Configuration;
   import org.apache.hadoop.fs.FileStatus;
   import org.apache.hadoop.fs.FileSystem;
   import org.apache.hadoop.fs.Path;
   import org.apache.hadoop.security.UserGroupInformation;

   public class KerberosTest {
       private static String PATH_TO_HDFS_SITE_XML = KerberosTest.class.getClassLoader().getResource("hdfs-site.xml")
               .getPath();
       private static String PATH_TO_CORE_SITE_XML = KerberosTest.class.getClassLoader().getResource("core-site.xml")
               .getPath();
       private static String PATH_TO_KEYTAB = KerberosTest.class.getClassLoader().getResource("user.keytab").getPath();
       private static String PATH_TO_KRB5_CONF = KerberosTest.class.getClassLoader().getResource("krb5.conf").getPath();
       private static String PRNCIPAL_NAME = "develop";
       private FileSystem fs;
       private Configuration conf;

       /**
        * initialize Configuration
        */
       private void initConf() {
           conf = new Configuration();

           // add configuration files
           conf.addResource(new Path(PATH_TO_HDFS_SITE_XML));
           conf.addResource(new Path(PATH_TO_CORE_SITE_XML));
       }

       /**
        * login Kerberos to get TGT, if the cluster is in security mode
        * @throws IOException if login is failed
        */
       private void login() throws IOException {
           // not security mode, just return
           if (! "kerberos".equalsIgnoreCase(conf.get("hadoop.security.authentication"))) {
               return;
           }

           //security mode
           System.setProperty("java.security.krb5.conf", PATH_TO_KRB5_CONF);

           UserGroupInformation.setConfiguration(conf);
           UserGroupInformation.loginUserFromKeytab(PRNCIPAL_NAME, PATH_TO_KEYTAB);
       }

       /**
        * initialize FileSystem, and get ST from Kerberos
        * @throws IOException
        */
       private void initFileSystem() throws IOException {
           fs = FileSystem.get(conf);
       }

       /**
        * An example to access the HDFS
        * @throws IOException
        */
       private void doSth() throws IOException {
           Path path = new Path("/tmp");
           FileStatus fStatus = fs.getFileStatus(path);
           System.out.println("Status of " + path + " is " + fStatus);
           //other thing
       }


       public static void main(String[] args) throws Exception {
           KerberosTest test = new KerberosTest();
           test.initConf();
           test.login();
           test.initFileSystem();
           test.doSth();
       }
   }

.. note::

   #. During Kerberos authentication, you need to configure the file parameters required for configuring the Kerberos authentication, including the keytab path, Kerberos authentication username, and the **krb5.conf** configuration file of the client for Kerberos authentication.
   #. Method **login()** indicates calling the Hadoop API to perform Kerberos authentication and generating a TGT.
   #. Method **doSth** indicates calling the Hadoop API to access the file system. In this situation, the underlying RPC automatically carries the TGT to Kerberos for verification and then an ST is generated.
