This article is only applicable to firmware version 12.0 and later. For versions older than 12.0 please reference the documentation page accessible by clicking the "?" symbol next to the OAuth heading on your filter.
OAuth is an HTTP-based authorization protocol which is commonly used to share information between different applications. It serves as the basis for several authentication schemes whereby one application (often a Web site) enables a user to log in, or to delegate access to their profile or organization, by authenticating to another service (usually a different, unrelated Web site such as Google or Facebook). The latter service is referred to as the identity provider.
Cipafilter supports the use of OAuth-based authentication via two third-party identity providers: Google G Suite (Gmail) and Microsoft Azure AD (Office 365).
OAuth authentication support can be divided into two distinct but related functions: a directory back-end and a portal front-end.
OAuth directory back-end
Adding an OAuth service to the Directory Back-Ends table on the Web Filtering page enables the use of that service as a directory back-end. Both supported identity providers offer APIs that function as directories, similar to LDAP implementations like Active Directory. The Cipafilter can use these APIs to determine the existence of a user in the directory, as well as that user's group memberships, just as it would with LDAP.
There are some limitations to OAuth back-ends, however. Unlike LDAP, which allows the filter to test a given user name and password for validity, OAuth does not support direct credential authentication; the identity provider handles this itself. As a result, directory information derived from OAuth-based services can not be used to complete password authentication; only password-less authentication methods — RADIUS, a compatible Cipafilter authentication client, or the OAuth portal front-end (described below) — may be used.
(The Windows and macOS authentication clients can "simulate" a successful log-in via OAuth when the user's domain or work-station user name matches the one returned by the identity provider; the authentication is assumed to be successful based on the fact that the user was able to log in to the work station. The Cipafilter Direct Authenticator Chrome extension uses a Google-specific method to authenticate to the filter using information derived from the account signed into Chrome.)
OAuth back-ends do not work with captive-portal password log-ins, browser proxy prompts, or the Cipafilter Authenticator Chrome extension.
OAuth portal front-end
Checking the Portal box in the OAuth table on the Web Filtering page enables the use of the OAuth sign-in flow on the captive portal. When active, a button appears on the portal, which, when clicked, directs the user to the appropriate identity provider. Once the user has authenticated with the identity provider, they are returned to the portal, which verifies the result of the operation and (if successful) matches the returned user information to a group using the configured directory back-ends.
Example: Central High School has an internal Active Directory server as well as G Suite accounts for all students. A student named Joe Bloggs has an account jbloggs in Active Directory, and an account firstname.lastname@example.org in G Suite. With the Google OAuth portal front-end enabled, Joe can sign in to Google via the captive portal, and the Cipafilter will match the user name from the returned e-mail address to the user name in Active Directory. Upon finding a match, the filter will use the AD group-membership information to place the user into an appropriate group.
This feature can be, and usually is, used in conjunction with the corresponding OAuth directory back-end (described above). By combining the two, organizations can use the identity provider's directory service as a complete substitute for Active Directory and other traditional directories.
Because it requires Web-based interaction from the users themselves, the front-end feature is only beneficial to portal users; it does not affect browser proxy prompts or Cipafilter authentication clients.
A one-time setup is required on the identity-provider side for each domain you would like to use for OAuth authentication on the filter.
Initial setup: Google G Suite
- Using an administrative account for your G Suite domain, log in to the Google API Console at console.developers.google.com.
- Click the Select a project drop-down menu at the top of the API Console page (it may show the name of a previously configured project, if you have one), and click New Project.
- On the next page, you will be prompted for a project name and ID; enter "Cipafilter OAuth" or similar for the name (the ID can be left as the default), then click Create.
- You should be directed to the dashboard for the new project. If not, go back to the projects drop-down at the top and click on the new project name. Then, near the top of the screen, click Enable APIs and services.
- On the API Library page, locate the Admin SDK and People API features, and enable them by clicking their names and then clicking Enable. After enabling one API, use the navigation menu (three lines) in the top left to return to the API Library and enable the next.
- Navigate to APIs & Services and then OAuth consent screen using the menu in the top left.
- On the OAuth consent screen tab, if prompted for the user type, select Public or External, and then click Create.
- Navigate to the Credentials tab via the menu on the left, then click the Create credentials drop-down and select OAuth client ID.
- After a moment, you will be shown a dialogue containing your OAuth client ID and client secret. (These can be viewed later on the Credentials page.) Take note of this information; it will be used for Configuring the filter below.
Initial setup: Microsoft Azure AD
- Using an administrative account for your Azure domain, log in to the Azure portal at portal.azure.com.
- From the navigation menu (three lines) at the top left, click Azure Active Directory.
- In the list on the left, click App registrations.
- In the pane on the right, click New registration.
- On the next screen, enter a memorable Name, such as "Cipafilter OAuth". For Supported account types, select Accounts in any organizational directory (multi-tenant). Leave the Redirect URI blank for now and click Register.
- You should be taken to the Overview pane for the new app registration. Note that the Application (client) ID appears near the top of this pane; you will need this when configuring the filter. Click Authentication on the left.
- In the pane on the right, click Add a platform and select Web. Copy and paste the first of the Redirect URIs listed on the OAuth tab of your filter's Web Filtering page into the Redirect URIs field. (You can only enter one here.) Leave the other fields blank and click Configure.
- Back in the Authentication pane, a Web section should appear. Click Add URI beneath the URI you already added, and add the next URI from the list of Redirect URIs on the Web Filtering page. Repeat this process until you have entered all of the listed URIs. Please ensure that there are no extraneous spaces at the beginning or end of the URIs. When finished, click Save at the top.
- Click API permissions on the left.
- In the pane on the right, click Add a permission. On the Select an API screen, the Microsoft Graph API should appear prominently; click on it. (Please note that the similarly named Azure Active Directory Graph should not be used with Cipafilter.)
- On the next page, select Delegated permissions. A search box should appear; enter the word directory . Select Directory.Read.All from the list of permissions below, then click Add Permissions.
- Click Certificates & secrets on the left.
- In the pane on the right, click New client secret. Enter a memorable Description, check Never under Expires, then click Add.
- The pane on the right should now show the client secret in plain text. You will not be able to view this again, so please take note of it now. (If you ever lose it, simply delete the existing client secret, create a new one, and reconfigure the filter accordingly.) Use the client secret along with the application ID from above for Configuring the filter below.
Configuring the filter
- In another tab or window, access the Cipafilter Web-management interface, then navigate to the Web Filtering page, then to the OAuth tab.
- Click Insert New Rule to add a new entry to the table. Select the appropriate Service and enter your Primary Domain and any Secondary Domains (separated by commas). Paste the client/application ID you got from the identity provider into the Client ID field, and paste the client secret into the Client Secret field. Set Portal and Use UPN as desired (see OAuth).
- Click Save and Apply. (You must always save your changes after editing an entry on this tab before using the Authorize filter access or Test settings functions.)
- In the new tab, you should be directed to the identity provider for the entry you configured. A prompt should appear which explains that the filter wants access to user and group information in your organization's directory. You must authorize this access with an administrative account before OAuth authentication will function.
- Once you have authorized the filter's access, the new tab should close automatically (or it should display a message instructing you to close it yourself).
- It is recommended to confirm that the operation succeeded by clicking the Test settings (check-mark) button on the entry you just added. Normally this check should pass within a few minutes of authorizing the filter's access; if not, please contact tech support for troubleshooting.
- If you would like to use the OAuth service as a directory back-end, add it (taking care to match the Primary Domain) to the Directory Back-Ends table on the Authentication tab. You can also control whether the captive portal allows password log-ins by toggling Allow password log-in from portal when mixed methods are configured under Portal Settings.
Combining Google OAuth with LDAP
For organizations looking to combine traditional LDAP services with Google authentication via the OAuth portal front-end, Google provides a free product for Windows and Linux called Google Cloud Directory Sync (GCDS), which automatically synchronizes directory information from your local LDAP server to Google.
Using this synchronization solution may be more robust than using Google itself as a directory back-end, due to the credential limitations described previously.