GreenRADIUS v4.3 Admin Guide

Green Rocket Security

Green Rocket Security's GreenRADIUS is a complete two-factor authentication solution, supporting YubiKey OTP and OATH, Green Rocket's own mobile apps which use push notifications, Google Authenticator and much more. It validates traditional RADIUS logins as well as offering a modernized Web API for web applications. GreenRADIUS can also enforce 2FA for Windows Logon, whether PCs are domain-joined or not, online or offline, and for both desktop and RDP logins.

This guide describes how to configure and operate your GreenRADIUS instance. Administrators will find the guide has been arranged by topic, making it easy to refer to specific sections for information.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Overview of GreenRADIUS

What is GreenRADIUS?

GreenRADIUS is a two-factor authentication platform. It augments the traditional username/password security model by requiring users to provide a second factor to prove their identity. This helps secure users and organizations against various password-related attacks.

GreenRADIUS takes the form of a multi-protocol server. GreenRADIUS validates each user/password/second-factor login attempt and responds with either ACCEPTED or DENIED.

GreenRADIUS supports the traditional RADIUS protocol, which has wide industry acceptance and is used by a considerable amount of existing client software.

In addition, GreenRADIUS also exposes a modern web API, which makes the development of modern web-centric applications (or browser-based 2FA validations) very easy.

GreenRADIUS can also enforce 2FA for Windows Logon, whether PCs are domain-joined or not, online or offline, and for both desktop and RDP logins. Contact us today to learn more.

Distribution

GreenRADIUS 4.0 is distributed as a virtual machine (VM) packaged in the Open Virtualization Format (OVA). It is available as a free preview download from our website at http://www.greenrocketsecurity.com/greenradius

If you would prefer an AWS instance of GreenRADIUS, please contact us, and we would be happy to share our GreenRADIUS AWI with you.

Minimum Requirements

GreenRADIUS is a lightweight virtual appliance, and, at a minimum, requires the following:

  • 2 CPUs
  • 4 GB RAM (8 GB RAM is recommended)
  • 80 GB hard drive space

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Default Login Information

By default, the login information for GreenRADIUS is:

  • Username: gradmin
  • Password: GreenRocket!23

This username and password are used to log in to the command line. Most configurations for GreenRADIUS are performed through the web admin interface, served at https://<IP address of GreenRADIUS>/admin.

Note: The web admin interface is only accessible after the network has been set up. See the next section for information on how to do this.

We would recommend changing the password, both for the console and the web admin interface. The password for each is stored separately.

To change the command line password, run the passwd command from the command line in the terminal console.

To change the web admin interface password, go to the "Webmin Users" link (found under the Webmin menu in the left panel), and click the username whose password you would like to change.

Changing a Webmin password

Make sure the password mode is "Set to ..", then type the new password into the field to the right. Click Save to record your changes. The next time you log into the web admin interface, the new password will be required.

This username and password are used to log in to the command line. Most configurations for GreenRADIUS are performed through the web admin interface, served at https://<IP address of GreenRADIUS>/admin.

Web Analytics Made Easy -
StatCounter

Updated 2021-09-13
© 2021 Green Rocket Security Inc. All rights reserved.

Authenticator 2FA For Web Admin Interface

The GreenRADIUS web admin interface itself can be secured with two-factor authentication (2FA). This is easy to do with any Authenticator app, such as Google Authenticator and Microsoft Authenticator.

  1. Open the Webmin Configuration link (found under the Webmin menu in the left panel.)

  2. You will be presented with a grid of configuration menus. Select Two-Factor Authentication.

  3. From the two-factor authentication options, select Google Authenticator:

enabling 2FA for web admin interface

Click Save to commit your changes. This will require the server to restart, so there will be a slight delay.

  1. Open the Webmin Users link (also located under the Webmin menu in the left panel).

Webmin users

  1. Select the user for whom you would like to enable two-factor authentication. You will be presented with a series of configuration dropdowns. Select "Security and limits options":

security and limits

  1. Click the "Enable Two-Factor for User" button.

  2. Select "Enroll for Two-Factor Authentication":

Enroll for two-factor authentication

  1. A QR code will be generated which you can scan with your authenticaton app of choice.

  2. The next time you attempt to log into the web admin interface, an OTP dialog will appear. Input the six-digit Authenticator code here:

Log in with OTP

2FA is now enabled for the web admin interface.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Automatic Logout for Web Admin Interface

To mitigate session reuse attacks, the web admin interface can be configured to log users out after a certain period of inactivity.

  1. Log into the web admin interface.
  2. From the left panel, select Webmin→Webmin Configuration.
  3. A series of options will be displayed. Select "Authentication". Authentication option in Webmin Configuration
  4. A page of configuration settings will appear. Edit the setting labeled "Auto-logout after [ ] minutes of inactivity". When finished, select the "Save" button at the bottom of the page to commit your changes. Editing the timeout value
  5. Users will now be automatically logged out after a period of inactivity.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Network Configuration

Before GreenRADIUS can be accessed, the network settings must be configured.

Log into the command line. Then run the following commands:

cd /opt/grs/greenradius/scripts/ip-configuration-scripts
sudo python configure_ip.py

Example: Network configuration

You will be presented with a series of prompts. Select either DHCP or static IP address. If you select DHCP, GreenRADIUS will communicate with your routing device and automatically choose an IP address for you. If you select static IP, you will need to choose an IP address yourself, as well as configuring the network access point and DNS server.

WARNING: If you opt for Static IP Address, ensure that the IP address chosen does not conflict with any existing devices on the network.

Ports

The following ports need to be open for proper communication to and from GreenRADIUS:

PortDescription
22SSH for remote administration
389LDAP
443access to the web admin interface, self-service portal, use of the GreenRADIUS Web API, for Windows Logon, for mobile app
636LDAPS
1812 UDPRADIUS authentication
9443for Windows Logon, mobile app

Once the network setup is complete, your GreenRADIUS instance is ready to use.

Web Analytics Made Easy -
StatCounter

Updated 2021-08-21
© 2021 Green Rocket Security Inc. All rights reserved.

Domains

Domains hold collections of users in GreenRADIUS. They are independent and their configurations are separate from one another.

The Domains view

You can freely create and remove domains. There is no limit to the number of domains a GreenRADIUS instance can hold. Domain names may only contain alphanumeric characters, periods, and underscores.

Clicking on a domain in the web admin interface brings up a set of domain-specific tabs:

Domain specific tabs

Each domain has configuration specific to it, accessed through the Configuration tab in the main menu page. There is also a set of configuration options which apply to all domains. This is found under the Global Configuration tab.

The Default Domain

If multiple domains exist, there must be a way to disambiguate which domain a request is intended for. When there are multiple domains and no default domain is selected, all authentication requests to GreenRADIUS must specify the user in 'canonical' format: user@domain, for example jdoe@greenradius.demo.

If a domain has been set as the default domain, requests which do not explicitly specify a domain (that is, a login with a username only) will assume the default domain.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Users

Importing users

GreenRADIUS imports users from different LDAP servers:

  1. Active Directory
  2. OpenLDAP (there is also an onboard OpenLDAP which can be used as the user store)
  3. 389 DS
  4. FreeIPA

The LDAP server must remain reachable for GreenRADIUS to work, as authentication requests to GreenRADIUS involve a subsidiary request to the LDAP server.

LDAP configuration is found under the Directory Server tab.

LDAP configuration

Set the IP address/hostname/FQDN to point to a running LDAP server. The credentials must have the correct permission(s) to allow GreenRADIUS to log into the LDAP server and fetch (read) the user list. Next, click "Save and Import" to import the users into the selected domain.

The Users Tab

When a domain has been selected, the Users/Groups tab displays a list of users:

Users tab

From here you can perform administrative actions at the user level. These are covered in more detail in subsequent sections.

Groups

Group membership can be configured to be returned in the RADIUS response for each login attempt.

  1. Navigate to Configuration tab of the domain
  2. Set "Return User's Group Membership In RADIUS Response" to "Yes"
  3. Use the default "Response Format" unless the RADIUS clients require any specific text to be returned
  4. Set "Group Return Information" to "Only Group Name"
  5. Set "Return All Groups" as desired
  6. Click the Update button to save the settings

Group Membership Configuration

  1. Navigate to the Groups tab.
  • A group setting of "0" means the group is not prioritized
  • A group setting of "1" is the highest priority
  • A group setting of "2" is the next highest priority, and so on

Group Membership Prioritization

  1. The group(s) with the highest priority to which the user belongs will be returned in the RADIUS response. This can be tested in the RADIUS Test of the Troubleshoot tab

Group Membership Troubleshoot Test

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Onboard OpenLDAP

GreenRADIUS comes equipped with an onboard OpenLDAP server, in case an external LDAP is not desired. A third-party LDAP admin tool can be used to manage the onboard OpenLDAP, such as LDAP Admin.

The onboard OpenLDAP, by default, is configured with a sample domain (greenradius.demo) with five test users (user1 through user5). Each of the users has a default password of GreenRocket!23

To overwrite the default OpenLDAP domain with a new OpenLDAP domain, follow these steps:

Pre-requisites

A resolvable hostname/FQDN and a corresponding certificate must be configured in GreenRADIUS.

  1. Global Configuration tab > General
  2. Set the value of the Server Hostname/FQDN field
  3. Click the Save button to save the configuration
  4. Global Configuration tab > Certificate
  5. Under the Generate a CSR/Upload the Certificate section, click Upload a certificate and provide the server certificate, private key, and CA chain. Then click the Install Certificate button.
  • To install a self-signed certificate, in the Create Certificate section, enter a common name matching the hostname/FQDN configured earlier. Click the Create and Install button.

Changing the Onboard OpenLDAP Domain

  1. Global Configuration tab > On-board LDAP Server
  2. Provide the following inputs:
  • DNS Domain Name
  • Organization Name
  • Current Admin Password (default password is GreenRocket!23)
  • Enable Secure Connection for Replication
  • Server ID
  1. Click the Update button to save the new configuration

Changing the OpenLDAP Admin Password

To change the onboard OpenLDAP password of the admin user, follow these steps:

  1. Global Configuration tab > On-board LDAP Server
  2. Provide the following inputs:
  • Current Admin Password (default password is GreenRocket!23)
  • New Admin Password
  • Confirm Admin Password
  1. Click the Update button to change the admin password

Users Changing Their Own Onboard OpenLDAP Password

Users can change their own onboard OpenLDAP password.

Pre-requisites

  • A RedHat, CentOS, or Ubuntu machine that has OpenLDAP utilities installed:
  • In RedHat/CentOS, openldap-clients should be installed
  • In Ubuntu, ldap-utils should be installed
  • The above Linux machine must be able to reach GreenRADIUS

Steps

  1. On the command line of the Linux machine, run the following command: ldappasswd -h <ip address of GreenRADIUS> -p 389 -x -D "uid=<username>,ou=<user's OU>,dc=<domain component 1>,dc=<domain component 2>,dc=<domain component etc>" -W -A -S
  2. The user enters his current password twice
  3. Then the user enters his new password twice
  4. Then the user enters his current/old password once again
  5. A successful password change is silent. If there is an error, an error message will appear.

OpenLDAP password change screen

Setting Up OpenLDAP Password Policies

The onboard OpenLDAP comes with an optional module which can enforce certain password policies, such as password expiration and minimum password lengths.

