Home

Welcome to the Mojo::Gateway documentation!

Mojo::Gateway is a config-file driven edge authentication service for cloud environments. This wiki is a documentation source and will offer some recipes (WIP) for various usages.

Config File Documentation

The default config file gateway.json is a JSON-based text file with embedded perl. See this link for more explanation of this format: JSONConfig Format. Borrowing this format from standard Mojolicious config file formats, allows Mojo::Gateway to allow injection of ENV VAR and other perl expressions to the configuration at app bootstrap. Other than that its just JSON and follows all requirements of JSON formatted data structures.

You can provide your own config file (name it private.json since thats already in the .gitignore) at bootstrap with using the Mojolicious MOJO_CONFIG ENV VAR set to the name of the config file you want to use (e.g MOJO_CONFIG=private.json). That file would could be injected into the Docker container presumably hosting this service or could simply be included at the root level of the project (e.g. 'private.json' file).

Top Level Fields

Field Name	JSON Type	Required?	Default	Remarks
login_page_title	string	no	"Login"	HTML page title of login screen
landing_page	string	no	"/"	Route to redirect to for if a default fallback/landing page is used
max_login_attempts	number	no	undef	If defined, number of consecutive unsuccessful login attempts before account is locked
mfa_secret	string	no	undef	If defined, is the secret for MFA TOTP (mfa_issuer and mfa_key_id must also be defined)
mfa_issuer	string	no	undef	If defined, is the name of the issuer to use for MFA (would appear in apps like Google Authenticator
mfa_key_id	string	no	undef	If defined, is the key id of the TOTP (you can specify something like 'login_key' or something
mfa_force_on_all	boolean	no	false	If true, then marks all accounts, present and future, to be MFA enabled. Existing accounts will be forced into MFA enrollment on next login
enable_logging	boolean	no	undef	If defined and truthy, then all requests/response stats will be logged to database (audit log)
logging_ignore_paths	array	no	undef	If defined, hold string elements of paths we want to NOT log if we have logging enabled (e.g. /assets or /public, etc). Path compares are done in a "starts with" manner so something like /public would exclude anything starting with /public
secret	string or array	yes	--	Mojolicious required string for signing - can be string or array
admin_user	string	yes	--	Email of default admin user to seed app bootstrap with (NOTE: if bootstrapping does not find this account username/email, then it will be created every time on bootstrap. If you don't want to use the account, then let it get created, then go in and disable it. Deleting it will make it get RECREATED on next app invocation.
admin_pass	string	yes	--	password to go along with the default admin account - note: does not get subjected to the password complexity rules
db_type	'pg' or 'sqlite'	no	undef	You're using Postgres or Sqlite. If not defined then app will use an in-memory sqlite database (same as used during unit tests)
db_uri	string	maybe	undef	If you're using Postgres then this is needed - format postgresql://username:password@host:port/db_name , otherwise this field isn't required. For persistent SQLite databases, the file named 'data.db' at the same directory level will be used/created
cookie_name	string	no	'mojolicious'	Name of the session cookie to save as
strip_headers_to_client	array	no	undef	List of strings representing names of headers (case insensitive) to strip on response prior to sending back to client
jwt_secret	string	yes	--	Requires min of one character. This is the string used to sign the JSON Web Tokens (JWTs)
routes	object	yes	--	Routing specs (see below)
password_valid_days	number	yes	--	Number of days a password is valid for until forced to change it
password_complexity	object	yes	--	Password complexity rules. These rules are enforced whenever a user changes their password. These rules are NOT enforced when an admin make/creates a password via the app's admin interface. Object with fields: min_length (required number), alphas (optional numeric field for minimum number of alphabet characters), numbers (optional numeric field for minimum number of numbers), specials (optional numeric field for minimum number of non-alphanumeric chars), spaces (required boolean field to indicate whether whitespace allowed in password)
default_route	object	yes	--	The default routing spec to fall back to if request path does not match any of the routes above
test	boolean	no	undef	NOT FOR PROD USE. Used during unit tests. Forces app to use in-mem sqlite database.
config_override	boolean	no	undef	NOT FOR PROD USE. Used by Mojolicious in unit tests to override default config

Routing Section Fields

Field Name	JSON Type	Required?	Default	Remarks
uri	string	yes	--	Required if field template_name is not defined. This will be the url (with trailing-slash) to proxy to (i.e. http://other-host:8080/)
enable_jwt	boolean	no	false	True if we want to inject a JWT on a request that matches this route before we send to the uri
requires_login	boolean	no	true	Whether requests that match this route require a valid, logged-in user. Omitting this field will imply the route requires a logged-in user
jwt_claims	object	no	undef	Object/Hash of claims (key is the claim name) and value is a string or array of strings that will concatenate. Special strings prefixed with ':' will attempt to retrieve that value from the logged-in user record. Only certain fields are allowed (e.g. password, any secrets, etc wont be allowed and will just not get resolved). Use array format if you want to do something complex like [ 'My ', 'name ', 'is ', ':firstName' ] would resolve to My name is XXXXXX
other_headers	object	no	undef	Object/Hash of other headers to add to the about-to-be-proxied request. Format is header name is the hash key, and the value is the string to which assign to it. There are just static strings, no interpretation etc.
transforms	array	no	undef	Array of Objects/Hashes of shape: [{ path => <string>, action => { search: <regex>, replace: <value> }}]. If the path key is omitted, then the transform action will run for each response who's request matches its route spec and do the appropriate search and replace. Otherwise if the path matches (via regex) the value of the path key, then only then will the search and replace happen.

Cookbook and Recipes