Configuring OpsCenter for Kerberos authentication

OpsCenter can use Kerberos to authenticate to DataStax Enterprise clusters. If a DataStax Enterprise cluster uses Kerberos authentication, create and configure the OpsCenter principals before adding the cluster to OpsCenter.

When configuring OpsCenter for Kerberos authentication, create and configure the OpsCenter principals first, and then add the cluster to OpsCenter.

cluster_name.conf

The location of the cluster_name.conf file depends on the type of installation:
  • Package installations: /etc/opscenter/clusters/cluster_name.conf
  • Tarball installations: install_location/conf/clusters/cluster_name.conf

dse.yaml

The location of the dse.yaml file depends on the type of installation:
Package installations /etc/dse/dse.yaml
Tarball installations installation_location/resources/dse/conf/dse.yaml

address.yaml

The location of the address.yaml file depends on the type of installation:
  • Package installations: /var/lib/datastax-agent/conf/address.yaml
  • Tarball installations: install_location/conf/address.yaml

Prerequisites

Before configuring OpsCenter to use Kerberos authentication, configure DSE for Kerberos. The DSE documentation provides guidelines, samples, and a tutorial for configuring Kerberos with DSE.
  1. Prepare DSE nodes for Kerberos.
  2. Review the Kerberos guidelines.
  3. Complete the Kerberos tutorial.

Kerberos principal formatting 

The method of creating Kerberos principals differs depending on the type of Kerberos Key Distribution Center (KDC) server used. The following procedures are based on MIT Kerberos.

Kerberos principals must be fully qualified with a realm, which in the following examples is EXAMPLE.COM. The realm follows the @ sign in the principal, and is typically all upper case. The first part of the principal represents a specific identity in the realm, such as a user or service.

Kerberos user principals typically have a single component, plus the realm. For example, user@EXAMPLE.COM. Kerberos service principals represent programs of different types, and follow the format service/HOST@EXAMPLE.COM. The HOST is the name of the server, such as node1.example.com.

Important: In the following procedure, the format of the service principal must match the format of the information in the keytab that was created with the kadmin command. For example, if the service principal is service/HOST@EXAMPLE.COM, then the principal in the keytab must use the same format.

The Kerberos commands in this procedure use the following format. For more details on using the kadmin CLI, see the kadmin help.

kadmin -p user_name/admin
addprinc -randkey service_name/FQDN
addprinc -randkey HTTP/FQDN
quit
Parameter Description
kadmin Launch Kerberos admin shell with an administrator account that has add privileges.
addprinc Create a new service principal for the node.
-randkey Set the key of the principal to a random value.
service_name User-defined name of the service. For example, opscenterd.
FQDN The fully qualified domain name of the node. For example, node1.example.com.

