ºÚÁϺ£½Ç91Èë¿Ú

Overview

This article covers how to use the PowerShell Automation scripts to generate and deploy certificates for use with passwordless or certificate-based authentication (CBA) to RADIUS. These scripts replace the self-signed Certificate creation OpenSSL process, which without these scripts has to be done manually per user. The details are given in the RADIUS-CBA Tools for BYO Certificates white paper (PDF attachment; see files section on right).

Prerequisites

• PowerShell 7.x.x ( )
• Before using these scripts, admins need to perform a one-time-only OpenSSL 3.x.x download and setup.
  • This process can be found in the appendix of the RADIUS-CBA tools for BYO Certificates Whitepaper (PDF attachment; see files section on right).
  • See macOS/ Windows Requirements below
  • This process is not compatible on Linux
• Certificate Authority (CA) - either from a vendor or self-generated

System Requirements

macOS Requirements

macOS ships with a version of OpenSSL titled LibreSSL. LibreSSL is sufficient to generate the usernameCN and emailDN type certificates but not the emailSAN type certificate (due to the inclusion of x509 subject headers in the certificate body). 
Because of this, a distribution of OpenSSL 3.x.x is required to run these scripts. While running the application, you'll be prompted to locate Openssl 3.x.x if it is not found.

• To install the latest version of OpenSSL on mac, install the and install the following

Some packages or applications in macOS rely on the pre-configured LibreSSL distribution. To use the Homebrew distribution of OpenSSL in this project, simply change the $openSSLBinary variable to point to the Homebrew bin location ex:

• In Config.ps1 change $opensslBinary to point to /usr/local/Cellar/openssl@3/3.0.7/bin/openssl
• ex: $opensslBinary = /usr/local/Cellar/openssl@3/3.0.7/bin/openssl

Windows Requirements

Windows does not typically ship with a preconfigured version of OpenSSL but a pre-compiled version of OpenSSL can be installed from . These automations have been tested with the full installer (not the Light) version of the tool. OpenSSL can also be downloaded and configured from if desired.
If the pre-compiled version of OpenSSL was installed, the OpenSSL should be installed in C:\Program Files\OpenSSL-Win64\bin\. There should exist an openssl.exe binary in that directory. In addition, there should also exist a legacy.dll file in that same directory which is required if generating $emailSAN user certificates.
To set the required system environment variables for this automation:

• Open Control Panel
• Select Edit the system environment variables
• Under the System Properties window and Advanced tab, select the Environment Variables... box.
• Under the User Variables for yourAccount click the New... box
  • Set the Variable Name to: OPENSSL_MODULES
  • Set the Variable Value to: C:\Program Files\OpenSSL-Win64\bin or the location of the legacy.dll file included in your OpenSSL distribution
  • Click OK.
• Under the System variables section scroll down to the Path variable, select it and click Edit...
  • Add a new line entry for this variable and type C:\ProgramFiles\OpenSSL-Win64\bin or the location of the openssl.exe file included in your OpenSSL distribution.
  • Click OK.
  • Click OK to close and save the Environment Variables dialog box.
• Click OK to close and save the System Properties dialog box.

The openssl command should be available in new PowerShell terminal windows.

Configure EAP-TLS for RADIUS

Run the ‘Start-RadiusDeployment’ script

The set of automations described in this document are invoked by the menu-based powershell automation script `Start-RadiusDeployment`. This automation script provides a text based user interface for generating a CA, generating user certificates, distributing user certificates (via ºÚÁϺ£½Ç91Èë¿Ú Commands) and monitoring the deployment status.
Before running the `Start-RadiusDeployment` automation script, the variables within the configuration file `config.ps1` must first be updated.

Edit the RADIUS Configuration file

1. Open the config.ps1 file with a text editor.
2. Set your API Key ID: change the variable $JCAPIKEY to an API Key from an administrator in your ºÚÁϺ£½Ç91Èë¿Ú org.
   • An administrator read-write API Key with at least a Manager role is required to use this toolset. See the Admin Portal Roles kb.
   • For more information on obtaining an API Key, see ºÚÁϺ£½Ç91Èë¿Ú APIs.
3. Set your Organization ID: Change the variable $JCORGID to the from your ºÚÁϺ£½Ç91Èë¿Ú org.
4. Set your User Group ID: Change the variable $JCUSERGROUP to the ID of the ºÚÁϺ£½Ç91Èë¿Ú user group with access to the Radius server.
   • The User Group ID is available on the ºÚÁϺ£½Ç91Èë¿Ú Admin Console. Go to USER MANAGEMENT > User Groups, select the appropriate User Group, and view the url.
     • The url will look similar to this: https://console.jumpcloud.com/#/groups/user/5f808a1bb544064831f7c9fb/details
     • The ID of the User Group is the 24 character string between /user/ and /details: 5f808a1bb544064831f7c9fb.
5. Set your network SSID Name.
   • Change the variable $NETWORKSSID to the name of the SSID network your clients will connect to.
     • On macOS hosts, the user certificate will be set to automatically authenticate to this SSID when the end user selects the WiFi Network.
     • Multiple SSIDs can be provided as a single string; separate SSID names with a space.
       

6. Set the open SSL Binary Location.
   • This variable can point to a path or call the binary with the name openssl.
     • For , this will likely need to be set to the openSSL binary installation path like
       '/opt/homebrew/opt/openssl@3/bin/openssl' or '/usr/local/Cellar/openssl@3/3.0.7/bin/openssl'
     • For Windows, installing OpenSSL and setting an environment variable described in should be sufficient (no additional changes to $opensslBinary necessary)
