Reference

Info

The entrypoint path to the Access guard service is /auth. This is where a forwarder should send a request to check if access should be granted or not.

Prerequisites

An SMTP server that Access guard can configure its SMTP client to send verification emails to.

Command line arguments

$ docker run --rm ghcr.io/flaeppe/access-guard:latest --help
usage: access-guard [-h] (-s SECRET | -sf PATH_TO_FILE) -a AUTH_HOST -t
                    TRUSTED_HOST [TRUSTED_HOST ...] -c COOKIE_DOMAIN [-V] [-d]
                    [--host HOST] [--port PORT]
                    [--log-formatter {json,console}] --email-host EMAIL_HOST
                    --email-port EMAIL_PORT --from-email FROM_EMAIL
                    [--email-username EMAIL_USERNAME]
                    [--email-password EMAIL_PASSWORD | --email-password-file PATH_TO_FILE]
                    [--email-use-tls | --email-start-tls]
                    [--email-no-validate-certs]
                    [--email-client-cert EMAIL_CLIENT_CERT]
                    [--email-client-key EMAIL_CLIENT_KEY]
                    [--email-subject EMAIL_SUBJECT] [--cookie-secure]
                    [--auth-cookie-name AUTH_COOKIE_NAME]
                    [--verified-cookie-name VERIFIED_COOKIE_NAME]
                    [--auth-cookie-max-age AUTH_COOKIE_MAX_AGE]
                    [--auth-signature-max-age AUTH_SIGNATURE_MAX_AGE]
                    [--verify-signature-max-age VERIFY_SIGNATURE_MAX_AGE]
                    EMAIL_PATTERN [EMAIL_PATTERN ...]

...

positional arguments:
  EMAIL_PATTERN         Email addresses to match, each compiled to a regex

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -d, --debug
  --host HOST           Server host. [default: 0.0.0.0]
  --port PORT           Server port. [default: 8585]
  --log-formatter {json,console}
                        Log output format [default: json]

Required arguments:
  -s SECRET, --secret SECRET
                        Secret key
  -sf PATH_TO_FILE, --secret-file PATH_TO_FILE
                        Secret key file
  -a AUTH_HOST, --auth-host AUTH_HOST
                        The entrypoint url for access guard, with protocol and
                        path
  -t TRUSTED_HOST [TRUSTED_HOST ...], --trusted-hosts TRUSTED_HOST [TRUSTED_HOST ...]
                        Hosts/domain names that access guard should serve.
                        Matched against a request's Host header. Wildcard
                        domains such as '*.example.com' are supported for
                        matching subdomains. To allow any hostname use: *
  -c COOKIE_DOMAIN, --cookie-domain COOKIE_DOMAIN
                        The domain to use for cookies. Ensure this value
                        covers domain set for AUTH_HOST

Required email arguments:
  SMTP/Email specific configuration

  --email-host EMAIL_HOST
                        The host to use for sending emails
  --email-port EMAIL_PORT
                        Port to use for the SMTP server defined in --email-
                        host
  --from-email FROM_EMAIL
                        What will become the sender's address in sent emails

Optional email arguments:
  SMTP/Email specific configuration

  --email-username EMAIL_USERNAME
                        Username to login with on configured SMTP server
                        [default: unset]
  --email-password EMAIL_PASSWORD
                        Password to login with on configured SMTP server
                        [default: unset]
  --email-password-file PATH_TO_FILE
                        File containing password to login with on configured
                        SMTP server [default: unset]
  --email-use-tls       Make the _initial_ connection to the SMTP server over
                        TLS/SSL [default: false]
  --email-start-tls     Make the initial connection to the SMTP server over
                        plaintext, and then upgrade the connection to TLS/SSL
                        [default: false]
  --email-no-validate-certs
                        Disable validating server certificates for SMTP
                        [default: false]
  --email-client-cert EMAIL_CLIENT_CERT
                        Path to client side certificate, for TLS verification
                        [default: unset]
  --email-client-key EMAIL_CLIENT_KEY
                        Path to client side key, for TLS verification
                        [default: unset]
  --email-subject EMAIL_SUBJECT
                        Subject of the email sent for verification [default:
                        Access guard verification]

