Publ: User authentication

Publ supports the use of Authl, an authentication wrapper library, to make it easier to control access to private posts. By configuring a few values in the application configuration and setting up some user groups, you can get fine-grained control over who can see specific posts.

The main things to pay attention to are as follows:

Application configuration

secret_key

The secret_key configuration value controls the signing of the authentication tokens. Essentially, it needs to be kept secret, to prevent others from gaining access that they shouldn’t have.

This is to be set in the configuration dictionary passed into the Publ application constructor; without this value, authentication will not be enabled.

A common pattern is to store this in your application environment variables; for example:

config = {
    # ...
    'secret_key' : os.environ['AUTH_SECRET']
}

app = publ.Publ(__name__, config)

Alternately, you might want to automatically generate the secret key as a local file:

config = {
    # ...
}

if not os.path.isfile('.sessionkey'):
    import uuid
    with open('.sessionkey', 'w') as file:
        file.write(str(uuid.uuid4()))
    os.chmod('.sessionkey', 0o600)
with open('.sessionkey') as file:
    config['secret_key'] = file.read()

auth

This is a key-value dictionary that is sent along to Authl’s from_config settings. See the Authl documentation for the most up-to-date configuration flags; here are some that you are likely to want to use:

• SSL options:
  • AUTH_FORCE_HTTPS: set to True if logins should go over HTTPS instead of HTTP (highly recommended!)
• Email options:
  • SMTP_HOST: the outgoing email host (required; usually localhost)
  • SMTP_PORT: the outgoing email port (required; usually 25 or 587)
  • SMTP_USE_SSL: whether to use SSL/TLS for the SMTP connection (not necessary for localhost but highly recommended for anything else)
  • EMAIL_FROM: the From: address to use when sending an email (required)
  • EMAIL_SUBJECT: the Subject: to use for a login email (required)
  • EMAIL_LOGIN_TIMEOUT: How long (in seconds) the user has to follow the login link
• IndieAuth options:
  • INDIEAUTH_CLIENT_ID: The client ID to send to the remote IndieAuth endpoint (required)¹
• Fediverse (e.g. Mastodon) options:
  • FEDIVERSE_NAME: the name of your website (required)
  • FEDIVERSE_HOMEPAGE: your website’s main URL (recommended)²

• Twitter options:

  • TWITTER_CLIENT_KEY, TWITTER_CLIENT_SECRET: a Twitter application client key and secret

    Note that for safety’s sake these should be read from environment variables, rather than checked in to code.

    In order to get these you need to go to the Twitter developer portal and register your website as an application. If asked for app usage, simply say “To provide Login with Twitter functionality to my website” or similar.

    You will also need to register your Twitter login callback URLs; this will probably be something like https://example.com/_cb/t.

• Test handler options:

  • TEST_ENABLED: whether to enable the test: test handler. Don’t do this.

user_list

This is the filename of a file where you configure access to users and groups. The format is based on a common configuration file format; see the user.cfg format for more information.

admin_group

This configuration setting specifies which user group will have administrative access; by default this is set to admin.

You can also set this configuration option to a specific identity.

Members of the administrative group will always be able to see all entries (including ones which would normally only be visible to logged-out users), and will also have access to the administrative functions of the site (such as being able to see the user log).

Adding authentication to entries

See the Auth: header.

Seeing who’s been logging on

The admin dashboard lives at /_admin; for example, on this site. It is restricted to members of the administrative group (you can log in as test:admin to see it).