Sveltia CMS Authenticator

This simple Cloudflare Workers script allows Sveltia CMS users to authenticate with GitHub.

[!IMPORTANT] In most cases, you don’t need this authenticator. Sveltia CMS supports multiple authentication methods for GitHub and GitLab, so you can choose the one that best suits your needs without having to set up this OAuth client.

[!IMPORTANT] Although this authenticator is compatible with Netlify CMS (now Decap CMS), it is designed for use with modern Sveltia CMS instances. Please refer to the Sveltia CMS documentation for more information about the differences between these products and the reasons why Decap CMS should not be used for new projects.

When to use it

You don’t need it if…

• You’re migrating from Netlify CMS or Decap CMS
  • Your site is being deployed to Netlify
    • You can keep using Netlify’s built-in OAuth client for Sveltia CMS without any changes to your CMS configuration.
  • You already use another 3rd party OAuth client
    • You can keep using it for Sveltia CMS without any changes to your CMS configuration.
• You’re using GitHub
  • You or technical users are the only users of your CMS instance
    • Use the access token method instead.
• You’re using GitLab
  • You or technical users are the only users of your CMS instance
    • Use the access token method instead.
  • Non-technical users need to sign into the CMS
    • Use client-side PKCE authorization instead.

You may need it only if…

• You’re using GitHub
  • Non-technical users need to sign into the CMS
    • This authenticator will provide a better user experience than the access token method, which requires users to create and manage their own personal access tokens.

[!NOTE] GitLab users don’t need this authenticator at all. GitLab support is included here only for completeness.

How to use it

Step 1. Deploy this project to Cloudflare Workers

Sign up with Cloudflare, and click the button below to start deploying.

Alternatively, you can clone the project and run wrangler deploy locally.

Once deployed, open your Cloudflare Workers dashboard, select the sveltia-cms-auth service, then the worker URL (https://sveltia-cms-auth.<SUBDOMAIN>.workers.dev) will be displayed. Copy it for Step 2. It will also be used in Step 4.

Step 2. Register the Worker as an OAuth app

GitHub

Register a new OAuth application on GitHub (details) with the following properties, including your Worker URL from Step 1:

• Application name: Sveltia CMS Authenticator (or whatever)
• Homepage URL: https://github.com/sveltia/sveltia-cms-auth (or whatever)
• Application description: (can be left empty)
• Authorization callback URL: <YOUR_WORKER_URL>/callback

Once registered, click on the Generate a new client secret button. The app’s Client ID and Client Secret will be displayed. We’ll use them in Step 3 below.

GitLab

Register a new OAuth application on GitLab (details) with the following properties, including your Worker URL from Step 1:

• Name: Sveltia CMS Authenticator (or whatever)
• Redirect URI: <YOUR_WORKER_URL>/callback
• Confidential: Yes
• Scopes: api only

Once registered, the app’s Application ID and Secret will be displayed. We’ll use them in Step 3 below.

Step 3. Configure the Worker

Go back to the sveltia-cms-auth service page on the Cloudflare dashboard, select Settings > Variables, and add the following Environment Variables to your worker (details):

GitHub

• GITHUB_CLIENT_ID: Client ID from Step 2
• GITHUB_CLIENT_SECRET: Client Secret from Step 2; click the Encrypt button to hide it
• GITHUB_HOSTNAME: Required only if you’re using GitHub Enterprise Server. Default: github.com

GitLab

• GITLAB_CLIENT_ID: Application ID from Step 2
• GITLAB_CLIENT_SECRET: Secret from Step 2; click the Encrypt button to hide it
• GITLAB_HOSTNAME: Required only if you’re using a self-hosted instance. Default: gitlab.com

Both GitHub and GitLab

• ALLOWED_DOMAINS: (Optional) Your site’s hostname, e.g. www.example.com
  • Multiple hostnames can be defined as a comma-separated list, e.g. www.example.com, www.example.org
  • A wildcard (*) can be used to match any subdomain, e.g. *.example.com that will match www.example.com, blog.example.com, docs.api.example.com, etc. (but not example.com)
  • To match a www-less naked domain and all the subdomains, use example.com, *.example.com
  • The list serves two purposes: it stops other sites from using your Worker at your expense (anti-abuse), and it stops them from obtaining an access token through it (security), because the authenticator releases a token only to a page served from one of these hostnames

[!IMPORTANT] ALLOWED_DOMAINS is optional, but it’s both an anti-abuse and a security measure, so setting it is strongly recommended.

Save and deploy.

Step 4. Update your CMS configuration

Open admin/config.yml locally or remotely, and add your Worker URL from Step 1 as the new base_url property under backend:

 backend:
   name: github # or gitlab
   repo: username/repo
   branch: main
+  base_url: <YOUR_WORKER_URL>

Commit the change. Once deployed, you can sign into Sveltia CMS remotely with GitHub or GitLab!

FAQ

Why do I have to set this thing up in the first place?

Technically, we could host Sveltia CMS Authenticator on our own server and let anyone use it, just like Netlify does. The cost probably wouldn’t matter because it’s just a small, short-lived script. However, running such a service certainly comes with legal, privacy and security liabilities that we cannot afford. Remember that Sveltia CMS is nothing more than @kyoshino’s personal project. That’s why the authenticator is not offered as SaaS and you have to install it yourself.

Acknowledgements

This project was inspired by netlify-cms-oauth-firebase.