Optional cookie arguments:
  Configuration for cookies

  --cookie-secure       Whether to only use secure cookies. When passed,
                        cookies will be marked as 'secure' [default: false]
  --auth-cookie-name AUTH_COOKIE_NAME
                        Name for cookie used during auth flow [default:
                        access-guard-forwarded]
  --verified-cookie-name VERIFIED_COOKIE_NAME
                        Name for cookie set when auth completed successfully
                        [default: access-guard-session]
  --auth-cookie-max-age AUTH_COOKIE_MAX_AGE
                        Seconds before the cookie set _during_ auth flow
                        should expire [default: 3600 (1 hour)]
  --auth-signature-max-age AUTH_SIGNATURE_MAX_AGE
                        Decides how many seconds a verification email should
                        be valid. When the amount of seconds has passed, the
                        client has to request a new email. [default: 600 (10
                        minutes)]
  --verify-signature-max-age VERIFY_SIGNATURE_MAX_AGE
                        Decides how many seconds a verified session cookie
                        should be valid. When the amount of seconds has
                        passed, the client has to verify again. [default:
                        86400 (24 hours)]

Arguments reference

Required arguments

Email patterns

EMAIL_PATTERN [EMAIL_PATTERN ...]

Positional argument

Email address patterns to match for being allowed possibility to verify and access. All entered patterns are case insensitively matched with emails entered by a client.

Example

*@email.com someone@else.com

Secret

-s/--secret SECRET

Should be set to a unique, unpredictable value. Is used for cryptographic signing.

Warning

Both --secret and --secret-file can not be passed at the same time

Secret file

-sf/--secret-file PATH_TO_FILE

As an alternative to passing the secret via command line, the value can be loaded from a file present in the container.

Example

--secret-file /run/secrets/access-guard-secret

Only the first line of the secret file will be read and any newline character at the end of it will be removed.

Warning

If the first line is empty after any newline character has been removed, an error will be raised.

Warning

Both --secret-file and --secret can not be passed at the same time.

Access guard's host

-a/--auth-host AUTH_HOST

The configured url for the access guard service, with protocol and path. The service wants to know this to redirect unverified clients in to the verification flow.

Example

--auth-host http://auth.localhost.com/

Trusted hosts

-t/--trusted-hosts TRUSTED_HOST [TRUSTED_HOST ...]

Hosts/domain names that access guard should serve. Matched against a request's Host header. Wildcard domains are supported for matching subdomains. Remember that for usage with docker and traefik, the name of the access guard service could be a trusted host. That'll allow the forwardauth middleware to configure an address resolved via a docker network. For example (via label/docker configuration):

traefik.http.middlewares.access-guard.forwardauth.address: "http://access-guard:8585/auth"

Example

Multiple hostsWildcard subdomainsAny hostname

--trusted-hosts access-guard auth.localhost.com

--trusted-hosts *.localhost.com

--trusted-hosts *

-c/--cookie-domain COOKIE_DOMAIN

The domain to use for cookies. Ensure this value covers the domain set for --auth-host.

With an auth host configuration of:

--auth-host http://auth.localhost.com/

We can set a cookie domain configuration like

--cookie-domain localhost.com

That'll allow a verification cookie to follow along to, for example, the hosts:

service_1.localhost.com
service_2.localhost.com

SMTP host

--email-host EMAIL_HOST

The host to use for sending of emails

Example

--email-host 172.18.0.1

SMTP port

--email-port EMAIL_PORT

Port to use for the SMTP server defined in --email-host

Example

--email-port 25

Sender's email address

--from-email FROM_EMAIL

What will become the sender's address in sent emails.

Example

--from-email verificator@email.com

Example using minimal arguments

docker run --rm ghcr.io/flaeppe/access-guard:latest \
  ".*@test.com" \
  --secret supersecret \
  --auth-host http://access-guard.localhost.com/ \
  --trusted-hosts access-guard access-guard.localhost.com \
  --cookie-domain localhost.com \
  --email-host mailhog \
  --email-port 1025 \
  --from-email access-guard@local.com

Optional arguments

Bind host

--host HOST

The socket that access guard's server should bind to. This will be inside of a running container.

Default value

0.0.0.0

Bind port

--port PORT

The port that access guard's server should bind to. This will be inside of a running container.

Default value

8585

Log formatter

--log-formatter

Log output format, available choices are json or console

Default value

json

SMTP client username

--email-username EMAIL_USERNAME

Username to login with on configured SMTP server

Default value

Not set

SMTP client password

--email-password EMAIL_PASSWORD

Password to login with on configured SMTP server

Default value

Not set

Warning

Both --email-password and --email-password-file can not be passed at the same time

SMTP client password file

--email-password-file PATH_TO_FILE

