Configuring certificate enrollment for the gateway

Follow these steps to configure certificate enrollment for the Blue Cedar Connect Gateway using the command-line interface (CLI):

Note: For ease in configuring certificate enrollment, please commit your changes after you have configured all the settings. (This is the last step in this list.) You can commit some of the changes before completing this procedure, but you may get an error message saying the commit failed. This error occurs because some steps in this procedure have dependencies on other steps before the changes can be committed. For this reason, Blue Cedar recommends that you commit changes at the end of this procedure.

Enable certificate enrollment.

BASH

% set aaa auth-group groupname certificate-enrollment enabled true

Choose an enrollment protocol—SCEP or EST (Enrollment over Secure Transport).

SCEP option: Provide the location of the SCEP server that the gateway uses to forward a Certificate Signing Request. This example uses EJBCA as enrollment infrastructure.

BASH

% set aaa auth-group groupname certificate-enrollment scep-url http://scep.example.com:8080/ejbca/publicweb/apply/scep/pkiclient.exe 
% commit
Commit succeeded.

EST option: Choose EST as the protocol, provide the URL of the EST server, and provide the RA certificate:

BASH

% set aaa auth-group groupname
  certificate-enrollment identity-cert-name estId 
% set aaa auth-group groupname
  certificate-enrollment enrollment-protocol est 
% set aaa auth-group groupname
  certificate-enrollment est url https://est.example.com:8085/.well-known/est/simpleenroll

If you do not specify an RA certificate, you can provide an optional username/password to authenticate to the server:

BASH

% set aaa auth-group groupname certificate-enrollment enrollment-protocol est 
% set aaa auth-group groupname certificate-enrollment est url https://est.example.com:8085/.well-known/est/simpleenroll 
% set aaa auth-group groupname certificate-enrollment est username estuser 
% set aaa auth-group groupname certificate-enrollment est password estpwd
% show aaa auth-group default certificate-enrollment est 
est {
  url https://est.example.com:8085/.well-known/est/simpleenroll;
  username estuser;
  password TU9DREFSAAITad2q8OnXgwgFrOpX/5Vy2gAAAAAAAAAHKnB+wgG15rrR3anfHxNn2gwnr
  4s6pklakDbXv+cc14RYXD/sQ7Gi/ppCsYodMc6Ua78XT9MzylLACFQHXxyC7XlGuNDr6oUfcf+858l
  0Yi56HxDxjnf2S3ZZX4NyXGv5zfykOtWKEWXppjMQux+andX7d7Ss5+fyBD9+taQBqcjjD/bMJRmSW
  yYGXkbv1msuoyzsmu9OdG30V5AOs4DfAaR6lSQ6D4rerBkpQj+s6rPFke/saL14ttZUZnaXXuMP8bU
  gAmKbDuaUXb/XE5/d7gpgBCMFNy9r7M4dyPJ4U6+dZs+CHaZqzshQo+8derO71XefdGT26mp5riLck
  u7Yresrqan/BF0y71WJL7jsfNTLBnqKFWwEL3QE0zqOOKE=;
}

(optional) If your SCEP server requires an identity certificate for mutual authentication, use the defined name. (See "Defining identity certificates" in Configuring AAA Public Key Infrastructure.)

BASH

% set aaa auth-group groupname certificate-enrollment identity-cert-name certname

(optional) If you are using Microsoft NDES with the gateway for certificate enrollment, enter this command line to configure it (using ms-ndes-2008 or ms-ndes-2012):

BASH

% set aaa auth-group groupname certificate-enrollment scep-server-type ms-ndes-2012
% commit

Configure the gateway for Certificate Signing Request (CSR) templates.

Before the gateway forwards a CSR from an app to a Certificate Authority, the values for a Certificate Signing Request must be accurate and in the correct format. The template is:

BASH

% set aaa auth-group groupname certificate-enrollment request-template

Use the following CLI commands to set the required parameters for a CSR. Use quotation marks to enclose any multiple-word entry. For example, "New York".