All commands must be performed in the terminal of GreenRADIUS, either directly or via SSH.

For simplicity, the domain shown in the steps below is always greenradius.demo, represented as dc=greenradius,dc=demo. If your own domain varies, you will need to make the appropriate substitutions.

Several of the commands below will prompt for multiple lines of text. Simply enter the text into your terminal. When everything has been input, press Ctrl-D on a blank line to finish the entry and execute the command.

First, you must load the appropriate module:

sudo docker exec -it GRS-OPENLDAP ldapmodify -Q -Y EXTERNAL -H ldapi:///

This will prompt for LDAP data to insert. Use the following:

dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: ppolicy.la

As mentioned above, press Ctrl-D on a blank line when done. The command should report success with a message:

modifying entry "cn=module{0},cn=config"

Next, load the ppolicy schema. To do this, you will need to download the schema from here and upload it to GreenRADIUS. Copy it into the /var/lib/docker/volumes/grs-docker-compose_gras-config/_data directory. (This will require root permissions.)

To load the schema into LDAP, execute this command:

sudo docker exec -it GRS-OPENLDAP ldapadd -Q -Y EXTERNAL -H ldapi:/// -f /opt/grs/greenradius/ppolicy.ldif

This will load the stored ppolicy schema. You should receive a message upon success.

Now the ppolicy module must be enabled:

sudo docker exec -it GRS-OPENLDAP ldapadd -Q -Y EXTERNAL -H ldapi:///

Input the following data to the command, pressing Ctrl-D when done as said above:

dn: olcOverlay=ppolicy,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
objectClass: olcPPolicyConfig
olcOverlay: ppolicy
olcPPolicyDefault: cn=default,ou=policies,dc=greenradius,dc=demo

As mentioned, replace dc=greenradius,dc=demo with the LDAP-formatted specification for your own domain, and press Ctrl-D on a blank line when finished.

Now add the object which will hold your password policies:

sudo docker exec -it GRS-OPENLDAP ldapadd -c -x -D "cn=admin,dc=greenradius,dc=demo" -W

You will be prompted for your administrative password. Once this is entered, the command takes the following data:

dn: ou=policies,dc=greenradius,dc=demo
objectClass: organizationalUnit
ou: policies

Press Ctrl-D on a blank line when finished, as before, to add the policy container. The final step is to create the password policy. Shown below is a simple, example policy that requires the following:

  • passwords must have a minimum of eight (8) characters
  • passwords expire after 60 days (or 5,184,000 in seconds)

Complete documentation on the available password settings can be here.

Run this command:

sudo docker exec -it GRS-OPENLDAP ldapadd -c -x -D "cn=admin,dc=greenradius,dc=demo" -W

As before, you will be prompted for your password, and once this is entered you will need to input the following:

dn: cn=default,ou=policies,dc=greenradius,dc=demo
objectClass: pwdPolicy
objectClass: organizationalRole
cn: default
pwdAttribute: userPassword
pwdCheckQuality: 2
pwdMinLength: 8
pwdMaxAge: 5184000

Replace pwdMinLength: 8 and pwdMaxAge: 5184000 with your own custom configurations as desired. Press Ctrl-D to save the changes as before. You should see a success message and find that your password policies are now enforced.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Token Types

GreenRADIUS supports several different types of second factor, called tokens:

YubiKey OTP

The YubiKey OTP protocol emits a 44-character One-Time Password (OTP). Once one OTP has been used, it cannot be used again. Another must be generated from the YubiKey. Thus to compromise a YubiKey-secured device, a malicious party would have to gain access to the YubiKey device itself. YubiKeys can be assigned to users in three ways:

  1. By the administrator in the Users/Groups tab of the GreenRADIUS domain
  2. With auto-provisioning
  3. By the user in the GreenRADIUS Self-Service Portal https://<IP address of GreenRADIUS>

YubiKey OTPs come in two variants: pre-programmed and custom. By default, YubiKeys ship with a pre-programmed secret. OTPs generated using this pre-programmed secret can only be validated using Yubico's YubiCloud servers. You can re-program and overwrite this secret, however, and import that secret into GreenRADIUS. Please refer to our Document Library to see our YubiKey programming guide.

The Global Configuration→Validation Server setting allows you to select whether YubiKey OTPs will be validated by the YubiCloud or locally by GreenRADIUS. If using pre-programmed keys, select YubiCloud. If you are using custom secrets, use local validation.

YubiKey OATH-HOTP

The OATH protocol is similar to the OTP protocol. OATH OTPs are shorter than the traditional YubiKey OTP, which may make OATH OTPs desirable for situations where password fields have a character-lenght limitation. This option is available for customers with a license for our premium OATH Module.

Please refer to our Document Library to see our guide on programming YubiKeys in OATH-HOTP mode.

Google Authenticator (Authy, Microsoft Authenticator, and similar soft tokens)

GreenRADIUS supports Google Authenticator and other similar soft tokens as a second factor for users for those customers with a license for our premium OATH Module. Users sign in to the GreenRADIUS Self-Service Portal, select Google Authenticator, and scan a QR code with the phone app. Once the user clicks Proceed on the Self-Service Portal, the soft token is registered to his user account in GreenRADIUS, and a six-digit code is regenerated every 30 seconds, providing a secure second factor.

Mobile Apps - "Green Rocket 2FA" Apps

The "Green Rocket 2FA" app is available for iOS or Android. Once the app is installed, there is a simple, one-time registration process. This feature is available for customers that have a GreenRADIUS license for our mobile app. (The app is free to download for users.)

In addition to a GreenRADIUS license enabling the use of our mobile app, make sure of the following:

  • A valid certificate should be installed in GreenRADIUS. See our Certificate guide for more details.
  • Ports 443 and 9443 should be open for communication to and from GreenRADIUS.

When an authentication request reaches GreenRADIUS, and a user has our mobile app installed and registered with GreenRADIUS, a push request will be sent to the user's phone, appearing as a notification in which they can either approve or deny the request.

U2F

The U2F function of the YubiKey (or any other FIDO U2F token) is used with our 2FA for Windows Logon solution. When users log in to Windows, the U2F token flashes, prompting the user to touch the token button and complete the login. No pre-registration of the token is required.

U2F can also be used for RADIUS integrations and web applications on supported browsers.

Temporary Token

A temporary token is a static per-user text string which is valid for a limited time and a limited number of logins only. Temporary tokens can be created from the Users/Groups tab.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Authenticator Registration

  1. In a web browser, navigate to the Self Service Portal at https://<ip address of GRVA>/.

Self service portal

  1. Click the "Assign a Token" button. You will then be prompted to log in with your username and password. (If you already have a token assigned, you will be prompted to log in with your assigned token as well.)

  2. Once you have logged in, select the "Google Authenticator" option at the top of the screen.

Authenticator

  1. Using your Authenticator app of choice, scan the QR code. Once you do, it will be displayed as a token in the app:

Token in app

  1. In the browser, click Proceed. (This is an extremely important step, as clicking Proceed registers the token in GreenRADIUS.) You will be prompted to verify your new Authenticator token by entering the current OTP:

Verifying OTP

  1. Once the token is assigned, you will see a success message:

Registration successful

  1. You can now use your Authenticator token as a second factor.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

"Green Rocket 2FA" Mobile App Registration

NOTE: In order to successfully register our mobile app on iOS devices, you will need to have a valid certificate from a recognized CA installed. This does not apply to Android devices. Also, make sure ports 443 and 9443 are open for communication between GreenRADIUS and the public internet. (Green Rocket Security uses a cloud service for push notifications.)

  1. Download and install the Green Rocket 2FA mobile app from the App Store (on iOS) or the Play Store (on Android):

Installing the app

  1. Launch the app. A registration screen will be displayed:

Registering

  1. Enter the IP address or hostname of the GreenRADIUS to connect to, along with the domain the user is in, the username, and password:

Registering

  1. Tap the Register button. The registration process may take a few seconds, after which you will see a completion message:

Success

  1. A PIN will need to be set. This PIN will only be required during login attempts if the phone itself does not already have a lock screen secure setting (PIN, pattern, password, etc.)

  2. The token will now be displayed in the app.

Tokens list in app

  1. You can now use the app as a second factor. When a login request is made and no other token is specified (by appending an OTP to the password or other ways), a push request will be sent to the app:

Push request

You can tap Approve or Reject on the prompt to verify or deny the authentication attempt.

NOTE: For the app on Android, whenever the Android device is rebooted, the Green Rocket 2FA app must be launched once for push notifications to be received.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Token Settings

Numerous settings apply to tokens:

Per-user Settings

Single Factor Flag

When set (green checkmark in the Single Factor Flag column), the user can log in without a second factor. This setting is most useful in conjunction with the Auto Provisioning and Gradual Deployment settings described below.

Temporary Token

Selecting a user and clicking "Temporary Token Settings" will bring you to a page where you can add a temporary token to a user. You must specify an expiration date and the maximum number of logins for the temporary token.

Users with valid temporary tokens will have a green checkmark in the Temporary Token column.

Per-domain Settings

Domain configuration can be found under the "Configuration" tab in each GreenRADIUS domain.

Auto Provisioning

Auto provisioning for domain

When Auto Provisioning is enabled, the first time a user logs in with a YubiKey OTP, that YubiKey will be automatically assigned to the user. The token assignment will appear on the Users/Groups tab.

The "Enable Auto Provisioning for Multiple Tokens Per User" options allow users to provision multiple tokens to themselves by this method. By default, only users with no tokens already assigned can auto provision.

The per-domain Auto Provisioning setting has no effect if it is not also enabled at a global level in the Global Configuration→General tab. (See below.)

Gradual Deployment

Gradual deployment

Gradual Deployment allows administrators to roll out the deployment of two-factor authentication gradually, without requiring every user to switch and register a second factor at once. When Gradual Deployment is enabled, the first time a user logs in successfully with a token, his Single Factor Flag is automatically disabled, thus requiring two-factor authentication from that point forward. Gradual Deployment is most useful in conjunction with Auto Provisioning, described above.

Token Label Prefix

Token label prefix

The Token Label Prefix is a text string which appears in Google Authenticator and other similar soft token apps to signify which Authenticator token is for GreenRADIUS integrated logins. This text string is configurable, but must not contain spaces.

Global Configuration

Token-related global configuration settings are found under the Global Configuration tab→General heading.

OTP Input Method

OTP input method

This setting controls where users input the OTP during login attempts. It is described in more detail in the Authentication Requests section.

Enable Auto Provisioning

Global auto provisioning

The Global Auto Provisioning settings must be enabled for any of the domain settings to have an effect. If Auto Provisioning is disabled in Global Configuration, no domain will have auto provisioning, irrespective of their domain settings.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Token Management

You can view which tokens are assigned to each user from the Users/Groups tab of a GreenRADIUS domain or you can view which users are assigned to which tokens on the List Tokens screen.

Importing Secrets

Programmed YubiKeys (whether programmed in traditional Yubico OTP mode or OATH-HOTP mode) have secrets associated with each YubiKey. These secrets files must be imported into GreenRADIUS before the YubiKeys can be used.

Secrets can be imported under the Import Secrets tab:

Import Secrets tab

You must select the correct format option depending on which token type you are importing. If importing YubiKey OTP secrets, select the Cross-Platform option. If importing OATH token secrets, select Import OATH Tokens.