7. Set your certificate subject headers: change the default values provided in the $Subj variable to Country, State, Locality, Organization, Organization Unit and Common Name values for your organization.
8. Set desired user certificate type: Change the $certType variable to either EmailSAN, EmailDN, or UsernameCn.
   • ºÚÁϺ£½Ç91Èë¿Ú RADIUS supports three types of user certificates:
     • ºÚÁϺ£½Ç91Èë¿Ú user email in the subject alternative name (EmailSAN)
     • ºÚÁϺ£½Ç91Èë¿Ú user email in the subject distinguished name (EmailDN)
     • ºÚÁϺ£½Ç91Èë¿Ú username in the common name (UsernameCn)

Generate or Import a Certificate Authority

A Certificate Authority (CA) is required for passwordless Radius Authentication. The radius_ca_cert.pem file is to be uploaded to ºÚÁϺ£½Ç91Èë¿Ú to serve as the Certificate Authority for subsequently generated user certificates. This CA can be imported or generated.The entire certificate generation process is managed through a PowerShell menu based script. To run the main program, open a PowerShell 7 terminal session and run: Start-RadiusDeployment.ps1, which will present the following menu:

To generate a self-signed certificate, use the first option in the menu.

• The resulting file, radius_ca_cert.pem, will live in the projectDirectory/Radius/Cert directory.
  • A password will be required to protect the CA from unauthorized access. During the session this password will be stored as an environment variable as it is also required to generate user certificates.

To import your own CA, the certificate and key files can be copied to the projectDirectory/Radius/Cert directory. 

In order to import a certificate from a .pfx file, the certificate and key needs to be extracted from .pfx file.

1. Extract the private key: openssl pkcs12 -in certfile.pfx -nocerts -out /projectDirectory/Radius/Cert/radius_ca_key.pem
   • Replace certfile.pfx to the file path of your .pfx file. Make sure the radius_ca_key.pem is saved or moved to /projectDirectory/Radius/Cert/ directory
   • This command will prompt for the .pfx password.

2. Extract the certificate: openssl pkcs12 -in certfile.pfx -nokeys -out /projectDirectory/Radius/Cert/radius_ca_cert.pem
   • Replace certfile.pfx to the file path of your .pfx file. Make sure the radius_ca_cert.pem is saved or moved to /projectDirectory/Radius/Cert/ directory.
   • Again, this command will prompt for the .pfx password.

After successful import or generation of a self-signed CA, the serial number and expiration date will be displayed on the main menu:

Generate User Certificates

After the CA has been generated or imported, individual user certificates can be generated.

• The ID of the user group stored as the variable: $JCUSERGROUP is used to store ºÚÁϺ£½Ç91Èë¿Ú users destined for passwordless Radius access.
• For each user in the group, a .pfx certificate will be generated in the /projectDirectory/Radius/UserCerts/ directory. 
• The user certificates are stored locally and monitored for expiration.
• If local user certificates are set to expire within 15 days, a notification is displayed on the main menu.
• User certificates can be manually removed from the /projectDirectory/Radius/UserCerts/ directory at any time, and regenerated using option 2 from the main menu. User certificates can be continuously re-applied to devices using option 3 to distribute user certificates.

Distribute User Certificates

Option 3 in the main menu will enable admins to distribute user certificates to end user devices. 

• Commands will be generated in your ºÚÁϺ£½Ç91Èë¿Ú Tenant for each user in the Radius User Group and their corresponding system associations. 
• This script will prompt you to kick off the generated commands. If the commands are invoked, they should be queued for all users in the Radius User Group.
  • These commands are queued with a TTL timeout of 10 days — meaning that if the end user device is offline when the command is queued, the command will sit in the JumpCLoud console for 10 days and wait for the device to come online before attempting to run.
• On the device, certificates are replaced if a command is sent to a device with a newer certificate.

EXAMPLE

In this example, users Bob and Ali were connected to a radius network with their individual certificates. Newly generated certificates are issued to Bob and Ali via generated ºÚÁϺ£½Ç91Èë¿Ú Commands. Bob's new user certificate with serial number XYZ1 would be installed and the older certificate with serial number ABC1 would be removed from the device. Ali's user certificate with serial number HIJ2 would be installed and the older certificate with serial number EFG1 would be removed from the device.
Replacement of user certificates can occur while a device is actively connected to the radius network protected by passwordless certificate based authentication due to the fact that authentication is session based. If Bob authenticated to the radius network with cert serial number ABC1 the network session between Bob and the radius network is instantiated. During that session, the certificate ABC1 can be replaced with certificate XYZ2 from Bob's computer without network interruption. Upon next authentication, the system should default to using the new certificate.
The generated ºÚÁϺ£½Ç91Èë¿Ú commands for Bob will only remove certificate ABC1 if XYZ2 is installed successfully.

Monitor Certificate Deployment Status

After certificates have been distributed, you can view overall progress of the deployment through option 4 on the main menu.

• This automation will query the deployment status of each generated command and display a table of the command status.
  • If a command is no longer queued (either through cancellation or the TTL timeout of 10 days exceeded) or if the command failed (either through some standard error or end user not being logged in (exit code 4)) these commands can be reissued using the menu options.
• After issuing commands to devices, the list of commands issued to devices can be viewed.
• Individual failed commands can be explored with option 2 from the certificate deployment menu.
  

• Option 3 can be used to retry a failed command.