Table Of Contents

Previous topic

6.2. Plugin development

Next topic

6.4. Connection information

6.3. Plugin response

class safeguard.sessions.plugin.plugin_response.DenyReasons

New in version 1.6.0

The DenyReasons holds the human readable reasons shown to the end-user. each message is a property on the class.

#!/usr/bin/env pluginwrapper3

from safeguard.sessions.plugin import AAResponse, DenyReasons

class Plugin:
    def authenticate(self, gateway_user):
        try:
            response = call_external_api()
            if response.success:
                return AAResponse.accept()
            else:
                return AAResponse.deny(deny_reason=DenyReasons().authentication_failure)
        except HTTPError:
                return AAResponse.deny(deny_reason=DenyReasons().communication_error)
        except TimeOutError:
                return AAResponse.deny(deny_reason=DenyReasons().backend_service_error)
authentication_failure

Message indicates an authentication failure Used in MFAClient

Return type

str

communication_error

Message indicates communation error while using 3rd party services Used in MFAClient

Return type

str

backend_service_error

Message indicates error in 3rd party service. Usually server or http errors. Used in MFAClient

Return type

str

class safeguard.sessions.plugin.plugin_response.AAResponse

The AAResponse class represents an AA plugin response and provides methods for creating and modifying such responses.

#!/usr/bin/env pluginwrapper3

from safeguard.sessions.plugin import AAResponse

class Plugin:
    def authenticate(self, gateway_user):
        if is_on_whitelist(gateway_user):
            return AAResponse.accept()
        elif is_on_blacklist(gateway_user):
            return AAResponse.deny(deny_reason="User is black listed")
        else:
            return AAResponse.need_info("Who are you?", 'username')
classmethod accept(reason=None)

Create a new ACCEPT response.

Parameters

reason (str) – will be placed in the metadata as {"reason": reason}

Return type

AAResponse

classmethod deny(reason=None, deny_reason=None)

Create a new DENY response.

Parameters

reason (str) – will be placed in the metadata as {"reason": reason}

New in version 1.6.0

Parameters

deny_reason (str) – will be shown to the end-user

Return type

AAResponse

classmethod need_info(question, key, disable_echo=False)

Create a new NEEDINFO response.

Parameters
  • question (str) – question (or prompt) to display for the user

  • key (str) – identifier key for the response (this will key the response in key_value_pairs parameter)

  • disable_echo (bool) – turn echo off for the user input (useful for e.g. password input); default: False

Return type

AAResponse

with_additional_metadata(additional_metadata)

Set the additional metadata field in the response. Overwrites previous reason given in accept(), deny().

Parameters

additional_metadata – this value will be stored a JSON in the Additional metadata column of the meta database.

Return type

AAResponse

Extend the response with a cookie.

Parameters

cookie (dict) – this value will be passed to the next call of the plugin in the cookie parameter

Return type

AAResponse

with_gateway_user(gateway_user, gateway_groups=())

Extend the response with a gateway username and its groups.

Parameters
  • gateway_user (str) – this value will override the current gateway user

  • gateway_groups (seq) – these will override the current gateway user’s groups; default: empty

Return type

AAResponse

Extend the response with a session cookie.

Parameters

session_cookie (dict) – this value will be passed to other plugins’ (e.g. credstore) calls in their session_cookie parameter

Return type

AAResponse

with_reason(reason)

New in version 1.6.0

Extend the response with a human readable reason. This message is shown to the end-user if the plugin denies the connection

Parameters

str (reason) – the message shown to the end-user

Return type

AAResponse