Procedure

  1. Use the kinit command to obtain and cache an initial ticket-granting ticket for the admin user. Enter the password for the admin user when prompted.
    kinit cassandra/admin@dse
    Password for cassandra/admin@dse:
    where dse is the cluster to log in to.
  2. Run the kadmin command to access the kadmin CLI. Enter the password for the admin user when prompted to access the kadmin: prompt.
    kadmin
    Password for cassandra/admin@dse:
    kadmin:
  3. Create a service principal for the OpsCenter daemon (opscenterd), plus an additional principal for HTTP communication. The service principal format for OpsCenter is opscenterd/FQDN, where FQDN is the Fully Qualified Domain Name of the OpsCenter node. The following example uses opscenterd as the principal name, but can be any valid name.
    Note: If configuring high availability for OpsCenter, a principal must be created for the OpsCenter primary and backup instances.
    kadmin: addprinc -randkey opscenterd/node1.example.com
    kadmin: addprinc -randkey HTTP/node1.example.com
    
  4. Create a shared principal for the OpsCenter DataStax agents, or create one principal per agent. The service principal format for the DataStax agent node is dxagent/FQDN, where FQDN is the Fully Qualified Domain Name of the DataStax agent node. The following example uses dx-agent as the principal name, but can be any valid name.
    Important: If creating one principal for each DataStax agent, manually update the kerberos_client_principal property for each agent in address.yaml.
    kadmin: addprinc -randkey dx-agent/node2.example.com
    kadmin: addprinc -randkey HTTP/node2.example.com
  5. Verify that the principals have been added by running the listprincs command with kadmin.
    kadmin: listprincs
    HTTP/node1.example.com@EXAMPLE.COM
    HTTP/node2.example.com@EXAMPLE.COM
    opscenterd/node1.example.com@EXAMPLE.COM
    dx-agent/node2.example.com@EXAMPLE.COM
    kadmin/admin@EXAMPLE.COM
    where node*.example.com is the FQDN and EXAMPLE.COM is the Kerberos realm, which must be all uppercase.
  6. Create a Cassandra user for the OpsCenter daemon principal. The CQL role must be the same as the principal name created in 3. In this example, the principal name and the CQL role name is opscenterd.
    CREATE ROLE 'opscenterd/node1@EXAMPLE.COM' WITH LOGIN = true;
    
  7. Create corresponding Cassandra users for all DataStax agent principals created in 4. The CQL role name must be the same as the principal name. In this example, dx-agent is both the principal name and the CQL role name.
    CREATE ROLE 'dx-agent/node1@EXAMPLE.COM' WITH LOGIN = true;
    
    CREATE ROLE 'dx-agent/node2@EXAMPLE.COM' WITH LOGIN = true;
    
    CREATE ROLE 'dx-agent/node3@EXAMPLE.COM' WITH LOGIN = true;
    
    To view the roles that were created on the node, run the LIST ROLES command in cqlsh.
    LIST ROLES
    EXIT
  8. Use the kadmin CLI to create two keytab files that map to the previously created principals: one for the OpsCenter node, and one for DataStax agents. If using one principal for each DataStax agent, create one keytab for each.

    The keytab file is used to store the Kerberos principals created in the previous steps.

    kadmin: ktadd -k /tmp/krb5_opsc.keytab opscenterd/node1.EXAMPLE.COM
    
    kadmin: ktadd -k /tmp/krb5_agent.keytab dx-agent/node1.EXAMPLE.COM
    
    kadmin: ktadd -k /tmp/krb5_agent.keytab dx-agent/node2.EXAMPLE.COM
    
    kadmin: ktadd -k /tmp/krb5_agent.keytab dx-agent/node3.EXAMPLE.COM
    
    kadmin: quit

    To obtain principal information (outside of kadmin), use the klist command. In the following example, the command requests the ticket from the krb5_opsc.keytab file.

    klist -kt krb5_opsc.keytab
    Keytab name: FILE:krb5_opsc.keytab
    KVNO Timestamp           Principal
    ---- ------------------- ----------------------------
    2    01/26/2018 18:16:18 opscenterd/node1.EXAMPLE.COM
  9. On the OpsCenter node and on each node running a DataStax agent, create a directory to store the keytab files. The recommended directory on each node is /etc/opscenter/security.
    mkdir /etc/opscenter/security
  10. Copy the generated keytab files to location created in 9. For example, /etc/opscenter/security/krb5_opsc.keytab.
    scp /tmp/krb5_opsc.keytab opscenterd@node1.EXAMPLE.COM:/etc/opscenter/security
    scp /tmp/krb5_agent.keytab dx-agent@node1.EXAMPLE.COM:/etc/opscenter/security
    scp /tmp/krb5_agent.keytab dx-agent@node2.EXAMPLE.COM:/etc/opscenter/security
    scp /tmp/krb5_agent.keytab dx-agent@node3.EXAMPLE.COM:/etc/opscenter/security
    The keytab locations are set in the following properties in the cluster_name.conf file after adding the cluster to OpsCenter in 12.
  11. Change the owner of the keytabs and the keytabs directory for OpsCenter and the DataStax agent.
    Replace the directory paths with the keytab locations created in the previous step.
    sudo chown cassandra /etc/opscenter/security \
    /etc/opscenter/security/krb5_opsc.keytab
    sudo chown cassandra /usr/agent/conf \
    /usr/agent/conf/krb5_agent.keytab
    
  12. Add the cluster to OpsCenter. The user adding the cluster to OpsCenter must have privileges on the DSE node to add the cluster.
    Note: When adding the cluster, select DSE security (kerberos) is enabled on my cluster and input the required information.
    DSE security (Kerberos) enabled configuration settings for OpsCenter connections
    1. Enter the Service Name. This name must match the user name of the Kerberos service used by DSE, which is defined in dse.yaml. For example, if the server principal is dse/HOST@EXAMPLE.COM, the Service Name should be dse.
      kerberos_options:
      ...
      service_principal: dse/HOST@EXAMPLE.COM
    2. Enter the Opscenterd Client Principal created in 3.
      For example: opscenterd/opscenterd.EXAMPLE.COM
    3. Enter the Opscenterd Keytab Location location created in 8. This keytab contains credentials for the opscenter_client_principal.
      For example: /etc/opscenter/security/krb5_opsc.keytab.
    4. Enter the DataStax Agent Client Principal created in 4.
      For example: kerberos_client_principal: dx-agent/node1@EXAMPLE.COM
      Important: If using a different principal for each DataStax agent, the value entered in this field is a placeholder only. Because each DataStax agent has a different principal name, set the kerberos_client_principal property in address.yaml for each DataStax agent.
    5. Enter the DataStax Agent Keytab Location location created in 8. This keytab contains credentials for the agent_client_principal.
      For example: /etc/opscenter/security/krb5_agent.keytab
  13. After specifying the Kerberos information, click Next and complete the remaining prompts to add the node to OpsCenter.
  14. If different principals were created for each DataStax agent in 4, restart each agent.

Results

After the cluster is added to OpsCenter, the values entered for each field are saved in a configuration file specific to the cluster. The file is created as /etc/opscenter/clusters/cluster_name.conf.