Authenticating Users with Google Cloud Identity¶

Google Cloud Identity LDAP service can be used to authenticate users on pfSense® software installations.

The method varies depending on the version of pfSense software installed on the firewall. This is due to the fact that Google Cloud Identity requires a client certificate to make a secure LDAP connection.

Firewalls running pfSense Plus software can use a client certificate directly on LDAP authentication sources.
Firewalls running pfSense CE software or older unsupported versions require the stunnel package to make a secure LDAP connection.

Configuring a firewall running pfSense software to use G Suite LDAP authentication requires a number of steps, all of which are covered in this document.

Configure the LDAP Application on the G Suite admin portal¶

Follow the instructions from Google for configuring and enabling the G Suite LDAP application.

Warning

Follow these directions exactly. No special provisions are required for pfSense, but please note that the LDAP application credentials (username and password) are required.

Download the certificate, key, username and password¶

Download the certificate, key, username and password from G Suite to a local directory on a workstation.

Import the certificate and key¶

From the web interface of a firewall running pfSense:

Navigate to System > Certificates, Certificates tab
Click Add/Sign to display the certificate import interface
Configure the entry as follows:

Method:

Import an existing certificate

Descriptive name:

G Suite LDAP

Certificate data:

Copy and paste the contents of the downloaded certificate

Private Key data:

Copy and paste the contents of the downloaded key
Click Save

The certificate is now available for use by the firewall.

The next step depends on the version of pfSense software installed on the firewall.

For pfSense CE software the stunnel package is necessary to make a secure LDAP connection. For these environments, proceed to Install the stunnel package (pfSense CE software).

For users of pfSense Plus software, LDAP authentication sources can use a client certificate directly. Skip ahead to Configure LDAP authentication on pfSense software.

Install the stunnel package (pfSense CE software)¶

From the web interface on pfSense:

Navigate to System > Package manager, Installed Packages tab
Check the list for stunnel and if it is listed as installed
If the package is installed and up-to-date, with a version of 5.37 or later, no action is required
If the package is installed but out of date
- Update the package by clicking for the stunnel entry
- Click Confirm to confirm the package update
If stunnel is not installed
- Navigate to the Available packages tab
- Locate the stunnel package in the list, or use the search bar
- Click Install for the stunnel package entry
- Click Confirm to confirm the package installation

Configure the stunnel package (CE or 2.4.4-RELEASE)¶

From the web interface on pfSense:

Navigate to Services > STunnel
Click Add to create a new profile
Configure the profile as follows:

Description:

Text describing this connection, such as G Suite

Client Mode:

Check

Listen on IP:

127.0.0.1

Listen on port:

1636

Certificate:

The entry imported previously, in this case G Suite LDAP

Redirects to IP:

ldap.google.com

Redirects to port:

636
Click Save

Configure LDAP authentication on pfSense software¶

From the web interface on pfSense:

Select System > User manager, Authentication servers tab
Click Add to create a new entry
Enter a Descriptive name for this LDAP server, such as G Suite
Configure the basic settings for the server as follows:

Type:

LDAP

Protocol version:

3

Server timeout:

25

Search scope:

Entire tree

The remaining settings depend on which version of pfSense software is installed:

For pfSense Plus:

Hostname or IP address:: ldap.google.com
Port value:: 636
Transport:: SSL - Encrypted
Peer Certificate Authority:: Global Root CA List
Client Certificate:: The entry imported previously, in this case G Suite LDAP

For pfSense CE or when using stunnel:

Hostname or IP address:: 127.0.0.1
Port value:: 1636
Transport:: TCP-Standard

The next few settings are UNIQUE TO THE DOMAIN. For this example, assume that is example.com.

Warning

Substitute the actual domain when entering these values!

Base DN:: The domain name in DN format, for example``dc=example,dc=com``
Authentication containers:: Base DN prepended by the Users organizational unit, for example: ou=Users,dc=example,dc=com
Bind anonymous:: Unchecked to show the Bind Credentials fields
Bind credentials:: The G Suite LDAP username and password that were created with the certificate and key

The remaining attributes are not specific to the domain, or are defaults

User naming attribute:: uid
Group naming attribute:: cn
Group member attribute:: memberOf

Create a Group¶

Using a remote authentication server to manage administrative logins to services on pfSense software requires a matching group to be present on both the authentication source server and on the firewall. The existing admins group could be used, but since the name is so general it may conflict with other desired permissions in G Suite.

This example uses a new group called fwadmins.

First, create the fwadmins group in G Suite and assign users to the group. The exact details will vary based on the domain and its organization.

Next, create a group on the firewall running pfSense software. This does not require local users, only a group entry. The group entry must have appropriate permissions.

To create the group on pfSense:

Navigate to System > User Manager, Groups tab
Click Add to make a new group
Configure the group as follows:

Group name:

Name of the group, in this example: fwadmins

Scope:

Remote

Description:

Remote Firewall Administrators
Click Save

Now the group needs privileges:

Click on the row for the newly created group
Click Add in the Assigned Privileges section
Select the desired permissions for the group, for example: WebCfg - All pages

Warning

Do not select every item in this list! Doing so will also select the User - Config: Deny Config Write privilege which will prevent users in this group from making changes to the firewall configuration.
Click Save to store the privileges

Test G Suite Authentication¶

With the complete configuration described above, it is now possible to authenticate against Google G Suite LDAP. First, test the authentication to ensure it is working properly.

Navigate to Diagnostics > Authentication
Set the Authentication server to the name used for the LDAP Server entry, such as G Suite
Enter a known username and password on the domain that G Suite controls

Note

By default only the username part of the login is checked against the configured LDAP base DN. If a username is submitted with a domain part, for example user@example.com, the @example.com part is ignored.
Click Test

The user should show as authenticating successfully, and if the user entered is a member of the fwadmins group in G Suite, that should also be reflected in the test output.

If the test succeeds, the service is ready for use. pfSense software can use it as an authentication source for the GUI, for VPNs, or anywhere the user manager authentication servers work.

If the test fails, check the main system log for error messages from LDAP. Start from the beginning of this document and compare all settings between this document, G Suite, and pfSense software. Most common problems are with parameters being input incorrectly, such as selecting the wrong certificate, using an incorrect LDAP attribute name, or not using correct bind credentials.

Use G Suite for Administrative Logins¶

If all is well and the user authenticated as expected:

Navigate to System > User manager, Settings
Set the Authentication server to G Suite
Click Save

After saving, firewall users will be authenticated against Google Cloud Identity.

Note

pfSense software automatically falls back to local authentication if it cannot authenticate using the chosen LDAP server.