Settings

Explaining the content of settings.py

settings.py is part of .gitignore and hence not synced with GitHub. It is used for local development and testing purposes only. The PROD environment uses secrets fetched by the generic settings in software\configurations\base.py.

settings.py is located in the project folder and is used as the core configuration of a given Automail instance for your local development and testing environment.

General Settings

settings.py should always extend configurations.base, which includes the generic configurations that apply to all Automail instances.

from configurations.base import *

PROJECT_NAME = "automail-lv-cookie" # instance name
COMPANY_NAME = "ABC Inc." # client company name
APPLICATION_NAME = f"Automail DEV {VERSION}" # instance-specific name displayed on the sign-in page
APPLICATION_NAME_SHORT = APPLICATION_NAME # instance-specific short name displayed next to the Lineverge logo on the top left of the site when the left menu is unfolded (maximum 12 characters for optimal display)
DOMAIN = "https://abc.com" # client company website
DESCRIPTION_TEXT = f"This is a testing site of Automail in version {VERSION}..." # notification text displayed on the sign-in page

LOG_FOLDER = r"C:\Lineverge\Staging\staging\Logs" # absolute folder path to store log files (None for local development)
PICKLE_DIR = r"C:\Lineverge\Staging\staging\Pickles" # absolute folder path to store pickles (a pickle is a dataframe stored in a file)
EXPORT_DIR = r"C:\Lineverge\Staging\staging\Exports" # absolute folder path to store files generated through custom backend processes (e.g. export of Costing data into costing.xlsx)
UPLOADS_DIR = r"C:\Lineverge\Staging\staging\Uploads" # absolute folder path for Automail to store files that were uploaded by a users via drag&drop using the Table upload feature
TEMP_DIR = r"C:\Lineverge\Staging\staging\Temp" # absolute folder path for Automail to store temporary files, which are deleted after being served to the user

SECRET_KEY = "ABCABCABCABCABCABCABCABCABCABCABCABC" # salt used for hashing sessions
ALLOWED_HOSTS = ["cookie.lineverge.io", "127.0.0.1"] # domains allowed to run the Automail instance (always put the PROD domain first and then alternative domains, "127.0.0.1" is running the application using the development server)

DEBUG = True # debug flag used for development only (in PROD always set to False for security reasons!)
if DEBUG:
    MEDIA_URL = "/"

if DEBUG is False: # HTTP to HTTPS redirect
    SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
    SECURE_SSL_REDIRECT = True
    SESSION_COOKIE_SECURE = True
    CSRF_COOKIE_SECURE = True

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql', # database driver
        'NAME': 'automail', # database name 
        'USER': 'automail', # database user (always set up a dedicated user for Automail called "automail" for consistency)
        'PASSWORD': 'SECRET PASSWORD', # database user password
        'HOST': 'automail-lv-cookie.ap-east-1.rds.amazonaws.com', # database host ("localhost" for local development)
    },
}

DBBACKUP_STORAGE_OPTIONS = {"location": r"C:\Lineverge\Staging\Backups"} # Backup folder

# Outbound SendGrid
SENDGRID_APIKEY = "SG..." # API key to send emails using the Sendgrid API
SENDGRID_APIKEY_DELETE_BOUNCE = "SG..." # API key to delete bounced emails in Sendgrid (to avoid Sendgrid blocking the submissions)
SUPPORT_EMAIL_ADDRESS = "[e-mail]" # support email address of the client to help supply chain partners
EMAIL_USERNAME = "[e-mail]" # email address to send the Automail emails (if using a client email address then the required domain records need to be set to avoid emails falling into SPAM)
EMAIL_USERNAME_SEND = EMAIL_USERNAME
SEND_TO_BCC = [] # email addresses to included in BCC for all Automail emails (usually of Lineverge team members)

