Guest

Cisco Identity Services Engine

DogTag Used as an Open Source Certificate Authority Server for the ISE Configuration Example

Techzone Article content

Document ID: 116237

Updated: Jul 17, 2013

Contributed by Vivek Santuka, Cisco TAC Engineer.

   Print

Introduction

This document describes how to install and configure DogTag, an open source Certificate Authority (CA) server, to work with the Identity Services Engine (ISE) in order to onboard Bring Your Own Device (BYOD). In order to onboard BYOD devices with ISE, you must enable a Simple Certificate Enrollment Protocol (SCEP) server on a CA or a Remote Authority (RA) if Extensible Authentication Protocol-Transport Layer Security (EAP-TLS) authentication is required. Network Device Enrollment Service (NDES) on Windows 2008 R2 is the only server that is known to work with ISE that uses the correct implementation of the SCEP Request For Comments draft.

Note: This document provides steps tested in the lab. The Cisco Technical Assistance Center (TAC) cannot support the installation and configuration of DogTag. These steps are provided as is in order to present an alternate option in case you are not able to use NDES. NDES remains the only fully-supported CA/SCEP server with ISE.

Prerequisites

Requirements

Cisco recommends that you have working knowledge of CA servers and Linux.

Components Used

The information in this document is based on these software and hardware versions:

  • A host that runs Fedora 15 with Internet connectivity. DogTag 10 does not work for this purpose.
  • The Fully Qualified Domain Name (FQDN) of the host should be resolvable with a Domain Name Server (DNS).

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Install and Configure Dependencies

Install 389-DS and PHP

The main dependency of DogTag is the 389-Directory Server (DS). The rest of the dependencies are installed by Yellowdog Updater, Modified (YUM).

  1. Before you start the process, use the yum update command in order to have YUM update the system.
  2. In order to install and configure 389-DS, use this command:
    yum install 389-ds
  3. This command installs all 389-DS dependencies as well as HTTPD. In order to configure 389-DS, enter these commands.
    useradd ds389
    /usr/sbin/setup-ds.pl

    The setup-ds.pl script guides you through the configuration, and you usually can accept all the defaults. Verify the port (389 by default), the administration DN (cn=Directory Manager by default), and the administration password.
  4. In order to install PHP, enter this command:
    yum install php
  5. In order to ensure that DogTag works with ISE, run a small PHP script. These commands ensure that 389-DS and HTTPD work and are ready to start.
    service httpd start
    service dirsrv start
    chkconfig dirsrv on
    chkconfig httpd on

Install DogTag

  1. In order to install DogTag, enter this command:
    yum install pki-ca
  2. This command installs DogTag and all its dependencies. In order to configure the CA instance, enter this command.
    pkicreate    -pki_instance_root=/var/lib      \
    -pki_instance_name=ise-ca \
    -subsystem_type=ca \
    -agent_secure_port=9443 \
    -ee_secure_port=9444 \
    -ee_secure_client_auth_port=9446 \
    -admin_secure_port=9447 \
    -unsecure_port=9180 \
    -tomcat_server_port=9701 \
    -user=pkiuser \
    -group=pkiuser \
    -redirect conf=/etc/ise-ca \
    -redirect logs=/var/log/ise-ca \
    -verbose

    This command creates an instance called ISE-CA and the main ports for it are 9447 (for GUI access) and 9180 (for SCEP request). You can modify the values for your needs, but ensure that you replace the new values throughout the document. The value that you select for the -pki_instance_name option is referenced in the rest of the document as the instance-name.
  3. After the instance is created, the script provides the URL to configure the instance. Copy and paste the URL into a browser in order to continue with the configuration.

Configure DogTag

The configuration GUI is very well-designed with helpful text on every page. When you reach the PKI Hierarchy page (see Image 1), you must decide if you want this CA to be a root CA on its own or a SubCA in your current enterprise PKI setup. If you choose the first option, you can continue through each page and let the CA generate its own certificates.

                                                                     Image 1 - PKI Hierarchy page

116237-configure-dogtag-01.png

If you choose the second option and continue through the setup, you are required to generate the CA certificate from your enterprise CA on the Requests and Certificate page as shown in Image 2.

                                                                 Image 2 - Requests and Certificates page

116237-configure-dogtag-02.png

Generate a CA Certificate from the Enterprise CA

  1. Click the Step 1 link, copy the Certificate Signing Request (CSR), and have your CA sign the request. Use a template like "Subordinate Certificate Authority" so that the certificate has the correct Key Usage and Enhanced Key Usage attributes.
  2. Download the certificate from the CA in Base64-encoded format, open it in a text file, and copy the content. Click on Step 3 on the DogTag page, and paste the content there.
  3. Download the CA certificate chain in PKCS#7 Base64-encoded format, open it in a text file, and copy the content. Click on Step 2 on the DogTag page, and paste the content there.
  4. Click Apply. The page changes in order to show that the rest of the certificates were generated by the CA.
  5. Click Next, and continue with the configuration.

When you reach the end of the configuration, the server provides the command to restart the services and the URL for the Admin GUI. The process also installs an admin user certificate on your browser. You need that certificate in order to manage the CA form GUI.

Once you restart the service, log in to the CA URL, and verify that you are able to access the Agent Services section.

Enable SCEP and Finalize Setup

  1. Open the /etc/<instance-name>/CS.cfg file in a text editor, and edit this line with these values.
    ca.scep.allowedEncryptionAlgorithms=DES3
    ca.scep.allowedHashAlgorithms=SHA1,SHA256,SHA512
    ca.scep.enable=true
    ca.scep.encryptionAlgorithm=DES3
    ca.scep.hashAlgorithm=SHA256
    ca.scep.nonceSizeLimit=16
  2. Open the /var/lib/<instance-name>/profiles/ca/caRouterCert.cfg file in a text editor, and remove the value associated with the auth.instance_id= field (remove anything after the equal sign).
  3. Create a file called scepproxy.php at /var/www/html, and paste this into it:
    <?php
    $ops = $_GET['operation'];
    $msg= $_GET['message'];
    $order = array("\r\n", "\n", "\r", " ");
    $msg = str_replace($order, "", $msg);
    $msg = rawurldecode($msg);
    $msg=urlencode($msg);
    if ($ops == "GetCACaps")
    {
    echo "";
    }
    else
    {
    $url = "http://127.0.0.1/ca/cgi-bin/pkiclient.exe?operation=".$ops."&message=".$msg;
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_PORT, 9180);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    $body = curl_exec($ch);
    curl_close($ch);
    if ($ops=="PKIOperation")
    {
    header("Content-Type: application/x-pki-message");
    }
    else
    {
    header("Content-Type: application/x-x509-ca-cert");
    }
    echo $body;
    }
    ?>
  4. If you changed the unsecure port that the CA service listens on, replace the 9180 value in the previous text with the correct port number.

Verify

At this stage, you can add the CA as a SCEP server to ISE with this URL:

http://<service-ip>/scepproxy.php

The test connection option on ISE might fail, but you can save the profile, and check the Certificate Store section in order to ensure that the CA certificate was downloaded with SCEP.

Troubleshoot

This section provides information you can use to troubleshoot your configuration.

  • Some PHP versions might require that you comment out the curl_setopt($ch, CURLOPT_POST, 1); line in the scepproxy.php file. In order to comment out a line in PHP, add double forward slash (//) to the front of the line.
  • Make sure SELinux and IPTables do not cause a problem. In order to disable SELinux, use the setenforce 0 command. In order to disable iptables, use the service iptables stop command.
Updated: Jul 17, 2013
Document ID: 116237