Once you have chosen a file format, you will be prompted to select the file containing the secrets.

The List Tokens tab

You can view all locally saved tokens in the List Tokens tab. This tab displays every token saved in the GreenRADIUS database (this does not include pre-programmed YubiKeys, as their secrets are stored in the YubiCloud). It also lists the user assigned to each token andthe user's domain.

Token Assignment

There are several ways to assign tokens to users in GreenRADIUS:

Auto Provisioning

Auto provisioning

Auto Provisioning, described in the previous section, enables users to simply log in with a YubiKey and have it auto-assigned. This is the simplest way to assign YubiKeys (whether OTP or OATH).

Self-Service Portal

Self service portal

The Self-Service Portal allows users to add tokens to themselves manually. It is accessible at https://<ip address of GRVA>/. From the Self-Service Portal, users register YubiKeys or Google Authenticator (or similar soft tokens) by scanning a displayed QR code with their phone.

Administrator Assignment

The GreenRADIUS administrator can manually assign tokens to users from the web admin console in either the List Tokens tab or in the Users/Groups tab of the GreenRADIUS domain.

Assigning a token to a user

You will need to enter the user's name in the canonical user@domain format.

Other

Some other methods have their own ways of assigning tokens. U2F tokens are automatically assigned as part of the login process with our 2FA for Windows Logon solution. Our "Green Rocket 2FA" mobile apps have a simple registration process.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Authentication Requests

Request Methods

There are a number of ways GreenRADIUS can integrate with your applications or services including the following:

RADIUS

The RADIUS protocol is a standardized and widely-used authentication request protocol in the security industry. It uses UDP on port 1812.

RADIUS uses a configured shared secret between the client and the server. You can add RADIUS clients and shared secrets in the RADIUS Clients tab:

RADIUS Clients tab

Note: The following RADIUS protocols are supported by GreenRADIUS:

  • PAP
  • PEAP
  • EAP-TTLS-GTC

CHAP, MS-CHAP, and MS-CHAPv2 are not supported.

Web API

GreenRADIUS provides a modern, REST-style Web API for use in applications that are constrained (e.g. browser applications which don't have direct access to the TCP/UDP stack.)

The Web API is accessed using a simple HTTP POST request with the following parameters:

https://<ip address of GRVA>/wsapi/ropverify.php?user=<username>&password=<password+OTP>

Windows Login

Green Rocket Security provides a Windows agent which allows Windows logins to enforce two-factor authentication. Any supported token can be used as the second factor (YubiKey, Google Authenticator, "Green Rocket 2FA" mobile apps, etc.) Contact us today for more details.

OTPs

Some token types require an OTP to be submitted (i.e. OTP, OATH, and Authenticator tokens.) By default, the OTP is to be appended to the password.

However, this configuration can be changed in the Global Configuration tab. The OTP Input Method setting allows you to change whether the OTP should be appended to the username, appended to the password, or have a separate field to prompt for the OTP. (The Prompt For OTP option is only available for RADIUS clients that support this feature.)

OTP Input Method

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

2FA for Windows Logon

GreenRADIUS can enforce two-factor authentication for Windows Logon. Our Windows Logon solution works with:

  • Windows PCs (Windows 7 and 10)
  • Windows Servers (2012 R2, 2016, and 2019)
  • domain-joined
  • non-domain-joined
  • desktop/physical logon
  • RDP logon
  • online logons
  • offline logons

During configuration, make sure GreenRADIUS is reachable from your Windows machines over ports 443 and 9443. Also, make sure GreenRADIUS has an active license that enables our U2F Module. (You can check this in the GreenRADIUS web admin interface on the License tab.)

Also, if you are adding 2FA to domain-joined Windows machines, make sure GreenRADIUS has a domain whose name matches exactly with the name of the domain that the Windows machines are joined to.

On each Windows machine, a small Green Rocket Security Windows agent will need to be installed when logged in as an administrator. (Contact us for our latest Windows agents.)

Windows Agent Configuration

  • Enable 2FA: This should be checked to enforce 2FA with GreenRADIUS. If unchecked, 2FA will not be enforced.
  • Disable 2FA for Administrator Accounts: If checked, all administrator accounts will bypass 2FA and will only need passwords to log in.
    • NOTE: If an offline login is attempted for a domain account, the login will always require 2FA, even if this checkbox is checked and the user is a domain administrator.
  • Disable 2FA in Windows Safe Mode: If checked, when Windows is booted in Safe Mode, 2FA will be disabled. (NOTE: In Safe Mode, the agent cannot be uninstalled, but the "Enable 2FA" checkbox can be unchecked.)
  • GreenRADIUS Server IP/Hostname for Online Authentication: Enter the IP address or hostname of GreenRADIUS. (The "https://" and ":9443/" will automatically be inserted.)
  • User Domain: Enter the GreenRADIUS domain where LDAP users have been imported. (Only one GreenRADIUS domain can be configured.)

After the above has been configured, click the Test button. You should see a successful message appear. If not, double check the GreenRADIUS IP address/hostname and the GreenRADIUS domain, and then try the Test button again.

The Custom... button will allow for more granular 2FA policies on the Windows machine. These policies will override policies in GreenRADIUS. (For example, if user1 has 2FA enforced in GreenRADIUS, but in the Custom... button, user1 is configured to bypass 2FA, user1 will only need a password to log in.)

After configuration, save the settings. You may be asked to restart in order for changes to take effect.

Online Authentication Attempts (GreenRADIUS is reachable)

After entering the username and password, users may use the following tokens for online authentication attempts:

  • YubiKey OTP: Insert the YubiKey in a USB port, and with the cursor in the OTP field, touch the YubiKey button.
  • YubiKey OATH-HOTP: Insert the YubiKey in a USB port, and with the cursor in the OTP field, touch the YubiKey button.
  • FIDO U2F tokens: Insert the FIDO U2F token in a USB port, leave the OTP field blank, and after entering the password, press the Enter key on your keyboard or click the login arrow on the screen. Then touch the FIDO U2F button after it starts to flash. The FIDO U2F token used the first time successfully to log in by the user will automatically be assigned to the user in GreenRADIUS. This auto-provisioning of FIDO U2F tokens is the only way these tokens can be assigned to users.
  • Authenticator app: Enter the current OTP from the Authenticator app into the OTP field. Then press Enter.
  • Green Rocket 2FA Mobile App: With no token inserted in a USB port, and after entering the password, press Enter. A push notification will be sent to the user's phone to approve or reject the logon attempt. Tap Approve on the app to log in.

Windows Logon Screen

Important Note: For local Windows user accounts, corresponding user accounts with the same usernames as the local user accounts must be present in the LDAP being used with GreenRADIUS. Then, those user accounts will need to be imported into GreenRADIUS. Also important, if tokens using OTPs are going to be used, the LDAP password for these users must be set to Pa$$word@123. This password is not necessary for users using FIDO U2F tokens and the Green Rocket 2FA Mobile App. Local users would still use their local Windows passwords to log in to Windows. (This fixed password will never be used for a Windows login.)

RDP Logon

To log in via RDP, launch the mstsc.exe application. After selecting the IP address or hostname, on the RDP logon screen, enter username and password only.

RDP Logon

Once that is successful, users will see the Windows Logon screen. The following tokens can be used:

  • YubiKey OTP: Insert the YubiKey in a USB port, and with the cursor in the OTP field, touch the YubiKey button.
  • YubiKey OATH-HOTP: Insert the YubiKey in a USB port, and with the cursor in the OTP field, touch the YubiKey button.
  • Authenticator app: Enter the current OTP from the Authenticator app into the OTP field. Then press Enter.
  • Green Rocket 2FA Mobile App: With no token inserted in a USB port, and after entering the password, press Enter. A push notification will be sent to the user's phone to approve or reject the logon attempt. Tap Approve on the app to log in.

Note: FIDO U2F tokens cannot be used for RDP logon attempts.

Offline Authentication Attempts (GreenRADIUS is not reachable)

Only FIDO U2F tokens can be used when the Windows machine cannot reach GreenRADIUS. The logon experience will be the same when using FIDO U2F tokens, whether the Windows machine is online or offline. Users will insert the FIDO U2F token in a USB port, leave the OTP field blank, and after entering the password, press the Enter key on the keyboard or click the login arrow on the screen. Then touch the FIDO U2F button after it starts to flash.

The FIDO U2F token used to successfully log in the first time in offline mode will automatically be assigned to the user. Offline FIDO U2F tokens are managed on the Windows agent on the PC or Server, not in GreenRADIUS. To unassign an offline FIDO U2F token, open the agent as an administrator, select the user, and click the "Unassign" button.

Token Type By Login

Token TypeOnline LoginOffline LoginRDP
YubiKey OTPYesNoYes
YubiKey OATHYesNoYes
YubiKey FIDO U2FYesYesNo
Authenticator AppYesNoYes
Green Rocket 2FA Mobile AppYesNoYes

Web Analytics Made Easy -
StatCounter

Updated 2021-09-10
© 2021 Green Rocket Security Inc. All rights reserved.

LDAP Authenticator Module

The GreenRADIUS LDAP Authenticator Module enables a way to implement two-factor authentication for applications and services that support authentication requests over the LDAP protocol. At times, it is advantageous to integrate third-party applications and services over LDAP instead of RADIUS, Web APIs, or other ways.

Prerequisites

  • GreenRADIUS v4.0.2.2 or above
  • GreenRADIUS license that enables the LDAP Authenticator Module
  • If GreenRADIUS has multiple domains configured on the Domain tab, only the users in the default domain will be able to log in
  • Certificate installed in GreenRADIUS from a trusted CA
  • Third-party application that supports authentication requests over the LDAP protocol

Steps To Configure the LDAP Authenticator Module

  1. Click on the Global Configuration tab. Then click the LDAP Authenticator Module icon.

  2. Enter the following configuration parameters:

  • DNS Domain Name: This name needs to be distinct from your Active Directory/LDAP domain name. It should not contain a space nor any special characters except hyphen or period. This domain is a proxy domain which is used to forward authentication requests received from third-party applications or services to GreenRADIUS.
  • Organization Name: This could be your organization or any name of your choice. It should not contain a space nor any special characters except hyphen or period.
  • Current Admin Password: Enter the current admin password. (By default, the current admin password is GreenRocket!23.)
  • New Admin Password: Enter a new password
  • Confirm Admin Password: Re-enter the new password

LDAP Authenticator Module screen

  1. Click the Update button. You should see a success message like the one below.

LDAP Authenticator Module confirmation screen

Steps To Configure Your Third-Party Application

Typically, the following configuration parameters need to be specified:

  • Base DN: Use the same DNS domain name configured in the GreenRADIUS LDAP Authenticator Module, for example, dc=example,dc=com
  • Bind DN: For example, cn=admin,dc=example,dc=com
  • Password: Enter the same admin password configured in the GreenRADIUS LDAP Authenticator Module.

Web Analytics Made Easy -
StatCounter

Updated 2021-10-06
© 2021 Green Rocket Security Inc. All rights reserved.

PIN Authentication

GreenRADIUS offers the ability to use a PIN instead of an LDAP password or as an additional authentication factor when this premium feature is enabled. PINs can be set per user, and the policy to use a PIN can be configured for each RADIUS client served by GreenRADIUS.

The first step is to enable PIN authentication for the desired RADIUS client. On the RADIUS Clients tab in the web admin interface, when adding a new RADIUS client or when editing an existing one, the "Multi-Factor Policy" can be selected from the dropdown list:

Authentication mode

From this list, admins can select to use standard LDAP password authentication ("Password + OTP"), to use the PIN in addition to the LDAP password ("Password + PIN + OTP"), or to exclude the LDAP password entirely and use PIN authentication alone ("PIN + OTP").

When the PIN feature is enabled, an extra column labelled "PIN Status" will display next to each user in the Users/Domains tab:

User view with PIN

From here, admins can select a user and click "Set/Update PIN" to change the PIN for the user:

Pin setting

Users can also set their own PINs from the Self-Service Portal by clicking the "Assign/Change PIN" button. Once authenticated, users will be prompted to enter a new PIN:

Self service pin setting

Note that PINs must have a certain length based on a PIN length policy. This is set to 8 digits by default, but can be changed in the Global Configuration tab under the General heading:

Pin length config

Note: This PIN feature is only available for applications and services configured as RADIUS clients in GreenRADIUS.

[NGS](./non-gui-settings.md)

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Date and Time Configuration

Basic Configuration

By default, GreenRADIUS uses the hardware clock to provide the system time.

The date command allows you to access and edit the system time relative to the current timezone:

~$ date
Mon Jun 10 22:10:31 UTC 2019

The timezone can be changed using the timedatectl command:

sudo timedatectl set-timezone <timezone>

A complete list of timezone specifiers can be obtained by running:

sudo timedatectl list-timezones | less

Once the timezone has been correctly set, use these commands to edit the system date and time.

sudo timedatectl set-time YYYY-MM-DD

and

sudo timedatectl set-time HH:MM:SS

(Time synchronization may be enabled, which may prevent manually updating the date and time. This can be disabled with this command: sudo timedatectl set-ntp 0. To re-enable time synchronization: sudo timedatectl set-ntp 1.)

If the system clock is already set when the timezone is changed, setting the timezone adjusts the system clock to remain temporally consistent. For example, the UTC tiemzone is 7 hours ahead of PDT. Therefore if the system clock registers ‘08:15 UTC’ and then timezone is changed to PDT, the system will now display ‘01:15 PDT’, which is the equivalent time.

Setting the clock back in time often has disastrous consequences for long-running programs which depend on the clock always moving forward. This should be avoided whenever possible.

Network Time Protocol

NTP (Network Time Protocol) is a TCP/IP protocol which allows you to synchronize the clocks of multiple servers to a single canonical source. NTP is designed to correct for network latency and ensure that all server clocks are synchronized and monotonic (they never move backwards while adjusting to synchronize with each other.) This document explains how to configure both the NTP server and client on your GreenRADIUS instances, providing greater consistency in timestamps and logging data.

In most configurations, one NTP server will be set up, with the rest of the servers synchronizing to its canonical clock. However, this document explains how to configure any topology of servers that is desired.

GreenRADIUS comes installed with NTP client software by default in GreenRADIUS version 4.2.1.1 or later. The command ntpq -p will display the list of sources which the GreenRADIUS instance is synchronizing its time to. You can edit these sources in the /etc/ntp.conf file. Each line beginning with the pool directive indicates a pool of NTP servers:

pool ntp.ubuntu.com iburst maxsources 4
pool 0.ubuntu.pool.ntp.org iburst maxsources 1
pool 1.ubuntu.pool.ntp.org iburst maxsources 1
pool 2.ubuntu.pool.ntp.org iburst maxsources 2

You can add additional servers by adding a line to the file:

server mytimeserver.s iburst

Note that the NTP client daemon only allows accesses to domain-name-defined servers, not IP addresses. To work around this problem for NTP servers that do not have an assigned domain name, simply add the IP address followed by the desired domain name to your /etc/hosts file:

192.168.56.118      mytimeserver.s

Changing /etc/hosts takes effect immediately when the file is saved; however, after any changes to /etc/ntp.conf you will need to restart the NTP service:

sudo systemctl restart ntp

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Certificates

The GreenRADIUS web admin interface GreenRADIUS's Web API are served exclusively over HTTPS. GreenRADIUS supports both self-signed certificates and certificates from certificate authorities.

The Global Configuration→Certificates tab will allow you to upload new certificates into your GreenRADIUS instance.

The Certificates tab

The Server Certificate Information segment displays the credentials of the certificate being served and the Certificate Authority. The Create Certificate segment will allow you to generate and upload your own self-signed certificate (CSR).

To upload a certificate from a trusted provider, open the Upload a certificate segment and select Upload a certificate created with the CSR generated externally.

Uploading a certificate

You will need to copy and paste the certificate, the complete trust chain extending back either to a Certificate Authority or to yourself (if the certificate is self- signed), and the private key. If the certificate was created with a passphrase, you'll need to provide that too.

Once uploaded, the GreenRADIUS instance will display a completion message. From this point on the certificate will be served as the SSL security for all web admin interface and Web API accesses.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Debugging and Reports

The Troubleshooting tab

Troubleshooting tab

If you need to troubleshoot your GreenRADIUS configuration, the Troubleshooting tab offers several tests you can perform to triage the problem:

  • The RADIUS test allows you to send a RADIUS request, bypassing the RADIUS IP address/secret filter.
  • The OTP test allows you to validate an OTP. This will help ensure that the secrets are correctly uploaded, the OTP is synced (if it is an OATH token), and the validation settings are correct.
  • The Ping test helps to ensure that an IP address or hostname is accessible by GreenRADIUS and that there is something on the other end.
  • The LDAP test performs an authentication using LDAP only without a second factor.

The Reports tab

Reports tab

Three types of report can be generated by GreenRADIUS. These reports list all events of a certain type. They can be filtered by date, time, and other filters to produce more informative results.

Authentication Requests

Authentication requests

An authentication request report lists all authentication attempts that have reached GreenRADIUS, whether they were successful or rejected. The report can be filtered by date, user, token type, and other filters.

Token Assignment

Token assignment

The token assignment report lists the time at which each token was assigned to a user. Like the authentication request report, it supports filtering by token type and token status.

Support Package

If you have a problem and contact GreenRADIUS support, you may be asked to generate a support package. This is an archive containing a copy of GreenRADIUS internal state and log files which provide more insight into any configurations and login attempts.

Generating a support package is done in the Global Configuration→Logging tab:

The Logging tab

Click the Generate button to create a new support package. This may take time. When the package is ready, it will be displayed along with the 15 most recent packages for download:

Package ready for download

You can then download the package and send it to Green Rocket Security to enable the Support team to better assist you.

Please note - If the issue is related to login attempts, it will be very helpful if detailed logging is enabled during the login attempts. These will then be captured in the support package and give the Support team more details to review.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Maintenance

License Files

GreenRADIUS licenses grant you a certain number of user-token assignments for a certain period of time. When the current license file expires, it is necessary to install a new one. Licenses can be obtained by emailing sales@greenrocketsecurity.com.

License installation is done from the License tab.

The License tab

The license tab displays the licensee, the expiration date of the currently installed license, and the number of user-token assignments of each type used out of the maximum allowed. To install a new license, click the Choose File button and select a license file to upload.

Once the new license is installed, you will see a completion message, and the license information will be updated.

Updates

GreenRADIUS updates are generally released monthly. Updates and release notes (including steps to apply the updates) are distributed to customers via email.

Updates include enhancements and security patches for the entire GreenRADIUS VM, from the operating system to the containers. There is no need to update any GreenRADIUS component manually or individually, outside of the updates provided by Green Rocket Security.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Appendix

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

GreenRADIUS Security Recommendations and Considerations

The following items are recommendations to consider to help secure your GreenRADIUS instances.

  1. Change default passwords
    • Web admin interface (change for both default users root and gradmin)
    • Command line (change for the gradmin user)
      • Note: The passwords for web admin interface users and command line users are managed separately, so be sure to change the default passwords for both
  2. Enforce two-factor authentication for GreenRADIUS admin accounts
  3. Replace the default self-signed certificate with a certificate signed by a trusted CA
  4. Restrict web admin interface access by IP address
    • Webmin > Webmin Configuration > IP Access Control
  5. Enable the UFW (onboard firewall) and set policies to restrict access (if an external firewall will not be used)
  6. If the onboard OpenLDAP nor the LDAP Authenticator Module will not be used, use a docker-compose-override file to prevent the OpenLDAP container from starting up
  7. Enable encryption of token secrets prior to importing or registering any tokens
    • Global Configuration tab > General
  8. If the YubiCloud will be used to validate YubiKey OTPs (instead of validating locally within GreenRADIUS), obtain a new Client ID and API Key from the Yubico site
    • Set in Global Configuration tab > Validation Server
  9. Set strong shared secrets when configuring RADIUS and ADFS clients
  10. Enable auto-logout after a certain period of inactivity in the web admin interface
    • Webmin > Webmin Configuration > Authentication
  11. Enable blocking of user accounts to prevent brute force attacks
  12. Make sure to apply the GreenRADIUS updates timely

Web Analytics Made Easy -
StatCounter

Updated 2021-06-26
© 2021 Green Rocket Security Inc. All rights reserved.

Migrating from GreenRADIUS v3.1.6.7 to v4.1.3.4

Introduction

GreenRADIUS version 4.1.3.4 is equipped with a tool to migrate users, tokens, and settings from v3.1.6.7. This document describes how to use the migration tool, detailing the steps to perform. It also covers how to deal with certain configurations not covered by the migration tool.

The following configuration is migrated with this tool:

  1. Database tables containing general configuration, user-token assignments, user information, domain information, directory server information, RADIUS clients, token states, token secrets, etc.
  2. Certificates
  3. License file
  4. RADIUS configuration

Additionally, the following configuration can optionally be migrated as well:

  1. Onboard firewall configuration
  2. Onboard OpenLDAP server configurations
  3. Network configuration migration, including DHCP settings and (if applicable) static IP address
  4. Hostname
  5. Time zone

Prerequisites

  1. The GreenRADIUS instance to migrate from must be running GreenRADIUS v3.1.6.7
  2. A fresh GreenRADIUS v4.1.3.4 must be deployed as the migration target
  3. The v4.X instance must be able to reach the v3.1.6.7 instance
  4. On the GreenRADIUS v3.1.6.7 instance, the gradmin command line user account (not the web admin interface account) needs to have a password that does not include special characters
  5. The Docker containers auto-start on boot. If the containers have been stopped manually, they need to be restarted before beginning the migration.
  6. For on-board OpenLDAP server configuration migration, a resolvable hostname/FQDN must be configured in GreenRADIUS v4.X as follows:
    • Log in to GreenRADIUS.
    • Navigate to Global Configuration→Certificate
    • Set the value in the Server Hostname/FQDN field.
    • Under the Create Certificate tab, enter a common name matching the hostname/FQDN configured in the above step. Click the Create and Install button.

Steps

Once GreenRADIUS v4.1.3.4 is running, invoke the migration script from the command line:

$ cd /home/gradmin/GRS-Migration-Tool/
$ sudo python migration.py

This will produce a dialog of migration options like this:

Migration Options

The migration tool prompts for the hostname or IP address of a v3.1.6.7 instance.

It will then request an administrator username and password of a command-line user on the v3.1.6.7 instance.

You will be prompted as to whether you wish to migrate on-board firewall configuration, on-board LDAP configuration, hostname, network, and timezone settings.

The migration process may take some time. When it is finished, a completion message will be displayed:

Migration Complete

If your v3.1.6.7 instance was configured not to use DHCP, then the v4.1.3.4 instance will try to use its IP address the next time it starts (if you selected to migrate the network configuration.) To prevent the GreenRADIUS instances from colliding over the IP address, you should shut both down and then reboot only the v4.1.3.4 instance without rebooting the v3.1.6.7 one.

After reboot, you will find that most settings from your v3.1.6.7 instance have been migrated.

IMPORTANT NOTE: If there are multiple servers configured in synchronization, one GreenRADIUS v4.1.3.4 instance should be deployed for each v3.1.6.7 instance and migration from each v3.1.6.7 instance should be done to the corresponding v4.1.3.4 server instance. Once the migration is done, the server entries in the synchronization configuration should be deleted and re-added on each of the v4.1.3.4 server instances.

Additionally, in some cases, the network configuration is not migrated.
In such cases, manually configure the network by following our network configuration guide.

Settings to Check and Configure Manually

Not all settings are migrated. Please be sure to check the following settings and make changes as necessary:

  1. YubiKey OATH-HOTP OTP length (in case YubiKeys programmed in OATH-HOTP mode are being used, this setting is found under Global Configuration→General)
  2. User portal OATH algorithm for soft tokens (in case Google Authenticator or similar soft tokens are being used, a setting of TOTP is recommended, this setting is found under Global Configuration→User Portal)
  3. Temporary tokens must be re-established for those users assigned temporary tokens
  4. LDAP server certificates (in the Directory Server tab of the GreenRADIUS domain) if you are using secure connection (over port 636)
  5. Local web admin console user accounts and settings

Contact Green Rocket Security for further instructions to upgrade from v4.1.3.4 to the latest GreenRADIUS version

Web Analytics Made Easy -
StatCounter

Updated 2021-10-21
© 2021 Green Rocket Security Inc. All rights reserved.

GreenRADIUS – Rocket Evaluation Guide

Start Testing Greenradius In Less Than 15 Minutes!

This guide is intended for those that want to evaluate GreenRADIUS and its features quickly before integrating it with external user directories (such as Active Directory) and external RADIUS clients (such as VPN with Cisco, Palo Alto Networks, SonicWALL, and other devices and applications that authenticate with the RADIUS protocol).

Step 1 – Import OVA File In VMWare Or Oracle Virtualbox

After downloading the GreenRADIUS OVA file, import it into either VMware or Oracle VirtualBox. If DHCP is set up, the appliance will try to find an available IP address. If one is not set up automatically or if you would like to change the IP address later, see our guide for configuring network settings.

Step 2 – Log In To The Web Console

After an IP address is assigned, open a new browser tab and go to https://<IP address of GreenRADIUS>/admin.

The default credentials are:

  • Username: gradmin
  • Password: GreenRocket!23

Step 3 – Review The Sample Domain

GreenRADIUS includes a pre-configured, sample domain named greenradius.demo. (This can be deleted later, and new domains can be created and configured.) Click on the Domain tab, then click on greenradius.demo. Five test users are included in this domain from the onboard OpenLDAP that is included in the virtual appliance. All five test users have a default password of GreenRocket!23.

To access the onboard OpenLDAP, use a third-party LDAP admin tool, such as LDAP Admin. The default credentials are:

  • Username: cn=admin,dc=greenradius,dc=demo
  • Password: GreenRocket!23

By default, this domain has our Gradual Deployment feature enabled, so that all test users are in single-factor mode (meaning only username and password are required for authentication). After a test user successfully authenticates with a security token (such as a YubiKey or Google Authenticator), the single-factor mode for that user will be disabled so that the user must use two-factor authentication (password + security token) going forward.

Step 4 – Single-Factor Authentication

Click on the GreenRADIUS Virtual Appliance link on the left. Then click on the Troubleshoot tab. The RADIUS Test section at the top can be envisioned to stand in for a client or login page that requires a username and password.

In the username field, enter “user1”. In the password field, enter “GreenRocket!23”. (We will leave the OTP field blank for this single-factor test authentication.) Then click the Send Request button. You should see a response of “Successful”.

Step 5 – Assigning A Google Authenticator Token To A User

In a new browser tab, go to https://<IP address of GreenRADIUS> (with nothing else after the IP address). This is the user self-service portal where a user can self-assign tokens, including Google Authenticator.

Follow these steps to assign Google Authenticator to a user:

  1. Click the “Assign a Token” button.
  2. In the Username field, enter “user1”. Then click Proceed.
  3. In the Password field, enter “GreenRocket!23”. Then click Submit.
  4. Click on the Google Authenticator radio button at the top.
  5. Open the Google Authenticator app on your phone. (If you do not already have it installed on your phone, please download and install the free app.)
  6. In the Google Authenticator app, navigate to set up a new account and click “Scan a barcode”.
  7. The Google Authenticator app will launch a barcode scanner (like a camera). Scan the barcode on your browser.
  8. Once the barcode is captured and a new token is displayed (with six numeric characters), click the Proceed button.
  9. Enter the current six-digit OTP in Google Authenticator (assigned to user1@greenradius.demo) in the OTP field. Then click the Verify button. You should receive a successful response.

Step 6 – Two-Factor Authentication

Go back to the Troubleshoot tab. In the RADIUS Test section, enter “user1” in the Username field, enter “GreenRocket!23” in the Password field, and enter the current six-digit OTP in Google Authenticator in the OTP field. Then click the Send Request button. You should see a response of “Successful”. (If you see a response of “Failed”, make sure that the server time is correct by following these steps.)

With this same user (user1), you can try with username and password only, and you will notice that the attempt now fails. Since the user has successfully authenticated with a token (Google Authenticator), this user must use two-factor authentication going forward. (Admins can change this for individual users in the Users/Groups tab in the Domain tab.)

One other note – This RADIUS test section has three separate fields for username, password, and OTP. When RADIUS clients are eventually set up, the default configuration in GreenRADIUS is for users to submit credentials this way:

  • Username field of client or login page: username
  • Password field: password immediately followed by OTP (no spaces or characters in between)

If you run into any issues or have further questions, please do not hesitate to contact us at 888-793-3247 or +44 808 234 6340 or email us at info@greenrocketsecurity.com.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

GreenRADIUS – Quick Start Guide

This guide is intended for those that want to evaluate GreenRADIUS and its features quickly by integrating it with external user directories (such as Active Directory) and external RADIUS clients (such as VPN with Cisco, Palo Alto Networks, SonicWALL, and other devices and applications that authenticate with the RADIUS protocol).

If you would like to evaluate GreenRADIUS before integrating with your user directory and your RADIUS clients, please refer to our GreenRADIUS "Rocket" Evaluation Guide.

Step 1 – Import OVA File In VMWare Or Oracle Virtualbox

After downloading the GreenRADIUS OVA file, import it into either VMware or Oracle VirtualBox. If DHCP is set up, the appliance will try to find an available IP address. If one is not set up automatically or if you would like to change the IP address later, see our guide for configuring network settings.

Step 2 – Log In To The Web Console

After an IP address is assigned, open a new browser tab and go to https://<IP address of GreenRADIUS>/admin.

The default credentials are:

  • Username: gradmin
  • Password: GreenRocket!23

Step 3 - Set Up a New Domain

GreenRADIUS includes a pre-configured, sample domain named “greenradius.demo”. (You can keep this or delete it, since a new domain will be created.)

In the Domain tab, enter your domain name in the field, then click the “Add Domain” button. Then click on the newly created domain.

Step 4 – Importing Users

Go to the “Directory Server” tab. Enter the IP address of your Active Directory, OpenLDAP, or 389DS. Then enter the username and password of an administrator’s credentials. Click the “Proceed” button.

Complete the additional fields to import users from your Active Directory or OpenLDAP. Note the following:

  • For the “Login Name Identifier”:
    • For Active Directory, “sAMAccountName” is common, but other identifiers can also be used.
    • For OpenLDAP, use “uid”
  • The “Set Frequency” drop-down menu sets the scheduled frequency that GreenRADIUS will import/update users from your user directory.

Once all fields have been configured, click the “Save and Import” button to import users.

The import operation should begin. If the import is successful, the end of the message will read “Successfully updated users records. User Import operation completed.” Click “Return to previous page”.

Step 5 – Configuring A RADIUS Client

Go to the “RADIUS Clients” tab.

Enter the IP address or hostname of the RADIUS client you want to integrate with GreenRADIUS. (You could also enter a subnet.) Then, enter a shared secret (entirely up to you what you want to use) in the two client secret fields. Then, click the “Add” button.

In the admin/management screen/portal of the client you are configuring with GreenRADIUS, make sure to direct authentications to GreenRADIUS and use the same shared secret as configured in GreenRADIUS.

At this point, you can test single-factor authentications through your normal logon client/page.

Step 6 – Enable Gradual Deployment (Optional)

GreenRADIUS can make implementation easy with the Gradual Deployment feature. When enabled, GreenRADIUS will automatically enforce two-factor authentication for a user after the user’s first successful authentication with password and token. For users that have yet to use a token, they will remain needing only to use their password to successfully authenticate until they use their token or until the Gradual Deployment feature is disabled.

To enable Gradual Deployment, in the Configuration tab of the domain, set the “Enable Gradual Deployment” setting to “Yes”. Then click the “Update” button.

Note – Changing this setting from “No” to “Yes” will set all users to needing only passwords (single factor only) to authenticate, even those users that have tokens assigned or are set to needing tokens to authenticate. You can check each user’s requirement under the “Single Factor Flag” column in the “Users/Groups” tab. A green check mark means the user only needs a password. A red X means the user needs password and token.

Step 7 – Enable Auto-Provisioning Of YubiKeys (Optional)

Auto-provisioning of YubiKeys to users can be done automatically in GreenRADIUS. When this feature is enabled, users are auto-assigned YubiKeys upon first successful authentication with an unassigned YubiKey. No separate registration of the YubiKey to the user is required.

To enable this feature, in the Configuration tab of the domain, set the “Enable Auto-provisioning For YubiKey Tokens” to “Yes”. Then click the “Update” button. (Make sure this setting is also set to “Yes” in the “General” settings in the Global Configuration tab.)

If you run into any issues or have further questions, please do not hesitate to contact us at 888-793-3247 or +44 808 234 6340 or email us at info@greenrocketsecurity.com.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Configuring Our GRS PAM Module for 2FA for RedHat, CentOS, or Ubuntu

Introduction

GreenRADIUS can be used to enforce two-factor authentication for access to RedHat, CentOS or Ubuntu machines. One way to do this is with our custom GRS PAM Module. Our GRS PAM Module uses HTTPS communication instead of RADIUS, avoiding the need to manage each machine as a RADIUS client.

The following login methods can be protected with the GRS PAM Module:

  • SSH
  • console
  • sudo
  • GNOME

Contact us today to evaluate GreenRADIUS with our custom GRS PAM Module.

Prerequisites

  1. GreenRADIUS with users imported and reachable from the client machine running RedHat/CentOS 6, 7, or 8, or Ubuntu 16, 18, or 20
    • Users imported into GreenRADIUS from your LDAP must have matching usernames with local user accounts on the Linux machine
  2. GRS PAM Module from Green Rocket Security (at least v2.2.2).
  3. SELinux must be disabled or set to permissive mode on the client machine, if it is installed (it is usually installed on RedHat/CentOS). You can change the SELinux configuration in the /etc/selinux/config file.
  4. You will need a version of Python (Python 3 on every system except RedHat 6 or CentOS 6) and the corresponding Requests module.
    • RedHat/CentOS 6: sudo yum install python and sudo yum install python-requests
    • RedHat/CentOS 7: sudo yum install python3 and sudo pip3 install requests
    • RedHat/CentOS 8: sudo yum install python3 and sudo pip3 install requests
    • Ubuntu 16: sudo apt install python3 python3-requests
    • Ubuntu 18: sudo apt install python3 python3-requests
    • Ubuntu 20: sudo apt install python3 python3-requests

Steps

  1. Run sudo su - to enter super user mode
  2. Unpack the provided module archive. You should have three files: make_request.py, config, and grs_pam.so.
    • The make_request-centos6.py file is the make_request file for RedHat/CentOS 6. If you are using this OS, delete make_request.py and rename make_request-centos6.py to make_request.py.
  3. Run chmod +x make_request.py
  4. Run chmod +x grs_pam.so
  5. Run mkdir /etc/grs-pam
  6. Run mv make_request.py /etc/grs-pam
  7. Run mv config /etc/grs-pam
  8. If and only if your OS is RedHat 6 or CentOS 6: Edit the /etc/grs-pam/make_request.py file and change #!/usr/bin/python3 to #!/usr/bin/python. If the first line already reads #!/usr/bin/python, this step can be skipped.
  9. Move the grs_pam.so to the appropriate location depending on your OS:
    • RedHat/CentOS 6: /lib64/security
    • RedHat/CentOS 7: /lib64/security
    • RedHat/CentOS 8: /lib64/security
    • Ubuntu 16: /lib/x86_64-linux-gnu/security
    • Ubuntu 18: /lib/x86_64-linux-gnu/security
    • Ubuntu 20: /lib/x86_64-linux-gnu/security
  10. Edit the /etc/grs-pam/config file to update the following:
    • SERVER: the IP address/hostname of the GreenRADIUS instances or a list of IP addresses/hostnames
      • e.g. [SERVER:greenradius]
    • VERIFY_SSL: flag to enable/disable peer certificate verification
      • [VERIFY_SSL:YES] - for enforcing certificate verification
      • [VERIFY_SSL:NO] - for disabling certificate verification
    • CERT: the absolute path to a CA_BUNDLE file or directory of trusted CA certs to be used to verify the GreenRADIUS certificate
      • e.g. [CERT:/etc/ssl/certs/ca-bundle.crt]
      • NOTE: If a directory is specified with CERT, it must have been processed using the c_rehash utility supplied with OpenSSL.
    • TIMEOUT: the number of seconds the PAM module will wait for GreenRADIUS to respond
      • e.g. [TIMEOUT:10]

It is possible to configure multiple GreenRADIUS servers by using a set of SERVER directives. Timeout and certificate settings must be configured separately for each server with the appropriate TIMEOUT, VERIFY_SSL, and CERT directives. In this configuration, the PAM module will attempt to contact each server in turn. If one server fails to respond, the next is tried. This is useful for high availability configurations.

GRS PAM Module Configuration

  1. Edit one of the following files depending on which login method(s) you want to protect:
    • SSH: /etc/pam.d/sshd
    • console: /etc/pam.d/login
    • sudo: /etc/pam.d/sudo
    • GNOME: /etc/pam.d/gdm-password
    • GNOME Screen Lock: /etc/pam.d/gnome-screensaver
  2. Add this line at the top of the file: auth required grs_pam.so.
  3. Add a # in front of the following line to comment it out:
    • RedHat/CentOS 6: auth include password-auth
    • RedHat/CentOS 7 or 8: auth substack password-auth
    • Ubuntu: @include common-auth
  4. Try a test login attempt with a user. In the password field, enter Password+OTP (append OTP to the end of the password), then hit Enter.

If you have any questions during your evaluation or configuration, please do not hesitate to contact us!

Updated 2021-06-09
© 2021 Green Rocket Security Inc. All rights reserved.

Integration Guide for Palo Alto Networks GlobalProtect VPN

Before starting, make sure GreenRADIUS is configured with users imported from your LDAP and can communicate with your Palo Alto GlobalProtect device.

Configuring GreenRADIUS for Palo Alto GlobalProtect

In the GreenRADIUS web admin interface, add the Palo Alto GlobalProtect as a RADIUS client.

  1. Click the Domain tab
  2. Click the domain name where you want to add the Palo Alto GlobalProtect as a RADIUS client
  3. Click the RADIUS Clients tab
  4. Enter the IP address of the Palo Alto GlobalProtect. Then enter the same RADIUS secret twice. Then click the Add button.

RADIUS Client Configuration

Configuring Palo Alto GlobalProtect

Add GreenRADIUS as a RADIUS Server

  1. Log in to the Palo Alto GlobalProtect admin interface
  2. On the Device tab, navigate to Server Profiles, then RADIUS. Click Add.
  3. In the Name field, enter "GreenRADIUS"
  4. Set the timeout value to 10 seconds (or 45 seconds if using our Green Rocket 2FA Mobile App)
  5. Configure the "Authentication Protocol" drop-down to "PAP". Note: PAN-OS 7.X users must set the protocol via command line using this command: set authentication radius-auth-type pap
  6. In the Servers section, click Add. Then enter the following:
  • Server: GreenRADIUS
  • RADIUS Server: [IP address or hostname of GreenRADIUS]
  • Secret: [enter the same RADIUS secret as configured in GreenRADIUS for the Palo Alto GlobalProtect]
  • Port: 1812
  1. Click OK

RADIUS Server Profile

Add an Authentication Profile

  1. On the Device tab, navigate to Authentication Profile
  2. Click the New... button. Then enter the following:
  • Name: GreenRADIUS
  • Type: RADIUS
  • Server Profile: GreenRADIUS
  • User Domain: Optional, leave blank if you only have one domain configured in GreenRADIUS
  • Username Modified: Optional, leave blank if you only have one domain configured in GreenRADIUS
  1. Click the Advanced tab. In the "Allow List" section, select the "all" group.
  2. Click OK

Authentication Profile

Configure Palo Alto GlobalProtect

  1. On the Network tab, navigate to GlobalProtect, then Gateways
  2. Click on the GlobalProtect Gateway to display the properties window
  3. On the Authentication tab, select the GreenRADIUS authentication profile

Authentication Profile

  1. Click the Agent tab, then click the Client Settings tab. Click the name of your configuration.
  2. On the Authentication Override tab, check the checkboxes for both Generate cookie for authentication override and Accept cookie for authentication override. Set the Cookie Lifetime as desired. Select a certificate to use with the cookie.

Authentication Override

  1. Click OK twice

Configure the GlobalProtect Portal

  1. On the Network tab, navigate to GlobalProtect, then Portal
  2. Click on your GlobalProtect Portal to display the properties window
  3. On the Authentication tab, select the GreenRADIUS authentication profile

Authentication Profile

  1. Click the Agent tab, then click the name of your configuration.
  2. On the Authentication tab, check the checkboxes for both Generate cookie for authentication override and Accept cookie for authentication override. Set the Cookie Lifetime as desired. Select a certificate to use with the cookie.

Authentication Override

  1. Click OK twice

Commit and Save the Settings

  1. Click the Commit button to make the changes take effect

You may now start testing Palo Alto GlobalProtect logins. Check the Authentication Requests report in GreenRADIUS (under the Reports tab) to make sure Palo Alto GlobalProtect logins are being validated by GreenRADIUS.

Web Analytics Made Easy -
StatCounter

Updated 2021-09-28
© 2021 Green Rocket Security Inc. All rights reserved.

ADFS Integration

GreenRADIUS 2FA can be integrated with Active Directory Federation Services (ADFS).

This deployment and configuration guide assumes the following:

  • GreenRADIUS (v4.1.11.11 or later) has been deployed and configured
  • The ADFS Server role has been installed and configured in either Windows Server 2016 or 2019
  • Applications and services are already set up in ADFS as relying parties

GreenRADIUS Configuration

  1. In the GreenRADIUS web admin interface, click on the Global Configuration tab.

GreenRADIUS Global Configuration tab

  1. Click the Client-based Authentication Policies icon.
  2. In the Add Client page, configure the following settings:
  • Client ID: This is an admin-defined value and should be the same Client ID as configured in the ADFS adapter.
  • Description: This is an optional field.
  • Shared Secret: This is an admin-defined character string and must match with the Shared Secret configured in the ADFS adapter.
  • Type: Set to ADFS
  • Multi-Factor Policy: The configured setting will be enforced for user logins:
    • Password + OTP: Password and OTP (or mobile push app)
    • PIN + OTP: PIN and OTP (or mobile push app)
    • Password + PIN + OTP Password, PIN, and OTP (or mobile push app)
  • Enable First Factor Validation (Password/PIN) Through GreenRADIUS: Set to No
  • Enable Auto-provisioning: If set to Yes, YubiKeys (when OTPs are used) will be automatically assigned to users upon the first successful login with the YubiKey if the user does not already have a YubiKey assigned.
    • Note: To enable auto-provisioning of YubiKeys for use with ADFS, not only must this be set to "Yes", but also at the global and domain level.

Client-based Authentication Policies

  1. Click the Add button.

Install and Configure the GreenRADIUS ADFS MFA Adapter

  1. Download the GreenRADIUS ADFS MFA Adapter. (You can obtain the latest version by contacting us.)
  2. Logged in as an admin on the Windows Server with the ADFS server role, double-click the GreenRADIUS ADFS 2FA Adapter installer. After a few progress bars, a welcome screen appears. Click Next.

Welcome screen

  1. Accept the license agreement and click Next.

License screen

  1. Click Install.

Install screen

  1. After the installation is complete, click Finish.
  2. Open the GreenRADIUS ADFS MFA Adapter Configuration application

GreenRADIUS URL screen

  1. Click the Global Configuration tab.
  2. Configure the following settings:
  • Request Processing Scheme
    • Ordered List: The first GreenRADIUS instance listed will be contacted first for user authentication, then the next, and so on.
    • Round Robin: The next GreenRADIUS instance will be contacted first for user authentication, rotating through the list of GreenRADIUS instances with each new login attempt.
  • Server Connection Timeout: The time (in seconds) for which the ADFS client waits for each GreenRADIUS instance to respond.
  • Dead Server Detection Threshold: Indicates the maximum number of consecutive login attempts to be made to a configured GreenRADIUS instance before marking the instance as "dead"
  • Server Dead Time Interval: The time (in seconds) for which a server marked as dead will not be contacted.
  • Client ID: Should be the same Client ID as configured in all GreenRADIUS instances.
    • Note: The client ID must be unique and not already used by another ADFS client.
  • Shared Secret: This must match the shared secret configured in each GreenRADIUS for this ADFS client.

ADFS Global Configuration

  1. Click the Server List tab.
  2. Add GreenRADIUS instances and enable them.

ADFS Server List

  1. Click the Save and Apply button.
  2. Launch the ADFS management application. Right-click on Authentication Methods and select Edit Multi-factor Authentication Methods.

Edit MFA Methods

  1. A list of authentication providers will be shown. Select/Enable Green Rocket Security MFA for AD FS, and then click Apply.

MFA providers screen

  1. Restart the ADFS service.

Configuring the GreenRADIUS ADFS MFA Adapter/Plugin

  1. Launch the ADFS management application. Right-click on Access Control Policies and select Add Access Control Policy....

Access control policies

  1. An "Add Access Control Policy" screen will appear. In the Name field, enter a name for this new access control policy.

Access control policy name

  1. In the "Rule Editor" screen, under the "Permit" section, select users and check the checkbox for and require multi-factor authentication. Then click OK.

Rule editor screen

  1. Click on Apply, then OK to save changes.

Associate Access Control Policies to Relying Parties in ADFS

  1. In the ADFS management application, right-click on Relying Party Trusts, and select a relying party trust to configure.
  2. From the list of available access control policies, select the policy that was just configured above that requires multi-factor authentication.

Select access control policy

  1. Restart the ADFS service.

User Logins with GreenRADIUS MFA for ADFS Relying Parties

At this point, the ADFS service is ready to authenticate users and their second factor with GreenRADIUS. If the relying party is configured with an access control policy requiring multi-factor authentication with GreenRADIUS, users will see the following screen (or similar) after logging in with their username and password.

Second factor login screen

The following tokens are currently supported:

  • YubiKeys: YubiKey OTPs are supported. With the cursor in the blank field, after inserting the YubiKey, the user simply touches the YubiKey button.
  • Google Authenticator: Google Authenticator and other Authenticator apps are supported as well. In the blank field, the user enters the current six-digit OTP in the Authenticator app, then clicks Continue.
  • Green Rocket 2FA Mobile App: Our Green Rocket 2FA Mobile App can also be used. The user leaves the field blank and clicks Continue. The user should then receive a push notification on his or her mobile phone and tap Approve to complete the login.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Configuring WordPress for GreenRADIUS 2FA

Introduction

GreenRADIUS can be used to enforce two-factor authentication for Wordpress installations.

Contact us to evaluate our WordPress plugin for GreenRADIUS 2FA.

Prerequisites

  1. A WordPress server, with administrative permissions to modify it.
  2. A publicly accessible GreenRADIUS instance with a valid certificate installed. The certificate must be trusted by the WordPress instance.
  3. The WordPress 2FA plugin from Green Rocket Security

Steps

  1. Log into your administrative account on WordPress.
  2. Click the "Plugins" menu in the left tab, then select "Add New" > "Upload Plugin".
  3. Select the .ZIP file from Green Rocket Security, and upload it.
  4. Select "Plugins" -> "Installed Plugins" from the left menu.
  5. Click "Activate" under the "GreenRADIUS Authentication" entry.
  6. In the left menu, select "Settings" > "GreenRADIUS Authentication".

WordPress settings

  1. Enter the hostname of the GreenRADIUS instance and click "Save".
  2. When you next attempt to log into the WordPress instance, you should see an OTP field:

Wordpress login with GreenRADIUS

  1. Log in with a user that is imported in GreenRADIUS. (Only user accounts in GreenRADIUS can now log in. Local WordPress user accounts that do not have a matching LDAP username imported into GreenRADIUS will no longer be able to log in with local credentials.

For example, if there is an existing WordPress user account with a username of "jdoe", there needs to be a corresponding LDAP user account with a username of "jdoe". This LDAP user account also needs to be among the users imported into GreenRADIUS, so that there is a "jdoe" user account in GreenRADIUS.

GreenRADIUS Validation of Token Only

The WordPress plugin and GreenRADIUS can be configured so that WordPress validates the user's local WordPress password and GreenRADIUS validates the token. To do this, follow the steps below:

  1. In the plugin settings, check the "Split Authentication" checkbox and click the Save button

WordPress plugin settings

  1. In the GreenRADIUS web admin interface, go to the "Global Configuration" tab and click the "General" icon
  2. Set "Enable Password Authentication Through GreenRADIUS" to "No".
  • NOTE: This GreenRADIUS setting is a global setting. It will enable or disable password validation through GreenRADIUS for all RADIUS and Web API integrations.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Programming YubiKeys with the GRS Programming/Auto-Import Tool

Green Rocket Security provides a Windows-based YubiKey programming tool, which programs YubiKeys and also automatically uploads the newly-generated YubiKey secrets to GreenRADIUS in a single-step process. These are the steps to install and use the programming tool.

  1. Contact Green Rocket Security to receive a copy of the programming tool installation EXE.
  2. Run the installer as administrator. The programming tool will be installed to the AppData directory for your user. A shortcut will also appear in the Start Menu.
  3. Enable the programming API on GreenRADIUS, if you have not done so already. To do this, log into GreenRADIUS, either in the console or via SSH, and run the command sudo docker exec -it GRVA-MAIN changepassword grsapiusr. This will prompt you for a new password for the grsapiusr API user.
  4. Insert your YubiKey in a USB port.
  5. Launch the programming tool as an administrator. To do this, find its entry in the Start Menu, right-click it, and select "Run as Administrator" from the list of options that appears.
  6. You will need to enter the hostname or IP address of GreenRADIUS as well as the username (grsapiusr) and password. The password is the one configured in Step 3. Entering the connection information
  7. The tool will now automatically program your YubiKey with a random secret and upload the data to GreenRADIUS. You will be able to see the new token appear in the "List Tokens" screen of the web admin interface.
  8. You can program as many keys as your wish successively, or exit the tool once you are finished. The data for each key is imported to GreenRADIUS as it is generated, so no final "save" step is necessary.

Configure GreenRADIUS to Validate YubiKeys Locally

To use the tokens, you will need to set your GreenRADIUS to use local validation, since the secrets are stored locally rather than in the YubiCloud. To do this:

  1. In the GreenRADIUS web admin interface, click the Global Configuration tab.
  2. Select "Validation Server".
  3. Set the server to "Local validation server on GreenRADIUS Virtual Appliance" and click "Save" to commit your changes.

Configuring the validation server

Once this is done, you will be able to use your YubiKeys with GreenRADIUS validating OTPs locally.

Web Analytics Made Easy -
StatCounter

Updated 2021-06-03
© 2021 Green Rocket Security Inc. All rights reserved.

Management APIs

Customers may make use of HTTPS management APIs for specific administrative operations in GreenRADIUS. These allow customers to write their own frontend software to administer their GreenRADIUS instance.

This document lists the endpoints for these APIs and provides examples of how to call each one.

All of these APIs require that the management API password be configured. You can do this by executing the following command from the shell on your GreenRADIUS instance:

sudo docker exec -it GRVA-MAIN changepassword grsapiusr

All requests require parameters to be supplied in the request body as a JSON structure. The Content-Type of the request must be set to application/json. Authentication is required for each request in the form of BasicAuth username/password tokens.

For example, to call the API from Python, you could use the following:

import requests

HOST = 'greenradius.example.com'

requests.post(
    'https://'+HOST+'/gras-api/v2/mgmt/import_token/yubikey',
	auth = ('grsapiusr', 'GreenRocket!23'),
	json = {
    	"yubikeys" : [
            {
                "make": "Yubico OTP",
                "serialno": 3014781,
                "publicname": "ddvcuttiuejt",
                "internalname": "8b428d0f016f",
                "aeskey": "a55adb9c4da2ad57c529737fd4d5ecd0"
            }
        ]
    }
)

The APIs are:

Reporting Batch Results

Many of the endpoints allow one to send multiple entries as part of a single request. For example, the YubiKey Import endpoint enables you to send several YubiKey token entries with one request. When this happens, it is possible for some of the assignment requests to succeed and some to fail. Therefore, these endpoints use result batches to report the results of individual logins, rather than reporting the entire batch as a single success or failure.

A result batch is a JSON structure with the following entries:

{
    "count": 2,
    "records": {...}
}

The count is either an integer or a string (callers must expect either.) It indicates the number of results in this batch. The records entry is a JSON structure, unless count is 0, in which case it is the empty list []. It will contain count key-value pairs, each of which represents the result of one of the entries in the initial request. The value will vary depending on which type of batch and which endpoint; the key is always a string (not an int) of the index, starting from 1, of the request in the initial list passed to the endpoint.

For example: say a fictional endpoint square, which computes N2, is called with five individual entries:

{
    "numbers": [
        5,
        2,
        "invalid input",
        6
    ]
}

The result might be two result batches, one containing successes and one containing failures:

{
    "numbers_squared": {
        "count": 3,
        "records": {
            "1": 25,
            "2": 4,
            "4": 36
        }
    },
    "numbers_invalid": {
        "count": 1,
        "records": {
            "3": {...}
        }
    }
}

numbers_invalid["records"]["3"] would be an error structure, as described below.

Error Reporting

Error Structure

Errors are reported as a structure with the following entries.

KeyValue TypeValue Description
codeIntAn integer numerical code describing the error.
shortStringA short, non-user-friendly description of the error.
descriptionStringA longer, more user-friendly description of the error.

Table of Error Codes

CodeError
4000The Content-Type of the request is not application/json.
4001One of the input parameters is invalid.
4002A required input parameter is missing.
5000No user found.
5001The user already has the maximum number of tokens allowed.
5002The token is already assigned to the user.
5003Assigning a token to a user failed.
5004The requested YubiKey token is not present.
5005The maximum number of users has been exceeded.
5006The token could not be assigned because user-level authentication failed due to invalid credentials.
5026The requested assignment was not found.
5051The YubiKey token is already present.

Import a YubiKey Token

Overview

This endpoint imports a new YubiKey token. The token will not be assigned to any user, but it will be added to the GreenRADIUS database.

Request Type: POST
Endpoint Path: /gras-api/v2/mgmt/import_token/yubikey

Parameters

{
    "yubikeys" : [...]
}

Each item in the provided list of YubiKeys must be a JSON structure with the following elements:

AttributeTypeDescription
makeStringThe make of this particular token. Should always be set to "Yubico OTP".
serialnoIntThe serial number of the YubiKey.
publicnameStringThe key's public ID.
internalnameStringThe key's private ID.
aeskeyStringThe secret AES-128 key associated with the YubiKey.

Return Values

If the request parameter is valid and adheres to the specified format, the endpoint will return a JSON structure similar to the following:

{
    "records_imported": {...},
    "records_invalid": {...},
    "records_skipped": {...}
}

Each of records_imported, records_invalid, and records_skipped will contain a request batch structure. Within this records_imported structure, each record in the batch will be a structure with keys status, make, serialno, and publicname. The latter three elements are the same ones that were passed in; the status attribute is always set to "success".

For failed requests (this includes both records_invalid and records_skipped), the value will be an error entry. Attempting to import a key that is already present in the database is considered an error; that key will be counted in records_skipped.

For an error which makes it impossible to parse the key import requests (such as, for example, the yubikeys parameter is missing entirely or is the wrong type) then the request value will simply be an error structure.

Delete a YubiKey

Overview

This endpoint deletes a YubiKey from the database.

Request Type: DELETE
Endpoint Path: /gras-api/v2/mgmt/delete_token/yubikey

Parameters

{
    "deletealways": false,
    "yubikeys": [...]
}
ParameterTypeDescription
deletealwaysBoolIf true, the YubiKeys will be deleted even if they are currently assigned to users. If false, those requests will instead produce error entries. This parameter is optional and defaults to false.
yubikeysListA list of YubiKeys to delete. Each YubiKey is a JSON structure with a single entry publicname, which is the Public ID of the YubiKey.

Return Values

If the request is validly formed, the response will be a JSON structure of the form:

{
    "records_deleted": {...},
    "records_invalid": {...},
    "records_skipped": {...}
}

Each of these is a batch structure; records_invalid and records_skipped contain an error structure for each failed deletion. records_deleted contains a batch structure, whose individual entries are of the following form:

{
    "status": "success",
    "publicname": "..."
}

publicname will be the public name of the deleted key.

If the request is not validly formed, the response will be an error structure.

Assign a Token

Overview

The endpoint assigns tokens to users. Unlike the YubiKey import endpoint, it is not restricted to any particular type of token.

Request Type: POST
Endpoint Path: /gras-api/v2/mgmt/mappings

Parameters

{
    "assignments" : [
        {...}
    ]
}

Each assignment entry should be a structure with the following elements:

AttributeTypeDescription
usernameStringThe target user to assign the key to. This must be supplied in user@domain format.
publicnameStringThe public ID of the token to assign to the user.

Return Values

Like the other endpoints, this returns a single error structure if the input is invalid. However, it does not return regular batch structures on success. Instead, the output is in the following format:

{
    "assignments": [...]
}

Each item in the assignments list corresponds to one of the entries in the original request. These are structures with two entries, input and output. The input attribute is the input that was submitted for this entry (i.e. a structure with username and publicname attributes). The output attribute is a structure. This structure is always guaranteed to have one attribute status, whose value will be either "success" or "failed". If the assignment failed, the structure will also be an error structure, with code,short,and description attributes. If the assignment succeeded, the structure will contain a msg attribute with a success message.

Remarks

If the token is already assigned to a user - even if they are the same as the target of the assignment request - the request will fail.

Unassign a Token

Overview

This endpoint un-assigns tokens that are currently assigned to users.

Request Type: DELETE
Endpoint Path: /gras-api/v2/mgmt/mappings

Parameters

{
    "users": [
        {...}
    ]
}

Each entry to unassign should be a structure with either of the two following keys (you need not supply both):

AttributeTypeDescription
usernameStringThe username to un-assign from, in user@domain format.
publicnameStringThe public ID of the token to un-assign.

Remember, for each unassignment, you only need to supply either the user or the token!

Return Value

Like the Assign a Token endpoint, this endpoint returns a structure in this format:

{
    "users": [...]
}

Each item in the users list corresponds to one of the input entries. These entries are structures with input and output attributes, with input again holding the input value for this entry. The output value is either an error structure, if the given entry failed to unassign, or a structure in one of two formats.

If the entry unassigned by username, its corresponding output struct will have the following attributes:

AttributeTypeDescription
statusStringFor successful unassignments, holds "success".
usernameStringThe input username.
tokens_unassignedList of stringsA list of all tokens unassigned from the user.

If the entry unassigned by token ID, its output struct will look like this instead:

AttributeTypeDescription
statusStringFor successful unassignments, holds "success".
publicnameStringThe input public ID of the token.
users_unassignedList of stringsA list of all users the token was unassigned from.

Request Token Assignments

Overview

This endpoint returns a list of user-token mappings matching the given criteria.

Request Type: GET
Endpoint Path: /gras-api/v2/mgmt/tokenassignment

Parameters

All parameters are optional. You may supply one, more than one, or none. Supplying no parameters will match all assignments.

ParameterTypeDescription
token_idList of stringsA list of Token IDs to match against.
usernameList of stringsA list of user names to match against. These must be provided in user@domain format.
token_typeList of stringsA list of token types to match against. The following values are accepted: yubikey, oath-totp, oath-hotp, u2f, and m2f. Multiple values may be supplied.
assigned_beforeIntA "latest date" for any assignment. Matches only assignments earlier than this date. Provided as a number of seconds since 00:00:00 on 1 Jan 1970 in the server's timezone.
assigned_afterIntAn "earliest date" for any assignment, in the same format as assigned_before.

Request Authentication Records

Overview

This endpoint returns a log the of authentications against the GreenRADIUS server, filtered according to provided criteria.

Request Type: GET
Endpoint Path: /gras-api/v2/mgmt/gras-authentication-request-records

Parameters

{
    "authentication_result": //List of strings.
    "token_type": //List of strings. 
    "username": //List of strings
    "token_id": //List of strings
    "authentication_agent": //List of strings
    "authentication_endpoint": //List of strings
    "sort_by": //String
    "sort_order": //String
    "from_timestamp": //String. "Earliest date" for authentication requests, in seconds since 
    				//00:00:00 on 1 January 1970 in the server's timezone
    "to_timestamp": //String. "Latest date" for authentication requests, in the same format as above.
}
ParameterPossible Values (more than one may be supplied)
authentication_resultSUCCESS_2FA, SUCCESS_SF,SUCCESS_TEMP,FAILED
token_typeALL,YUBIKEY,OATH,U2F,MOBILE
sort_byAUTHENTICATION_TIME,USERNAME,TOKEN_ID
sort_orderASC,DESC
Updated 2021-07-02
© 2021 Green Rocket Security Inc. All rights reserved.

Validation Protocol

The YubiKey Validation Protocol enables GreenRADIUS to validate YubiKey OTPs through a special endpoint without performing username/password validation nor user-YubiKey assignment validation.

Prerequisites

  • GreenRADIUS 4.4.1.1 or later
  • A valid license which supports OTPOnly functionality

Usage

The endpoint is accessible at https://<IP/hostname of GreenRADIUS>/wsapi/2.0/verify by POST or GET request.

HTTP parameters should be supplied in the usual way as "form-input" style entries, e.g.

https://<IP/hostname of GreenRADIUS>/wsapi/2.0/verify>nonce=12341234123412341234&id=1&otp=grktccrrijbribbcdtveetgbvergnrvcnkngnfljjfcj'

The following parameters are required:

  • id: The Client ID for this requestor.
  • otp: The OTP to validate
  • nonce: A unique identifier for this request. Must be between 16 and 40 characters in length.

The following parameters are optional:

  • timestamp: If 1, session counter information and timestamp will be returned with response.

The response will be returned as a series of key=value pairs, separated by newlines. The otp and nonce will be echoed back, accompanied by time stamp, session counter, and session use if timestamp was set in the request. An HMAC signature will also be returned, as the h parameter. The result will be returned in the status parameter, and takes the following possible values:

  • OK: The OTP is valid.
  • BAD_OTP: The OTP is invalid.
  • REPLAYED_OTP: The OTP has already been used in a previous request.
  • REPLAYED_REQUEST: The OTP/nonce combination has already been used in a previous request.
  • MISSING_PARAMETER: The request is lacking a required parameter.
  • NO_SUCH_CLIENT: A request ID other than 1 was selected.
  • BACKEND_ERROR An internal error has occurred. Please contact Green Rocket Security if you see this message.

Example of a request response:

h=u7EiYbXxElBBKRfkkCNCxf6zj/4=
t=2021-10-13T20:13:02Z0820
otp=grktccrrckjlbejchetblehkefgcnrtgdevvgiikkdfc
nonce=12341234123412345
timestamp=9323959
sessioncounter=2
sessionuse=0
status=OK

Editing Client Parameters

It is possible to edit some client parameters in the web administration console, such as the Client ID. To do this, log into the web admin console and navigate to Global Configuration > Client-based Authentication Policies. Select the client (OTP Only clients will be marked YUBIKEY_OTP_VALIDATION).

Client-based authentication policy configuration

Click "Edit Selected." You will then be able to edit the Client ID, description, and shared HMAC key for the client.

client-based authentication policy configuration - yubikey only

Updated 2021-11-04
© 2021 Green Rocket Security Inc. All rights reserved.

Automatic Certification with Let's Encrypt

It is possible to set up GreenRADIUS to automatically obtain and install certificates from Let's Encrypt. These are the steps to obtain and install a certificate and configure your GreenRADIUS to automatically renew its certificate from Let's Encrypt.

Prerequisites

  • GreenRADIUS v4.3.5.5 or later
  • A valid domain name with the A record pointing at GreenRADIUS
  • GreenRADIUS must be connected to the Internet with the ability to make outgoing connections on port 443 and accept incoming connections from any IP address on port 80. (Note: In order to enable incoming connections on the internal UFW firewall (if enabled), run sudo ufw allow 80 in the GreenRADIUS command line.)

Steps

  1. Log into your GreenRADIUS instance via SSH
  2. sudo su
  3. snap install core
  4. snap refresh core
  5. snap install --classic certbot
  6. ln -s /snap/bin/certbot /usr/bin/certbot
  7. certbot certonly --standalone
  8. Follow the onscreen instructions. After this, your certificate files will be placed in a directory at /etc/letsencrypt/live/<your site name>/. This contents of this folder will be updated as needed by Certbot, so the certificate here should always be fresh.
  9. Download the automatic installation script from this link and unzip it. You should now have a file called install-grva.sh.
  10. Move install-grva.sh to /etc/letsencrypt/renewal-hooks/deploy.
  11. Run chmod +x /etc/letsencrypt/renewal-hooks/deploy/install-grva.sh.
  12. Run certbot renew --force-renewal and verify that no errors occurred.

You should now find that the new certificates have been installed on GreenRADIUS. Certbot will periodically refresh the certificates; there may be a few seconds where GreenRADIUS is unavailable when this occurs (approximately once per month).

Updated 2021-11-01
© 2021 Green Rocket Security Inc. All rights reserved.

Deploying FIDO2 with GreenRADIUS for PHP-powered websites

Prerequisites

  • A web application which supports PHP integration
  • PHP 7.3.27 or later
  • GreenRADIUS v4.4.1.1 or later

Configuration Instructions

  1. Download and unzip the FIDO2 relying party installation package.
  2. The module is divided into two sections. One is written in Javascript and runs on the client's browser; the other is written in PHP and runs server-side. These are stored in the js/ and php/ subdirectories, respectively, of the installation package. Both need to be installed in your web application; the exact location and configuration depends on your specific web server. In this guide, the location of the PHP modules will be referred to as $PHPCLIENT and the location of the Javascript modules as $JSCLIENT.
  3. Configure the $PHPCLIENT/config.php. The folloing should be configured:
    1. server: IP address/hostname of the GreenRADIUS server to authenticate against.
    2. relying-party: A valid domain string that identifies the FIDO2 relying party (e.g. fido2demo.com). The same identifier with have to be configured on the GreenRADIUS FIDO2 server.
    3. client-id: A unique identifier for this particular client. The same ID must be configured in GreenRADIUS and cannot be shared by any other client.
    4. shared-secret: A shared secret key to authenticate the client module with GreenRADIUS. The same secret must also be configured in GreenRADIUS.
  4. In GreenRADIUS, go to Global Configuration > Client-Based Authentication Policies and select Add a New Client.
  5. Populate the new client with the same client ID, shared secret, and relying party identifier as in the $PHPCLIENT/config.php file. Set the client type to FIDO2_Web_API, and configure the other settings as preferred.
  6. You can now begin to develop your application. To help with this, a minimal example site has been provided as part of the installation package in the demosite/ directory. To deploy the demo site, place the $JSCLIENT files into the same directory as the demo site, and place the $PHPCLIENT file so that auth.php is accessible at the /mgmt-api/ path on the server. You may need to make adjustments depending on your particular configuration.
Updated 2021-11-10
© 2021 Green Rocket Security Inc. All rights reserved.