Field	Description and syntax
challenge-password	Challenge password (required for single-password mode) If you are not using NDES one-time challenge password, set the challenge-password here. Note: This password MUST match the challenge password for your CA (Entrust) or RA (Microsoft NDES). This is a required parameter. In the Certificate Signing request template, you must enter the same challenge password that was configured for the SCEP server (which is Entrust or NDES)—otherwise the authentication between the gateway and Entrust fails. BASH `% set aaa auth-group groupname certificate-enrollment request-template challenge-password string`
country-code	Two-letter (ISO) country code BASH `% set aaa auth-group groupname certificate-enrollment request-template country-code US`
key-type	Algorithm and keylength for certificates. Possible values: rsa1024 rsa2048 BASH `% set aaa auth-group groupname certificate-enrollment request-template key-type rsa2048`
locality	US city or locality (Full name only. No abbreviations.) BASH `% set aaa auth-group groupname certificate-enrollment request-template locality "Des Moines"`
state	State (Full name only. No abbreviations.) BASH `% set aaa auth-group groupname certificate-enrollment request-template state Iowa`
organization	Organization BASH `% set aaa auth-group groupname certificate-enrollment request-template organization "Acme, Inc."`
organizational-unit	Organizational unit BASH `% set aaa auth-group groupname certificate-enrollment request-template organizational-unit "Human Resources"`
san-othername-upn	Active Directory User Principal Name (Optional.) Use the variable %AD_UPN% to embed the Active Directory UPN into the "otherName" field of the Subject Alternative Name certificate extension. Use the variable %UPN% to embed custom attributes from LDAP into the "otherName" field. If use-san-uri is enabled, san-othername-upn is ignored; only the SAN_URI is used in the certificate generated by the server. BASH `% set aaa auth-group groupname certificate-enrollment request-template san-othername-upn %AD_UPN%`
use-fedkey-in-common-name	Use the common name DN (distinguished name) attribute to uniquely identify the user/device/federation. BASH `% set aaa auth-group groupname certificate-enrollment request-template use-fedkey-in-common-name true`
use-san-uri	Use the Subject Alternative Name URI field that uniquely identifies the user/device/federation. If use-san-uri is enabled (set to true) and san-othername-upn is configured for either %AD_UPN% or %UPN%, only the SAN_URI is returned under the SAN in the certificate generated by the server. If you really want to use %AD_UPN% or %UPN% in the certificate generated by the server, disable use-san-uri (set to false). BASH `% set aaa auth-group groupname certificate-enrollment request-template use-san-uri true`

Configure the gateway to forward the enrollment PIN to an email server.

Note: This step is optional if you have chosen not to enable the enrollment PIN feature. If this is the scenario, skip to Step 9.

In this procedure, you configure the gateway to:

Connect to an email server that sends out the email with the enrollment PIN. This is the purpose of configuring the smtp-port and smtp-server parameters.
Specify the email address that appears in the “From” field of the email that contains the enrollment PIN. (In the prerequisites section, you already created an administrator email account on your email server. Enter this email address as the value for the “admin-email” parameter. The email address is what a device user uses to ask any support questions or problems.)

Use the following parameters to configure the SMTP server and email address that the gateway forwards the enrollment PIN to:

Description	Syntax example
Email address for forwarding the enrollment PIN	BASH `% set system email admin-email admin@fauxcorp.net`
Port to be used by mail server for communication	BASH `% set system email smtp-port 25`
SMTP server for sending out the email	BASH `% set system email smtp-server mail.acme.com`

To enable the enrollment PIN email and customize the email your end users receive, see Customizing the enrollment PIN email.

(Optional) Enable certificate-only authentication.

Certificate-only authentication separates the establishment of a gateway connection from possession of enterprise credentials. This allows the client to use a user-created PIN to access a secured app instead of relying on a difficult-to-enter enterprise password, and the gateway treats a validated client certificate by itself as a sufficient credential for authentication.

BASH

% set aaa auth-group groupname certificate-only-auth allowed

To disable certificate-only authentication:

BASH

% set aaa auth-group groupname certificate-only-auth disabled

Configure the chain of trust depth.

Depending on your PKI infrastructure, you may need to configure the depth of the chain of trust. By default, the depth is set to 2, which includes the root and one intermediate certificate. For the gateway to authenticate the client certificate, it needs the whole certificate authority's trust chain configured under trusted certificates. If your certificate authority has more than two intermediate certificates, increase the trust-verify-depth number so that the client certificate can succeed:

BASH

% set system https trust-verify-depth number

(Optional) Enable username extraction.

After enrolling a client certificate, the gateway can pre-fill the username field in credential prompts with the value of the username in the certificate. When username extraction is enabled, once users are enrolled, they do not have to re-type the username when re-authenticating to the app. To enable this username extraction:

BASH

% set aaa auth-group groupname extract-username-from-certificate enabled

To disable username extraction:

BASH

% set aaa auth-group groupname extract-username-from-certificate disabled

Commit your changes.

The configuration of the gateway for certificate enrollment is complete. You can now test the certificate enrollment on an end-user device to confirm that it has been enrolled by the gateway.

BASH

% commit