As an alternative to passing a password via command line, the value can be loaded from a file present in the container.

Only the first line of the password file will be read and any newline character at the end of it will be removed.

Example

--email-password-file /run/secrets/email-passwd

Default value

Not set

Warning

If the first line is empty after any newline character has been removed, an error will be raised.

Warning

Both --email-password-file and --email-password can not be passed at the same time

SMTP client use TLS

--email-use-tls

Make the initial connection to the SMTP server over TLS/SSL.

Example

--email-use-tls

Default value

false

Warning

Both --email-use-tls and --email-start-tls can not be passed at the same time

SMTP client start TLS

--email-start-tls

Make the initial connection to the SMTP server over plaintext, and then upgrade the connection to TLS/SSL.

Example

--email-start-tls

Default value

false

Warning

Both --email-start-tls and --email-use-tls can not be passed at the same time

Disable SMTP cert validation

--email-no-validate-certs

Disable validating server certificates for SMTP

Example

--email-no-validate-certs

Default value

false

SMTP client TLS cert

--email-client-cert EMAIL_CLIENT_CERT

Path to client side certificate, for TLS verification

Example

--email-client-cert /path/to/cert

Default value

Not set

SMTP client TLS key

--email-client-key EMAIL_CLIENT_KEY

Path to client side key, for TLS verification

Example

--email-client-key /path/to/key

Default value

Not set

Email subject

--email-subject EMAIL_SUBJECT

Subject of the email sent for verification

Example

--email-subject "Custom email subject line"

Default value

"Access guard verification"

--cookie-secure

Whether to only use secure cookies. When passed, cookies will be marked as 'secure'

Example

--cookie-secure

Default value

false

--auth-cookie-name AUTH_COOKIE_NAME

Name for cookie used during auth flow

Example

--auth-cookie-name cookie-name

Default value

access-guard-forwarded

--verified-cookie-name VERIFIED_COOKIE_NAME

Name for cookie set when auth completed successfully

Example

--verified-cookie-name cookie-name

Default value

access-guard-session

--auth-cookie-max-age AUTH_COOKIE_MAX_AGE

Seconds before the cookie set during auth flow should expire

Example

--auth-cookie-max-age 600

Default value

3600 (1 hour)

Verification email max age

--auth-signature-max-age AUTH_SIGNATURE_MAX_AGE

Decides how many seconds a verification email should be valid. When the amount of seconds has passed, the client has to request a new email.

Example

--auth-signature-max-age 300

Default value

600 (10 minutes)

Verified session max age

--verify-signature-max-age VERIFY_SIGNATURE_MAX_AGE

Decides how many seconds a verified session cookie should be valid. When the amount of seconds has passed, the client has to verify again.

Example

--verify-signature-max-age 43200

Default value

86400 (24 hours)

Example using all arguments

docker run --rm ghcr.io/flaeppe/access-guard:latest \
  ".*@test.com" \
  --secret supersecret \
  --auth-host http://access-guard.localhost.com/ \
  --trusted-hosts access-guard access-guard.localhost.com \
  --cookie-domain localhost.com \
  --email-host mailhog \
  --email-port 1025 \
  --from-email access-guard@local.com \
  --host 0.0.0.0 \
  --port 8585 \
  --email-username email-login \
  --email-password SecreT \
  --email-use-tls \
  --email-no-validate-certs \
  --email-client-cert /run/secret/smtp-cert \
  --email-client-key /run/secret/smtp-key \
  --email-subject "You need to verify yourself" \
  --cookie-secure \
  --auth-cookie-name local-access-guard-forwarded \
  --verified-cookie-name local-access-guard-session \
  --auth-cookie-max-age 3600 \
  --auth-signature-max-age 600 \
  --verify-signature-max-age 43200

Note

All available arguments aren't included above, since some of them are mutually exclusive. In addition to the ones seen above the following arguments also exists:

Reference

Prerequisites

Command line arguments

Arguments reference

Required arguments

Email patterns

Secret

Secret file

Access guard's host

Trusted hosts

Cookie domain

SMTP host

SMTP port

Sender's email address

Example using minimal arguments

Optional arguments

Bind host

Bind port

Log formatter

SMTP client username

SMTP client password

SMTP client password file

SMTP client use TLS

SMTP client start TLS

Disable SMTP cert validation

SMTP client TLS cert

SMTP client TLS key

Email subject

Cookie secure

Auth cookie name

Verified cookie name

Auth cookie max age

Verification email max age

Verified session max age

Example using all arguments