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.
% 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.
% set aaa auth-group groupname certificate-enrollment scep-url http://scep.example.com:8080/ejbca/publicweb/apply/scep/pkiclient.exe
EST option: Choose EST as the protocol, provide the URL of the EST server, and provide the RA certificate:
% 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:
% 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
(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.)
% 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):
% set aaa auth-group groupname certificate-enrollment scep-server-type ms-ndes-2012
.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:
% 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".
|Description and syntax
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.
Two-letter (ISO) country code
Algorithm and keylength for certificates.
US city or locality (Full name only. No abbreviations.)
State (Full name only. No abbreviations.)
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.
Use the common name DN (distinguished name) attribute to uniquely identify the user/device/federation.
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).
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:
|Email address for forwarding the enrollment PIN
|Port to be used by mail server for communication
|SMTP server for sending out the email
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.
% set aaa auth-group groupname certificate-only-auth allowed
To disable certificate-only authentication:
% 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:
% 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:
% set aaa auth-group groupname extract-username-from-certificate enabled
To disable username extraction:
% 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.