153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
---
|
||
title: Authentication & Backends
|
||
weight: 25
|
||
menu:
|
||
docs:
|
||
parent: start
|
||
---
|
||
# Authentication & Backends
|
||
|
||
Netlify CMS stores content in your GitHub or GitLab repository. (Bitbucket [coming soon](https://github.com/netlify/netlify-cms/pull/525)!) 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](https://github.com/netlify/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](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](https://www.netlifycms.org/docs/start-with-a-template) are working examples of this backend.
|
||
|
||
To use it in your own project, follow these steps:
|
||
|
||
1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the
|
||
steps to get started.
|
||
2. Add the following lines to your Netlify CMS `config.yml` file:
|
||
|
||
```yaml
|
||
backend:
|
||
name: git-gateway
|
||
accept_roles: #optional - accepts all users if left out
|
||
- admin
|
||
- editor
|
||
```
|
||
|
||
3. Optionally, you can assign roles to users in your Netlify dashboard, and then limit which
|
||
roles can access the CMS by defining the `accept_roles` field as shown in the example above.
|
||
Otherwise `accept_roles` can be left out, and all Netlify Identity users on your site will have access.
|
||
|
||
## Git Gateway without Netlify
|
||
|
||
You can use [Git Gateway](https://github.com/netlify/git-gateway) without Netlify by setting up your own Git Gateway server and connecting it with your own instance of [GoTrue](https://www.gotrueapi.org) (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](#git-gateway-with-netlify-identity) instructions above.
|
||
|
||
## GitHub Backend
|
||
|
||
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](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for
|
||
authentication, Netlify facilitates basic GitHub authentication.
|
||
|
||
To enable it:
|
||
|
||
1. Follow the authentication provider setup steps in the [Netlify
|
||
docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
|
||
2. Add the following lines to your Netlify CMS `config.yml` file:
|
||
|
||
```yaml
|
||
backend:
|
||
name: github
|
||
repo: owner-name/repo-name # Path to your Github repository
|
||
```
|
||
|
||
## GitLab Backend
|
||
|
||
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](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above, and [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#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:
|
||
|
||
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) 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 `api` scope.
|
||
2. Follow the [Netlify
|
||
docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider) to add your new GitLab Application ID and Secret to your Netlify site dashboard.
|
||
2. In your repository, add the following lines to your Netlify CMS `config.yml` file:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) 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 `api`.
|
||
2. GitLab will give you an **Application ID**. Copy this and enter it in your Netlify CMS `config.yml` file, along with the following settings:
|
||
|
||
```yaml
|
||
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 `api_root`, `base_url`, and `auth_endpoint` fields:
|
||
|
||
```yaml
|
||
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.
|
||
|
||
## Bitbucket Support
|
||
|
||
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](https://github.com/netlify/netlify-cms/pull/525) 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](https://github.com/netlify/git-gateway).
|
||
|
||
## 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](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add yours!
|
||
|
||
| Author | Supported Git hosts | Language(s)/Platform(s) | Link |
|
||
| ---------------------------------------------- | ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [@vencax](https://github.com/vencax) | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) |
|
||
| [@igk1972](https://github.com/igk1972) | GitHub, GitHub Enterprise | Go | [Repo](https://github.com/igk1972/netlify-cms-oauth-provider-go) |
|
||
| [@davidejones](https://github.com/davidejones) | GitHub, GitHub Enterprise | Python | [Repo](https://github.com/davidejones/netlify-cms-oauth-provider-python) |
|
||
| [@marksteele](https://github.com/marksteele) | GitHub, GitHub Enterprise | Serverless | [Repo](https://github.com/marksteele/netlify-serverless-oauth2-backend), [Blog](https://www.control-alt-del.org/blog/serverless-blog-howto/) |
|
||
|
||
Check each project's documentation for instructions on how to configure it.
|
||
|
||
## Options
|
||
|
||
The `git-gateway`, `github`, and `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.
|
||
|
||
| Field | Default | Description |
|
||
| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `repo` | none | **Required** for `github` and `gitlab` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
|
||
| `accept_roles` | none | `git-gateway` only. Limits CMS access to your defined array of user roles. Omitting this field gives access to all registered users. |
|
||
| `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. |
|
||
| `api_root` | `https://api.github.com` (GitHub) or `https://gitlab.com/api/v4` (GitLab) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. |
|
||
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
|
||
| `base_url` | `https://api.netlify.com` (GitHub) or `https://gitlab.com` (GitLab) | OAuth client URL. **Required** when using an external OAuth server or self-hosted GitLab. |
|
||
| `auth_endpoint` | `auth` (GitHub) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. |
|