Authentication in OPNsense consists of three basic concepts, which are available throughout the entire system:
- These implement the method to use, for example Radius, Ldap, local authentication, etc
- A connection uses an authenticator and defines the properties needed, for example our Radius server available at our domain using specfic settings.
- Some services require or support authentication, such as the webinterface, OpenVPN, etc. These may allow one or more connectors.
Authenticators & Connections¶
Services within OPNsense can use different authentication methods, for which connections can be configured in
\OPNSense\Auth\IAuthConnector, which comes with some simple to use handles.
If a class in
IAuthConnector it is considered a viable authentication option
for the authenticator factory named
The factory provides a layer of abstraction around the different authentication concepts, for example a server defined in
This connects the authenticator to the configured servers and the response object is ready to handle authentication requests.
We strive to use
PAM to define our services, in which case we adopt to existing standards.
OPNsense comes with a PAM module, which connects our service definitions with the services defined using PAM.
A simple example of a service named opnsense-login is defined as follows in a file with the name
auth sufficient pam_opnsense.so account sufficient pam_opnsense.so
To test authentication, you can use opnsense-login for any configured service. The following example tries to authenticate user root for service opnsense-login (the default when no options are specified).
man opnsense-login for a list of available command line options.
opnsense-login inherits from the standard system authentication used for console and web GUI login unless otherwise specified.
Internally PAM calls
/usr/local/libexec/opnsense-pam which acts as a stepping stone into the
authentication sequence served by
opnsense-auth is written
in php and needs elevated privileges for this task, the stepping stone makes sure it has them granted before executing
using the setuid bit.
The authentication script
opnsense_auth utilizes our factory class to perform the actual authentication using
the connections defined in the service.
For this purpose we expose a services namespace in
\OPNSense\Auth\Services where the required options can be read
from the OPNsense configuration.
For every service defined in PAM, the factory method
getService() expects a class implementing
aliases() static method service classes can support multiple PAM services at once if needed
(e.g. System can also be used for ssh).
Not every service uses PAM already, in that case it is defined as a script handling the authentication.
IService is quite easy to read and should be self explanatory.