Authentication and Authorization

Outdated: as of 2024-03-13, this page is outdated

snug supports user authentication via popular third-party services, enabling you to implement login functionality for your site without building your own authentication system.

Currently, snug supports logging in via:

GitHub
Patreon

Setting Up GitHub Authentication

To enable GitHub authentication for your site:

Create an OAuth App in GitHub:
- Go to GitHub Developer Settings
- Click on “OAuth Apps” and then “New OAuth App”
- Fill in the application details:
  - Application name: Your site name (e.g., “My Snug Blog”)
  - Homepage URL: Your site’s base URL
    - For development: http://yourdomain.snug.blog:1111 (e.g., http://fasterthanli.me.snug.blog:1111)
    - For production: https://yourdomain.com (e.g., https://fasterthanli.me)
  - Authorization callback URL: Your site’s callback URL
    - For development: http://yourdomain.snug.blog:1111/login/github/callback (e.g., http://fasterthanli.me.snug.blog:1111/login/github/callback)
    - For production: https://yourdomain.com/login/github/callback (e.g., https://fasterthanli.me/login/github/callback)
- Click “Register Application”
After creating the app, you’ll receive:
- Client ID
- Client Secret
Configure your tenant in your snug.json configuration file:

{
  "tenants": {
    "yourdomain.com": {
      "secrets": {
        "github": {
          "oauth_client_id": "your_github_client_id",
          "oauth_client_secret": "your_github_client_secret"
        }
      },
      "admin_github_ids": ["12345678"]
    }
  }
}

The admin_github_ids field contains GitHub user IDs that will have administrative access to your site.

Setting Up Patreon Authentication

To enable Patreon authentication for your site:

Create a Patreon OAuth client:
- Go to Patreon Developer Portal
- Create a new client with the following details:
  - App Name: Your site name (e.g., “My Snug Blog”)
  - Redirect URIs:
    - For development: http://yourdomain.snug.blog:1111/login/patreon/callback (e.g., http://fasterthanli.me.snug.blog:1111/login/patreon/callback)
    - For production: https://yourdomain.com/login/patreon/callback (e.g., https://fasterthanli.me/login/patreon/callback)
After creating the client, you’ll receive:
- Client ID
- Client Secret
Configure your tenant in your snug.json configuration file:

{
  "tenants": {
    "yourdomain.com": {
      "secrets": {
        "patreon": {
          "oauth_client_id": "your_patreon_client_id",
          "oauth_client_secret": "your_patreon_client_secret"
        }
      },
      "patreon_campaign_ids": ["12345"],
      "admin_patreon_ids": ["67890"]
    }
  }
}

The patreon_campaign_ids field specifies which Patreon campaigns users need to be members of to access your site. The admin_patreon_ids field contains Patreon user IDs that will have administrative access to your site.

Authentication Flow

When a user clicks a login button on your site, they’ll be redirected to the authentication provider (GitHub or Patreon) to authorize your application. After authorization, they’ll be redirected back to your site with an authorization code, which snug will exchange for an access token. snug handles all the authentication flow details for you.

Further Customization

You can customize authentication behavior by modifying templates that handle login flows. For more details on templates, see the Templates documentation.