# Autoform
AWS_BUCKET = "autoform-test-uploads" # Autoform test bucket
AWS_REGION = "ap-southeast-1" # Autoform test region
AUTOFORM_TOKEN = "" # Autoform test token
AUTOFORM_DOMAIN = "https://autoform-test.s3.ap-southeast-1.amazonaws.com" # Autoform test domain
CREATECONFIG_ENDPOINT = "https://td5ag5ha50.execute-api.ap-southeast-1.amazonaws.com/dev/createconfig" # Autoform create test endpoint
UPDATECONFIG_ENDPOINT = "https://2npjre9u95.execute-api.ap-southeast-1.amazonaws.com/dev/updateconfig" # Autoform update test endpoint
LOADCONFIG_ENDPOINT = "https://ebsl128mw2.execute-api.ap-southeast-1.amazonaws.com/dev/loadconfig" # Autoform load test endpoint
CHECKCONFIG_ENDPOINT = "https://9ehwwojapd.execute-api.ap-southeast-1.amazonaws.com/dev/checkconfig"  # Autoform bulk config check endpoint

Single Sign-On

Automail has a Single Sign-On (SSO) feature, to allow seamless access to multiple applications and services using a single set of credentials. We use OpenID as our SSO method because it's an open standard that ensures secure user authentication, enabling users to log in using a single digital identity across various websites and applications, reducing the need for multiple passwords, and streamlining the user experience.

An Identity Provider (IdP), is a system that authenticates users and supplies their credentials to other services through a secure connection.

The IdP setup requires to configure [CUSTOM_DOMAIN]/app_authentication/oidc/callback/ (e.g. https://cookie.lineverge.com/app_authentication/oicd/callback/) as callback URI.

To enable SSO, add the following constants to settings.py:

SSO_AUTHENTICATION = True # To enable SSO within the application
AUTOMAIL_USERNAME_LOGIC = "email" # "email", "email_without_domain"
OIDC_RP_CLIENT_ID = "" # Provided by team managing the IdP
OIDC_RP_CLIENT_SECRET = "" # Provided by team managing the IdP
OIDC_OP_AUTHORIZATION_ENDPOINT = None  # (endpoints can be found on IdP - OpenID configuration URL, e.g. "https://ssotesttrial.onelogin.com/oidc/2/auth")
OIDC_OP_TOKEN_ENDPOINT = None  # (endpoints can be found on IdP - OpenID configuration URL, e.g. "https://ssotesttrial.onelogin.com/oidc/2/token")
OIDC_OP_USER_ENDPOINT = None  # (endpoints can be found on IdP - OpenID configuration URL, e.g. "https://ssotesttrial.onelogin.com/oidc/2/me")
OIDC_OP_JWKS_ENDPOINT = None  # (endpoints can be found on IdP - OpenID configuration URL, e.g. "https://contentlab-dev.onelogin.com/oidc/2/certs")
OIDC_RP_SIGN_ALGO = "HS256" # "HS256", "HS512", "RS256", "HS384"
AUTHENTICATION_BACKENDS = ["axes.backends.AxesBackend", "django.contrib.auth.backends.ModelBackend", "polygon.apps.app_authentication.backends.CustomOIDCAuthenticationBackend"]
MIDDLEWARE = [ "django.middleware.security.SecurityMiddleware", "django.contrib.sessions.middleware.SessionMiddleware", "django.middleware.common.CommonMiddleware", "django.middleware.csrf.CsrfViewMiddleware", "django.contrib.auth.middleware.AuthenticationMiddleware", "django.contrib.messages.middleware.MessageMiddleware", "django.middleware.clickjacking.XFrameOptionsMiddleware", "password_policies.middleware.PasswordChangeMiddleware", "axes.middleware.AxesMiddleware", "session_security.middleware.SessionSecurityMiddleware", 'polygon.apps.app_authentication.middlewares.DisableAdminLoginMiddleware', "mozilla_django_oidc.middleware.SessionRefresh"]

The endpoints are visible at: Google IdP: https://accounts.google.com/.well-known/openid-configuration

Microsoft IdP: https://login.microsoftonline.com/{tenant ID}/v2.0/.well-known/openid-configuration

This will replace the default sign-in page with the SSO button that will redirect users to the IdP authentication page. After successful authentication, the IdP will redirect the users to their authenticated Automail accounts.