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 > Cert manager, Certificates tab

  • Click fa-plus 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 fa-refresh for the stunnel entry

    • Click fa-check 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 fa-plus Install for the stunnel package entry

    • Click fa-check 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 fa-plus 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 fa-plus 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 fa-plus 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 fa-pencil on the row for the newly created group

  • Click fa-plus 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 fa-wrench 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.