Skip to main content

RADIUS Server for AdminX

Overview​

The RADIUS server is a command-line executable that facilitates connections between your Active Directory (AD) or LDAP user accounts on BlockID and your RADIUS client. The RADIUS server is configurable using the AdminX control plane.

Requirements​

  • 64-bit Operating System (Windows, macOS, or Linux)
  • RAM - 4 GB (Minimum)
  • Connection to the internet (required to communicate with BlockID and your RADIUS client)
  • BlockID Mobile Application (for entering one-time passcodes and push authentication)
  • Administrator access to AdminX (for configuration and download)

Supported Authentication Methods​

The RADIUS server accepts the following authentication methods. Tenant Administrators can set which authentication methods are allowed on their tenants:

  • Username and OTP
  • Username and Password + OTP
  • Push Authentication

When using Push Authentication, the RADIUS server also sends a push notification to your registered mobile device. Upon approving the authentication, the user is logged into the RADIUS app by providing biometrics like FaceID/TouchID.

RADIUS Server Configuration and Download​

The RADIUS Server can be configured and downloaded using AdminX. Tenant or Community Administrator access is required.

To access the RADIUS Configuration page in AdminX, login to your tenant as an Administrator and click Applications -> RADIUS Configurations

Create New RADIUS Configuration​

To create a new RADIUS Server configuration package for your tenant, please do the following:

  • Click Add New Configuration
  • Enter a Configuration Name to save your settings under.
  • Note your Config ID as it will be required to run the RADIUS Server from the command line.

Configure Supported Login Methods​

Next, you will need to define which login methods are supported when connecting to the RADIUS server.

Login with Push​

When enabled, users can authenticate to their RADIUS client by sending a push notification to their mobile device using the BlockID Mobile Application. Instead of entering a password, users enter the keyword push, triggering the notification. Users will need to authenticate the push notification using their enrolled biometrics, such as a fingerprint or face scan.

  • To enable, check the Login with Push box.
  • to disable, uncheck the Login with Push box.
tip

When enabled, login with push can be used concurrently with any of the passcode login methods below.

Login with Passcodes​

In this section, Administrators can enable and define which One-Time Passcode (OTP) combinations can be used for authentication. Select from the following passcode authentication options:

  • Not supported

    • Users will not be allowed to log in using passcodes. Login with push must be enabled to log in.

  • Prompt for OTP only

    • When prompted for a password, the user must only provide the 6-digit passcode to log in.

  • Prompt for Password and OTP

    • When prompted for a password, the user must provide the password with the 6-digit passcode appended to the end of the password. Example: MyP@ssw0rd873174

  • Prompt for OTP and Password

    • When prompted for a password, the user must provide the password with the 6-digit passcode prepended before the password. Example: 873174MyP@ssw0rd

Download the RADIUS Server​

After setting your supported login methods, click the download link for your desired OS. The RADIUS Server supports all major 64-bit operating systems, including Windows, macOS, and Linux. The download link contains a zip archive and comes preconfigured with your tenant license key.

Save RADIUS Configuration​

After configuring your RADIUS Server, click Create to save your configuration to AdminX.

Modify an Existing RADIUS Configuration​

Your RADIUS configuration can be edited at any time using AdminX. To edit your RADIUS configuration, please do the following:

  • Scroll to the RADIUS configuration you wish to edit and click the pencil icon, located in the actions column on the right.
  • Make any desired changes, then click Save. You can also download another copy of your RADIUS server if desired.
tip

Please allow up to 10 minutes for any changes to take effect

Delete a RADIUS Configuration​

Administrators can delete an existing RADIUS configuration using AdminX.

To delete an existing RADIUS configuration, please do the following:

  • Scroll to the RADIUS configuration you wish to delete and click the trash icon, located in the actions column on the right.
  • Confirm you wish to delete the configuration by clicking Yes, delete.
caution

Once the configuration has been removed, users will no longer be able to authenticate using the deleted Config ID.

tip

Please allow up to 10 minutes for any changes to take effect

Start or Stop the RADIUS Server​

After downloading the RADIUS server archive, copy the archive to your server and extract its contents to a folder of your choosing. The folder will contain the RADIUS server executable, your license.json file, and some bash scripts.

Open a terminal window and navigate to the folder containing the bash scripts. Execute the following commands from your terminal to run the RADIUS server. We've outlined the different runtime configuration options.

Command Line Arguments​

note

