authnzerver.actions.email module

This contains functions to drive email-related auth actions.

authnzerver.actions.email.send_email(sender: str, subject: str, text: str, recipients: Sequence[str], server: str, user: str, password: str, pii_salt: str, bcc: bool = False, port: int = 587) → bool[source]

This is a utility function to send email.

Parameters:
  • sender (str) –

    The name and email address of the entity sending the email in the following form:

    "Sender Name <senderemail@example.com>"
  • subject (str) – The subject of the email.
  • text (str) – The text of the email.
  • recipients (list of str) –

    A list of the email addresses to send the email to. Use either of the formats below for each email address:

    "Recipient Name <recipient@example.com>"
"recipient@example.com"
  • server (str) – The address of the email server to use.
  • user (str) – The username to use when logging into the email server via SMTP.
  • password (str) – The password to use when logging into the email server via SMTP.
  • pii_salt (str) – The PII salt value passed in from a wrapping function. Used to censor personally identifying information in the logs emitted from this function.
  • bcc (bool or list of str) – If True, will set the To: field in the email itself to “undisclosed-recipients” and send the email to all recipients such that none of them know who the message was sent to (effectively BCCs all the recipients). If this is set to a list of email addresses in RFC822 format as strings, will only BCC those email addresses. If this is set to False, the To: field in the email itself will contain the addresses of all recipients.
  • port (int) – The SMTP port to use when logging into the email server via SMTP.
Returns:

sent_ok – Returns True if email sending succeeded. False otherwise.
Return type:

bool
authnzerver.actions.email.send_forgotpass_verification_email(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, config: types.SimpleNamespace = None) → dict[source]

This actually sends the forgot password email.

Parameters:
  • payload (dict) –

    Keys expected in this dict from a client are:

    • email_address: str, the email address to send the email to
    • session_token: str, session token of the user being sent the email
    • server_name: str, the name of the frontend server
    • server_baseurl: str, the base URL of the frontend server
    • password_forgot_url: str, the URL fragment of the frontend forgot-password process initiation endpoint
    • verification_token: str, a verification token generated by frontend
    • verification_expiry: int, number of seconds after which the token expires

    In addition, the following items must be provided by a wrapper function to set up the email server.

    • emailuser
    • emailpass
    • emailserver
    • emailport
    • emailsender

    These can be provided as part of the payload as dict keys or as attributes in the SimpleNamespace object passed in the config kwarg. The config object will be checked first, and the payload items will override it.

    Finally, the payload must also include the following keys (usually added in by a wrapping function):

    • reqid: int or str
    • pii_salt: str
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

Returns a dict containing the user_id, email_address, and the emailforgotpass_sent_datetime value if email was sent successfully.
Return type:

dict
authnzerver.actions.email.send_signup_verification_email(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, config: types.SimpleNamespace = None) → dict[source]

Sends an account verification email.

Parameters:
  • payload (dict) –

    Keys expected in this dict from a client are:

    • email_address: str, the email address to send the email to
    • session_token: str, session token of the user being sent the email
    • created_info: dict, the dict returned by users.auth_create_user()
    • server_name: str, the name of the frontend server
    • server_baseurl: str, the base URL of the frontend server
    • account_verify_url: str, the URL fragment of the frontend verification endpoint
    • verification_token: str, a verification token generated by frontend
    • verification_expiry: int, number of seconds after which the token expires

    In addition, the following optional items must be provided by a wrapper function to set up the email server.

    • emailuser
    • emailpass
    • emailserver
    • emailport
    • emailsender

    These can be provided as part of the payload as dict keys or as attributes in the SimpleNamespace object passed in the config kwarg. The config object will be checked first, and the payload items will override it.

    Finally, the payload must also include the following keys (usually added in by a wrapping function):

    • reqid: int or str
    • pii_salt: str
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

Returns a dict containing the user_id, email_address, and the emailverify_sent_datetime value if email was sent successfully.
Return type:

dict
authnzerver.actions.email.set_user_email_sent(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, config: types.SimpleNamespace = None) → dict[source]

Sets the verify/forgot email sent flag & time for the newly created user.

This is useful when some other way of emailing the user to verify their sign up or their password forgot request is used, external to authnzerver. Use this function to let the authnzerver know that an email has been sent so it knows the correct move if someone tries to sign up for an account with the same email address later.

Parameters:
  • payload (dict) –

    This is a dict with the following key:

    • email, str
    • email_type, str: one of “signup”, “forgotpass”

    Finally, the payload must also include the following keys (usually added in by a wrapping function):

    • reqid: int or str
    • pii_salt: str
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

Returns a dict containing the email address and email*_sent_datetime values if the sent-email notification was successfully set.
Return type:

dict
authnzerver.actions.email.set_user_emailaddr_verified(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, config: types.SimpleNamespace = None) → dict[source]

Sets the verification status of the email address of the user.

This is called by the frontend after it verifies that the token challenge to verify the user’s email succeeded and has not yet expired. This will set the user_role to ‘authenticated’ (or the previous user role before locking) and the is_active column to True.

Parameters:
  • payload (dict) –

    This is a dict with the following key:

    • email

    Finally, the payload must also include the following keys (usually added in by a wrapping function):

    • reqid: int or str
    • pii_salt: str
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

Returns a dict containing the user_id, is_active, and user_role values if verification status is successfully set.
Return type:

dict