Authentication & Backends
Netlify CMS stores content in your GitHub or GitLab repository. (Bitbucket coming soon!) In order for this to work, you need to authenticate with your Git host, and in most cases that requires a server. We have a few options for handling this.
Note: some static site generators have plugins for optimized integration with Netlify CMS, and starter templates may utilize these plugins. If you’re using a starter template, read the template documentation before proceeding, as their instructions may differ.
Git Gateway with Netlify Identity
Git Gateway is a Netlify open source project that allows you to add editors to your site CMS without giving them direct push access to your GitHub or GitLab repository. Netlify Identity service can handle the authentication and provides a simple interface for user management. The Netlify CMS featured templates are working examples of this backend.
To use it in your own project, follow these steps:
- Head over to the Netlify Identity docs and follow the steps to get started.
Add the following lines to your Netlify CMS
backend: name: git-gateway accept_roles: #optional - accepts all users if left out - admin - editor
Optionally, you can assign roles to users in your Netlify dashboard, and then limit which roles can access the CMS by defining the
accept_rolesfield as shown in the example above. Otherwise
accept_rolescan be left out, and all Netlify Identity users on your site will have access.
Git Gateway without Netlify
You can use Git Gateway without Netlify by setting up your own Git Gateway server and connecting it with your own instance of GoTrue (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).
To configure in Netlify CMS, use the same
backend settings in your Netlify CMS
config.yml file as described in Step 2 of the Git Gateway with Netlify Identity instructions above.
For repositories stored on GitHub, the
github backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.
Because Github requires a server for authentication, Netlify facilitates basic GitHub authentication.
To enable it:
- Follow the authentication provider setup steps in the Netlify docs.
Add the following lines to your Netlify CMS
backend: name: github repo: owner-name/repo-name # Path to your Github repository
For repositories stored on GitLab, the
gitlab backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work.
Unlike GitHub, the GitLab API allows for two types of OAuth2 flows: Web Application Flow, which works much like the GitHub OAuth flow described above, and Implicit Grant, which operates without the need for an authentication server.
Web Application Flow with Netlify
When using GitLab’s Web Application Flow for authentication, you can use Netlify to handle the server-side authentication requests.
To enable it:
- Follow the GitLab docs to add your Netlify CMS instance as an OAuth application. For the Redirect URI, enter
https://api.netlify.com/auth/done, and check the box for
- Follow the Netlify docs to add your new GitLab Application ID and Secret to your Netlify site dashboard.
In your repository, add the following lines to your Netlify CMS
backend: name: gitlab repo: owner-name/repo-name # Path to your GitLab repository
Client-Side Implicit Grant
With GitLab’s Implicit Grant, users can authenticate with GitLab directly from the client. To do this:
- Follow the GitLab docs to add your Netlify CMS instance as an OAuth application. For the Redirect URI, enter the address where you access Netlify CMS, for example,
https://www.mysite.com/admin. For scope, select
GitLab will give you an Application ID. Copy this and enter it in your Netlify CMS
config.ymlfile, along with the following settings:
backend: name: gitlab repo: owner-name/repo-name # Path to your GitLab repository auth_type: implicit # Required for implicit grant app_id: your-app-id # Application ID from your GitLab settings
You can also use Implicit Grant with a self-hosted GitLab instance. This requires adding
backend: name: gitlab repo: owner-name/repo-name # Path to your GitLab repository auth_type: implicit # Required for implicit grant app_id: your-app-id # Application ID from your GitLab settings api_root: https://my-hosted-gitlab-instance.com/api/v4 base_url: https://my-hosted-gitlab-instance.com auth_endpoint: oauth/authorize
Note that in both cases, GitLab will also provide you with a client secret. You should never store this in your repo or reveal it in the client.
Netlify CMS is meant to be platform agnostic, so we’re always looking to expand the ecosystem and find new ways to use it. Check out our active PR in progress for Bitbucket backend support.
Git Gateway could also be modified to support other Git hosts. If you’re interested, you can file an issue (or a pull request!) in the git-gateway repo.
External OAuth Clients
If you would like to facilitate your own OAuth authentication rather than use Netlify’s service or implicit grant, you can use one of the community-maintained projects below. Feel free to submit a pull request if you’d like to add yours!
|Author||Supported Git hosts||Language(s)/Platform(s)||Link|
|@vencax||GitHub, GitHub Enterprise||Node.js||Repo|
|@igk1972||GitHub, GitHub Enterprise||Go||Repo|
|@davidejones||GitHub, GitHub Enterprise||Python||Repo|
|@marksteele||GitHub, GitHub Enterprise||Serverless||Repo, Blog|
Check each project’s documentation for instructions on how to configure it.
gitlab backends all allow some additional optional fields for certain use
cases. A full reference is below. Note that these are properties of the
backend field, and should
be nested under that field.
||The branch where published content is stored. All CMS commits and PRs are made to this branch.|
||The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab.|
||OAuth client URL. Required when using an external OAuth server or self-hosted GitLab.|
||Path to append to