Please enter your Config ID from AdminX as your UUID. These strings need to match for the RADIUS server to work.

  • -u <uuid> (required): Set your uuid. Use your Config ID from AdminX.
  • -P <port> (optional): Set the port to listen on (default is 1812)`
  • -s <secret> (optional): Set RADIUS shared secret (default is secret)
  • -p <proxy password> (optional): Set a proxy password
  • Starting the RADIUS server service
./startRadius.bsh -u <uuid>
  • Starting the RADIUS server service on a custom port (default is port 1812)
./startRadius.bsh -u <uuid> -P <port>
  • Starting the RADIUS server service with a proxy password
./startRadius.bsh -u <uuid> -p <password>
  • Starting the RADIUS server service with a new shared secret 
./startRadius.bsh -u <uuid> -s <shared secret>
  • Stopping the RADIUS server service 
./stopRadius.bsh

Shared Secret Configuration​

Your RADIUS client and server must be configured with the same shared secret. The shared secret is a password of your choosing used to generate one-way encrypted communication in all RADIUS packets. The maximum length of the shared secret is 256 bytes and is case-sensitive. We recommended that the shared secret be at least 16 characters.

The shared secret is defined for the RADIUS server at runtime. For information on setting the shared secret in your RADIUS client, please refer to the documentation specific to your client.

If users do not set a shared secret, the radius-server will default to secret.

danger

Your RADIUS client and the BlockID RADIUS server must be configured with the same shared secret. In other words, you must use the same password on your RADIUS client and the BlockID RADIUS Server.

Proxy Configuration​

If your setup requires you to run your RADIUS server through a proxy, some additional information must be added to the license.json file packaged with your RADIUS server archive.

  • Contents of license.json:

    • licenseKey: Your BlockID tenant license key
    • communityId: Your tenant community ID
    • version: RADIUS server version
    • tenantDNS: Tenant domain the server is connecting to

  • Using a text editor, add the following lines to your license.json:

    • proxyUrl: proxy server URL
    • proxyUser: proxy user

Your license.json file will already be populated with the necessary information minus the optional proxy information.

Here is an example of a completed license.json with proxy details:

license.json
{
  "licenseKey":"c1fe166d-997b-4b4a-81f2-000000000000",
  "communityId": "default",
  "version": "pl_gr_1.07.0"
  "tenantDNS":"blockid-trial.1kosmos.net",
  "proxyUrl": "http://proxy.example.com",
  "proxyUser": "proxy"
}

Connecting to the RADIUS Server​

Once the service of the RADIUS server is running, you can connect to the server using your preferred radius client by sending a RADIUS payload. The payload is a specifically formatted text block containing your username and other details.

note

Administrators can set which authentication options are available to use. Not all methods described below might be available on your tenant. Please get in touch with your tenant Administrator for more details.

The BlockID RADIUS server accepts two different payload types:

  • One-Time Passcode (OTP) Authentication: Your RADIUS client sends a payload containing your BlockID username and a six-digit OTP.
  • One-Time Passcode (OTP) Authentication with Password: Your RADIUS client sends a payload containing your BlockID username, BlockID password, and a six-digit OTP.
  • Push Authentication: Your RADIUS client sends your BlockID username and a specific push keyword that triggers the server to send a push notification to the BlockID Mobile App for passwordless authentication.

After submitting your payload, the request is forwarded to the BlockID cloud for validation with your Active Directory (AD) instance. After successfully validating your AD credentials, the RADIUS server validates your authentication method, and you are fully authenticated into your tenant.

OTP Authentication​

Using this method, your RADIUS client payload is configured to allow for the addition of OTP authentication.

The RADIUS protocol itself has no built-in mechanism for specifying OTP parameters. To work around this, we use the 6-digit OTP instead of the password when using the OTP Authentication method. 

User-name = "<BlockID tenant username>"
User-password = "<6-digit OTP>"

The easiest method of fetching your OTP is to use the BlockID Mobile Application. Open the BlockID Mobile Application on your device and swipe left to view your six-digit TOTP. An image of the BlockID Mobile App containing the six-digit refreshing OTP is shown below.

Each TOTP is valid for 30 seconds, after which the code expires and refreshes to a new six-digit code. The circle indicator surrounding the OTP shows how much time is left before the current code expires and refreshes.

Quickly enter the same six-digit code currently displayed in the BlockID Mobile App in your RADIUS client and send your payload before the OTP refreshes.

Example OTP Payload​

Here is an example payload with the following user details:

  • BlockID tenant username is user@1kosmos.com
  • OTP (from BlockID Mobile App) is 873174

Your RADIUS client OTP payload should be formatted as follows:

User-Name = "user@1kosmos.com"
User-Password= "Pas$w0rd873174"

After submitting your payload, the request is forwarded to the BlockID cloud for validation with your Active Directory (AD) instance. After successfully validating your AD credentials, the RADIUS server validates the OTP code appended to your password.

After successful OTP validation, you will be fully authenticated into the tenant.

OTP Authentication with Password​

Using this method, your RADIUS client payload is configured to allow for the addition of OTP authentication.

The RADIUS protocol itself has no built-in mechanism for specifying OTP parameters. To work around this, we require the OTP to be added directly to the end of your password with no spaces, as shown below:

User-name = "<BlockID tenant username>"
User-password = "<BlockID tenant password><6-digit OTP>"

The easiest method of fetching your OTP is to use the BlockID Mobile Application. Open the BlockID Mobile Application on your device and swipe left to view your six-digit TOTP. An image of the BlockID Mobile App containing the six-digit refreshing OTP is shown below.

Each TOTP is valid for 30 seconds, after which the code expires and refreshes to a new six-digit code. The circle indicator surrounding the OTP shows how much time is left before the current code expires and refreshes.

Quickly enter the same six-digit code currently displayed in the BlockID Mobile App in your RADIUS client, appended directly to the end of your password. You must enter and send your payload before the OTP refreshes.

Example OTP with Password Payload​

Here is an example payload with the following user details:

  • BlockID tenant username is user@1kosmos.com
  • BlockID tenant password is MyP@ssw0rd
  • OTP (from BlockID Mobile App) is 873174

Your RADIUS client OTP payload should be formatted as follows:

User-Name = "user@1kosmos.com"
User-Password= "MyP@ssw0rd873174"

After successful OTP validation, you will be fully authenticated into the tenant.

Push Authentication​

Using this method, your RADIUS client payload must contain the push keyword (set by your tenant Administrator) in the password field. This triggers the server to send a push notification to the BlockID App on your mobile device.

Do not enter your actual BlockID password when using Push Authentication.

Example Push Payload​

Here is an example payload with the following user details:

  • BlockID tenant username: user@1kosmos.com
  • Push keyword: push

Your RADIUS client Push Authentication payload should be formatted as follows:

User-Name = "user@1kosmos.com"
User-Password= "push"
Reminder

For the push payload to work, you must enter your push keyword as your user password in your RADIUS client. Entering your actual user password will cause the request to fail.

After entering the push keyword, you will receive a push notification to your registered device. When approved, the user is logged into the RADIUS app.

Testing the RADIUS Server​

Users can test their RADIUS Server by initiating a connection using a RADIUS client and viewing the log files. For example, we will use the command-line tool radclient to test our connection.

  • Create a text file containing your RADIUS payload. Here is an example payload using push authentication, with push as our push keyword: 
User-Name = "ian.french@1kosmos.com"
User-Password= "push"
  • Save the file as payload.txt
  • Start the RADIUS server:
    • ./startRadius.bsh -u <uuid> -s <shared secret>
  • Run the following radclient command:
    • ./radclient -c 1 -f payload.txt localhost:1812 auth <shared secret>

If all your details are correct, the command should run without error messages. Examine the log files in port-<port>/logs/ and check for error messages. A successful connection will contain keywords such as 200 message: SUCCESS.

RADIUS Server Logs​

Logs will be viewable after starting the RADIUS Server for each instance running. Logs are in the folder containing the RADIUS Server at the following path: <diretory>/port-<port>/logs/.

Connection attempts, valid connections, and errors are all logged and can be viewed to troubleshoot any issues.

RADIUS Event Logs in AdminX​

The RADIUS server generates Event Logs whenever a user successfully or unsuccessfully authenticates using RADIUS. Administrators can review the logs in AdminX for detailed information about each authentication attempt.

The following events are created when using RADIUS authentication methods:

E_LOGIN_SUCCEEDED​

The E_LOGIN_SUCCEEDED event is created when a user completes RADIUS authentication using Push or OTP.

Details Captured:

  • Tenant Info
  • referrer_name = RADIUS
  • Time of Event
  • Username
  • User IP Address
  • RADIUS client identifier
  • RADIUS client name
  • Login method: “push”, “otp”`

A screenshot of an E_LOGIN_SUCCEEDED event log from AdminX is shown below:

E_LOGIN_FAILED​

The E_LOGIN_FAILED event is created when a user fails RADIUS authentication.

Details Captured:

  • Tenant Info
  • referrer_name = RADIUS
  • Time of Event
  • Username
  • User IP Address
  • RADIUS client identifier
  • RADIUS client name
  • Login method: “push”, “otp”`

A screenshot of an E_LOGIN_FAILED event log from AdminX is shown below: