7. MFA Client¶

The MFAClient class can be used to implement simple multi factor authentication (MFA) service clients. The following example shows the outline of a plugin for an imaginary “Acme” MFA that provides its services over HTTP/REST.

#!/usr/bin/env pluginwrapper3

import requests
from safeguard.sessions.plugin import AAPlugin, AAResponse
from safeguard.sessions.plugin.mfa_client import MFAClient

class AcmePlugin(AAPlugin):
    def do_authenticate(self):
        # Glue code to instantiate and execute an MFAClient
        client = AcmeClient.from_config(self.plugin_configuration)
        return client.execute_authenticate(self.username, self.mfa_identity, self.mfa_password)


class AcmeClient(MFAClient):
    def __init__(self, disable_echo, ignore_connection_error, server_url, token):
        super().__init__('ACME plugin', ignore_connection_error)
        self.disable_echo = disable_echo
        self.server_url = server_url
        self.token = token

    @classmethod
    def from_config(cls, plugin_configuration, section='acme')
        # It is good practice to handle the plugin configuration in its own method.
        # This method will return an instance of AcmeClient
        return cls(
            # In case the client needs to ask for further password(s), it should set disable_echo like AAPlugin
            plugin_configuration.getboolean('auth', 'disable_echo', default=False),
            plugin_configuration.getboolean(section, 'ignore_connection_error', default=False),
            plugin_configuration.get(section, 'server_url'),
            plugin_configuration.get(section, 'token'),

        )

    def push_authenticate(self, mfa_identity):
        # Use the requests module to implement the HTTP/REST communication
        # for push notification,
        # Should return True/False depending on the outcome.
        return False

    def otp_authenticate(self, mfa_identity, otp):
        # Use the requests module to implement the HTTP/REST communication
        # for one-time password authentication.
        # Should return True/False depending on the outcome.
        return False

This plugin will support the common AAPlugin configuration options (Common configuration options) as well as an [acme] section:

[acme]
; ignore_connection_error=<yes|no>
; server_url=<server-url>
; token=<$-or-token>

class safeguard.sessions.plugin.mfa_client.MFAClient(branded_name, ignore_connection_error=False)¶

The MFAClient is a base class for simple MFA client implementations.

push_authenticate(mfa_identity)¶

The push_authenticate() should implement handling push notification. It may return True/False or an AAResponse. In case of asking for further password(s), the disable_echo parameter of AAResponse.need_info should come from the “[auth] disable_echo” configuration parameter.

Parameters: mfa_identity (str) – username/identity to authenticate
Returns: whether the push notification was successful or not
Return type: bool or AAResponse

otp_authenticate(mfa_identity, otp)¶

The otp_authenticate() should implement checking one-time password. It may return True/False or an AAResponse. In case of asking for further password(s), the disable_echo parameter of AAResponse.need_info should come from the “[auth] disable_echo” configuration parameter.

Parameters

mfa_identity (str) – username/identity to authenticate
otp (str) – the password to check

Returns

whether the authentication was successful or not

Return type

bool or AAResponse

execute_authenticate(username, mfa_identity, mfa_password=None)¶

The execute_authenticate() should be called from AAPlugin.do_authenticate to execute the authentication. This method will dispatch to push_authenticate() or otp_authenticate() and handle errors as well as create the verdict towards SPS.

New in version 1.6.0

The deny verdicts now contains human readable deny verdicts

Parameters

username (str) – gateway user
mfa_identity (str) – the MFA identity to use
mfa_password (str) – the MFA password to check, or a False value to indicate push notification

Returns

AA plugin verdict

Return type

dict

exception safeguard.sessions.plugin.mfa_client.MFAAuthenticationFailure¶: The MFAAuthenticationFailure exception should be used to propagate server side authentication failure.

exception safeguard.sessions.plugin.mfa_client.MFACommunicationError¶: The MFACommunicationError exception should be used in MFA clients to indicate that there was an error in the communication with the MFA service. For example use this exception if there is a mismatch between client and server protocol version or capabilities.

exception safeguard.sessions.plugin.mfa_client.MFAServiceUnreachable¶: The MFAServiceUnreachable exception should be used in MFA clients to indicate that the MFA service could not be reached due to network issues.

Table Of Contents

Previous topic

Next topic

7. MFA Client¶