Toopher-RADIUS version 1.5

Toopher uses the popular open-source FreeRadius server as the base for its RADIUS solution.

Installation Requirements

Windows Server 2008, Ubuntu Server 12.04 LTS, CentOS/RHEL 6.4 64-bit : Other Windows OS versions are likely to work without issue. For Linux environments, only those listed have been tested.
Internet Connectivity: The Toopher-RADIUS Server must be able to contact the Toopher Web API. Administrators should add appropriate firewall exceptions as necessary.
RADIUS-Compatible Gateway Device: The user-facing device or service that is used with the Toopher-RADIUS server must support the RADIUS Access-Challenge packet type, allowing the Toopher-RADIUS server to request additional data from the user (for instance, when pairing a new mobile device). Almost all commercial VPN products satisfy this requirement, although exceptions do exist (most notably the Microsoft RRAS service)

Installing and Configuring the Toopher RADIUS server

Toopher-RADIUS can be configured to run in either Full-Authentication or Toopher-Only mode.

Full-Authentication: The Toopher-RADIUS server is responsible for authenticating the user's username/password credentials, as well as performing second-factor authentication using the Toopher API. Full-Authentication affords maximum compatibility with various VPN gateway devices, but requires that the Toopher-RADIUS server be configured to access to your organization's LDAP database.
Toopher-Only: Users have already passed username/password authentication before a request is made to the Toopher-RADIUS server. Toopher-Only mode reduces the number of times a user's password must be sent over the network, and may simplify firewall configuration because the Toopher-RADIUS server does not need to contact your organization's LDAP infrastructure. However, not all VPN devices are able to be configured to support the Toopher-RADIUS server in Toopher-ONLY mode.

If your VPN gateway device supports chaining multiple authentication methods, Toopher-Only is usually the prefered configuration for the Toopher-RADIUS server.

If using Full-Authentication mode: Prepare the Active Directory / LDAP Server for Toopher Administration
On the LDAP server, create a group called ToopherUsers
if your LDAP server is not configured to allow anonymous search, you should create a user LDAP account that has search permission for the sAMAccountName attribute (if using Active Directory), or uid (for most other LDAP schemas).

Installing the RADIUS Server

Installing on CentOS / RHEL / Ubuntu

The included install.sh script takes care of the full installation/upgrade process:

cd linux && sudo ./install.sh

Ubuntu installs the FreeRADIUS configuration files to /etc/freeradius instead of /etc/raddb. Where this document references files under /etc/raddb, please edit the corresponding file under /etc/freeradius.

Installing on Windows

The included MSI package will install the Toopher-RADIUS server for windows, along with necessary configuration tools.

RADIUS Configuration - Linux

Add the IP address of your VPN solution to /etc/raddb/clients.conf. This will vary according to your network environment. As an example, to add a VPN client named MY_VPN_BOX accessible at local IP address of 172.16.42.201 with RADIUS secret s3cr3t, add the following four lines to clients.conf:

client MY_VPN_BOX {
     ipaddr = 172.16.42.201
     secret = s3cr3t
}

Before you can run the server, you need to edit /etc/raddb/toopher_radius_config.pm to suit your site.

my $toopher_config =
{
  toopher_api => {
    url   =>  'https://api.toopher.com.com/v1/',
    key   =>  'YOUR TOOPHER API KEY',
    secret=>  'YOUR TOOPHER API SECRET',
    poll_timeout => 30,  # number of seconds before the server gives up on mobile authentication and asks for OTP
    },
  prompts => {
    pairing_challenge => 'Toopher 2-factor authentication is enabled for your account.  Please enter the pairing phrase generated by the Toopher mobile app:',
    otp_challenge => 'Timeout while contacting the Toopher API.  Please enter the OTP generated by the Toopher Mobile App to proceed.',
    self_reset => 'If you have lost your mobile device and need to recover your pairing, enter the word "reset"',
    name_terminal_challenge => 'To enable Toopher Automation, please enter a name for this terminal (e.g. "Home Laptop" or "Office PC")',
    reset_link_set => 'An email has been sent to %email% with a link to reset the Toopher pairing associated with this account',
    }
};

At a minimum, you must change the "key" and "secret" values in the toopher_api section. You can generate new requester credentials at the Toopher Developer Site.

Toopher-Only mode: edit /etc/raddb/toopher_users, and add the following two lines at the bottom of the file (below the # MAKE EDITS BELOW THIS LINE marker. Skip this step if using Full-Authentication mode

DEFAULT Auth-Type := TOOPHER_ONLY
  Fall-Through = Yes

Full-Authentication mode: edit /etc/raddb/modules/ldap to point to your LDAP / Active Directory server. Skip this step if using Toopher-Only mode

conf
  ldap {
    server = "ldap.example.com"
    port = 389
    identity = "cn=Radius Admin,cn=users,DC=example,DC=com"
    password = p@ssw0rd
    basedn = "cn=users,DC=example,DC=toopher,DC=com"
    filter = "(|(uid=%{%{Stripped-User-Name}:-%{User-Name}})(sAMAccountName=%{%{Stripped-User-Name}:-%{User-Name}}))"
    groupname_attribute = cn
    groupmembership_filter = "(|(&(objectClass=GroupOfNames)(member=%{control:Ldap-UserDn}))(&(objectClass=GroupOfUniqueNames)(uniquemember=%{control:Ldap-UserDn}))(&(objectClass=group)(member=%{control:Ldap-UserDn})))"

    # LOTS OF OTHER SETTINGS
}

Most users will only need to edit the server, identity, password, and basedn settings. identity and password correspond to an LDAP account that is allowed search/read access to User objects. If your LDAP server permits anonymous searches, you can comment out these two lines.

The default filters should work for Active Directory, as well as any LDAP server using the RFC 2798 (inetOrgPerson) schema.

Additionally, you may customize the prompt displayed to users when they initially pair their device with Toopher. The maximum length of this prompt is 253 characters due to technical limitations of the RADIUS specification.

RADIUS Configuration - Windows

Windows Administrators can configure the most commonly-used parameters through the Start menu (Toopher -> Toopher-RADIUS Server -> Configuration)

Toopher API Settings:

TOOPHER_API_KEY, TOOPHER_API_SECRET : These credentials are used to securely identify your server to the Toopher Web API. New credentials can be generated by creating an account at [https://dev.toopher.com]
TOOPHER_POLL_TIMEOUT : Maximum amount of time that Toopher will attempt to authenticate the user through the Toopher smartphone app before failing over to OTP validation.
TOOPHER_API_URL : This should stay at the default setting of https://api.toopher.com/v1/.

RADIUS Prompt Text:

PROMPT_PAIRING_CHALLENGE : Text displayed to the user when they first pair a mobile device with their account.
PROMPT_OTP_CHALLENGE : Text displayed to the user when they need to validate with a One-Time Password (for instance, if their mobile device does not have internet access)

Full-Authentication mode settings - skip these items (accept the defaults in the configuration script) if using Toopher-Only mode.

LDAP settings you will need to edit:

LDAP_BASEDN : Base DN to use for username searches
LDAP_HOST : Hostname or IP Address of LDAP or ActiveDirectory server
LDAP_IDENTITY : DN of user to use when connecting to LDAP server to perform user searches.
LDAP_PASSWORD : The password corresponding to the LDAP_IDENTITY user. this password will be stored in plaintext on the RADIUS server

LDAP Settings you probably don't need to edit: The following LDAP settings only need to be edited if your organization uses a non-standard LDAP schema. The default values should work for ActiveDirectory and inetOrgPerson schema, which account for the vast majority of LDAP user databases. If your organization needs help integrating Toopher-RADIUS with a different LDAP schema, please contact support@toopher.com for assistance.

LDAP_GROUP_MEMBERSHIP_FILTER
LDAP_SEARCH_FILTER

Toopher-Only mode: edit C:\Program Files (x86)\Toopher\Toopher FreeRADIUS Server\etc\raddb\toopher_users, and add the following two lines at the bottom of the file (below the # MAKE EDITS BELOW THIS LINE marker. Skip this step if using Full-Authentication mode

DEFAULT Auth-Type := TOOPHER_ONLY
  Fall-Through = Yes

Start the RADIUS server

Ubuntu

sudo service freeradius start

CentOS / RHEL

sudo service radiusd start

Windows

net start toopher-freeradius

Configure your RADIUS-Compatible Gateway Device

Follow vendor instructions for your RADIUS-Compatible VPN (or other gateway device) to connect it to the Toopher-RADIUS server. In addition to entering the IP address and shared secret for the Toopher-RADIUS server, the RADIUS timeout will typically need to be increased well above the default. This timeout should be set slightly higher than the poll_timeout setting configured in toopher_radius_config.pm, above. While the Toopher-RADIUS server will authenticate most requests within a few seconds, requests which require the user to respond to a prompt on their device will take considerably longer.

If you have configured your Toopher-RADIUS server to run in Toopher-Only mode, you must additionally configure your VPN device to perform primary username/password authentication. Exact instructions will vary for different VPN vendors, but the goal is to create a custom Authentication Chain, where the VPN gateway only sends a request to the Toopher-RADIUS server after the username/password combination is determined valid. If capabilities allow, you can also configure the VPN to check that the user is a member of the ToopherUsers group before sending the request to Toopher-RADIUS.

Add Toopher Protection to Individual Users

Toopher is enabled/disabled for an individual user by adding or removing that user from the ToopherUsers LDAP group. Users who are members of ToopherUsers will be subject to an additional Toopher Authentication step before being allowed access via RADIUS.

Resetting a User's Pairing

Resetting a pairing is occasionally necessary, for instance if a user gets a new mobile device and wants to stop authenticating with their old device.

Self-Reset Methods

The easiest way for users to reset their pairing is by deleting the existing pairing from their mobile device. In the Toopher Mobile App, select the pairing on the main screen, then press "Remove Pairing". The user will be prompted to re-pair with a new mobile device the next time they authenticate with the Toopher-RADIUS server.

Of course, if a user needs to reset their pairing, it likely means they do not have access to their mobile device. In this case, users can reset their pairing by waiting for the Toopher OTP prompt, then typing the word "reset" instead of the One-Time Password. The Toopher API will then send a reset link to the user's email address (defined in LDAP).

Administrative Reset

In some cases, a user may require administrator assistance to recover a lost pairing. This most commonly happens if the user loses their mobile device, or uninstalls the Toopher app without first deleting their pairing. There are two options for restoring access to the user:

Remove the user from the ToopherUsers LDAP group - This will preserve the Pairing informaion in the Toopher API server, while allowing the user to bypass Toopher authentication to log in. This method can be effectively undone by adding the user back to the ToopherUsers group.
Reset the user's pairing - Administrators can reset a user's pairing information by running perl /etc/freeradius/toopher_radius.pl reset-pairing [username] on the Toopher-RADIUS server. This command will remove that user's pairing information from the Toopher API, and they will be prompted to re-pair the next time they authenticate. Windows administrators can access this tool through the Start menu (Toopher -> Toopher-RADIUS Server -> Reset User Pairing)

Troubleshooting

SELinux Issues

Symptom: RADIUS returns error messages like Unknown error while authenticating: 500 Can't connect to toopher-api.appspot.com:443 when run as a service, but not when run in debug mode.
Possible Cause: The SELinux default radius module settings does not permit the server to access the Toopher API to complete authentication
Fix: Create a toopher_radius policy module to allow the blocked connection attempts:

grep radiusd /var/log/audit/audit.log | audit2allow -M toopher_radius semodule -i toopher_radius.pp

Support Information

Please do not hesitate to contact support@toopher.com with any questions or concerns.

Changelog

v1.5

Add support and documentation for Toopher-Only operational mode

v1.4.2

Rebuild .deb packages with updated Ubuntu dependencies

v1.4.1

Standardize use of "" characters in configuration files

v1.4

Add support for self-service pairing reset

v1.3

Add support for Feature Phone (SMS-based) pairings

v1.2.1

Add CentOS/RHEL installer

v1.2

Add support for naming user terminals and enabling automation

v1.1

Add Windows Installer

v1.0

Remove local storage requirements
Support LDAP/ActiveDirectory integration without requiring schema changes

Name		Name	Last commit message	Last commit date
Latest commit History 147 Commits
ad		ad
cygwin		cygwin
freeradius/etc/raddb		freeradius/etc/raddb
linux		linux
README-dev.md		README-dev.md
README.html		README.html
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Toopher-RADIUS version 1.5

Installation Requirements

Installing and Configuring the Toopher RADIUS server

Installing the RADIUS Server

Installing on CentOS / RHEL / Ubuntu

Installing on Windows

RADIUS Configuration - Linux

RADIUS Configuration - Windows

Start the RADIUS server

Ubuntu

CentOS / RHEL

Windows

Configure your RADIUS-Compatible Gateway Device

Add Toopher Protection to Individual Users

Resetting a User's Pairing

Self-Reset Methods

Administrative Reset

Troubleshooting

SELinux Issues

Support Information

Changelog

About

Uh oh!

Releases 2

Packages

Languages

toopher/toopher-radius

Folders and files

Latest commit

History

Repository files navigation

Toopher-RADIUS version 1.5

Installation Requirements

Installing and Configuring the Toopher RADIUS server

Installing the RADIUS Server

Installing on CentOS / RHEL / Ubuntu

Installing on Windows

RADIUS Configuration - Linux

RADIUS Configuration - Windows

Start the RADIUS server

Ubuntu

CentOS / RHEL

Windows

Configure your RADIUS-Compatible Gateway Device

Add Toopher Protection to Individual Users

Resetting a User's Pairing

Self-Reset Methods

Administrative Reset

Troubleshooting

SELinux Issues

Support Information

Changelog

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages