diff --git a/source/development/components.rst b/source/development/components.rst index b3fb86ed..370cee5f 100644 --- a/source/development/components.rst +++ b/source/development/components.rst @@ -15,3 +15,4 @@ tasks, this page indexes those components which aren't directly related to the components/menusystem components/acl + components/authentication diff --git a/source/development/components/authentication.rst b/source/development/components/authentication.rst new file mode 100644 index 00000000..cc4d13ff --- /dev/null +++ b/source/development/components/authentication.rst @@ -0,0 +1,83 @@ +=================== +Authentication +=================== + +.. sidebar:: Access Control List + + .. image:: images/acl-finger-print.jpg + +-------- +Concepts +-------- + +Authentication in OPNsense consists of three basic concepts, which are available throughout the entire system: + +* Authenticators + + - These implement the method to use, for example Radius, Ldap, local authentication, etc + +* Connections + + - A connection uses an authenticator and defines the properties needed, for example our Radius server available at our domain using specfic settings. + +* Services + + - 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 **System-->Access-->Servers** +(e.g. the method can be **radius** which is offered through a server at a location). +All of these methods use the same api defined in :code:`\OPNSense\Auth\IAuthConnector`, which comes with some simple to use handles. + +If a class in :code:`\OPNSense\Auth` implements :code:`IAuthConnector` it is considered a viable authentication option +for the authenticator factory named :code:`AuthenticationFactory`. + +The factory provides a layer of abstraction around the different authentication concepts, for example a server defined in +**System-->Access-->Servers** can be requested using a simple :code:`(new AuthenticationFactory())->get('name');` +This connects the authenticator to the configured servers and the response object is ready to handle authentication requests. + + +----------------------------- +Services +----------------------------- + +We strive to use :code:`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-auth-test** is defined as follows in a file with the name :code:`/etc/pam.d/opnsense-auth-test` + +.. code-block:: sh + + auth sufficient pam_opnsense.so + account sufficient pam_opnsense.so + +To test authentication, you can use opnsense-auth-test for any configured service. The following example +tries to authenticate user *root* for service *opnsense-auth-test*. + +.. code-block:: sh + + /usr/local/sbin/opnsense-auth-test -s opnsense-auth-test -u root + +.. Note:: + + **opnsense-auth-test** inherits from the standard system authentication used for console and webgui login. + + +Internally pam calls :code:`/usr/local/sbin/opnsense-auth` which then uses our factory class to perform authentication using +the connections defined in the service. + +For this purpose we expose a *services* namespace in :code:`\OPNSense\Auth\Services` where the required options can be read +from the OPNsense configuration. + +For every service defined in pam, the factory method :code:`getService()` expects a class implementing :code:`OPNsense\Auth\IService` + +.. Note:: + + Not every service uses pam already, in that case it is defined as a script handling the authentication. Conceptually + it delivers the same functionally, but has some downsides in terms of required rights for the script. + +The interface :code:`IService` is quite easy to read and should be self explanatory.