Skip to content

Commit

Permalink
Additional edits to auth doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@verythorough
verythorough committed Nov 14, 2017
1 parent 66d80df commit 9cacb21
Showing 1 changed file with 37 additions and 40 deletions.
77 changes: 37 additions & 40 deletions docs/authentication-backends.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,40 @@
# Authentication & Backends

Netlify CMS stores content in your GitHub repository (GitLab and Bitbucket coming soon!). You'll
need to sign in to your GitHub account through the CMS for this to work, and it requires a server.
We have a few options for handling this.
Netlify CMS stores content in your GitHub repository. (GitLab and Bitbucket coming soon!) In order for this to work, you need to authenticate with GitHub, and that requires a server. We have a few options for handling this.

## Git Gateway with Netlify Identity

[Git Gateway](https://github.com/netlify/git-gateway) another Netlify open source project, together
with the [Netlify Identity](https://www.netlify.com/docs/identity/) service, provides a way for CMS
users to sign in with email and password, and doesn't require them to have a GitHub account. This is
a great option for non-technical editors, or if you don't want CMS users to
have direct access to your GitHub repo. You can try Git Gateway with Netlify Identity any time via
the [Test Drive](/test-drive/).
[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 repository. [Netlify Identity](https://www.netlify.com/docs/identity/) service handles the authentication and provides a simple interface for user management. The Netlify CMS [Test Drive](/test-drive/) is a working example of this backend.

Using it in your own project is simple:
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 `config.yml` file:

``` yaml
backend:
name: git-gateway
accept_roles: "admin, editor" #optional - accepts all user roles if left out
```
3. Optionally, you can assign roles to users in your Netlify dashboard, and then only allow certain
roles to access the CMS by defining the `accept_roles` field in the `config.yml` example above.
Otherwise it can be left out.
``` 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 in the `config.yml` example above.
Otherwise `accept_roles` can be left out, and all Netlify Identity users on your site will have access.

## Git Gateway without Netlify

[Git Gateway](https://github.com/netlify/git-gateway) can be used 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).
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 `config.yml` file as described in Step 2 of the [Git Gateway with Netlify Identity](#git-gateway-with-netlify-identity) instructions above.

## GitHub Backend

The GitHub backend allows CMS users to log in directly with their GitHub account. Note that the
user's GitHub account must have push access to your content repo for this to work.
user's GitHub account 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
Expand All @@ -50,23 +46,23 @@ To enable it:
docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your `config.yml` file:

``` yaml
backend:
name: github
repo: owner-name/repo-name # Path to your Github repository
```
``` yaml
backend:
name: github
repo: owner-name/repo-name # Path to your Github repository
```


### External OAuth Clients
If you would like to facilitate your own OAuth authentication rather than use Netlify's service, you
can use one of the community maintained providers below, and feel free to [submit a pull
request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add
yours!
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!


## External OAuth Clients:
| Author | Supported Git hosts | Languages | Link |
|------------|---------------------------|-----------|---------------------------------------------------------------------|
| @vencax | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) |

Check each project's README for instructions on how to configure it.
Check each project's documentation for instructions on how to configure it.


## Bitbucket and GitLab Support
Expand All @@ -85,10 +81,11 @@ Both `git-gateway` and `github` backends allow some additional optional fields f
cases. A full reference is below. Note that these are properties of the `backend` field, and should
be nested under that field.

| Field | Required | Default | Description |
|---------------|----------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `repo` | Yes | n/a | The username of the repo owner, and the repo name, separated by a slash. |
| `branch` | No | `master` | The branch to store published content on. |
| `api_root` | No | `https://api.github.com` (ignored for `git-gateway` backend) | The API endpoint. Only necessary in certain cases, e.g. for GitHub Enterprise users on the `github` backend. |
| `site_domain` | No | `[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` | No | `https://api.netlify.com` | OAuth client URL for the `github` backend. Required when using an external OAuth server with the `github` backend. |
| Field | Default | Description |
|----------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `repo` | none | **Required** for `github` backend; 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` (ignored for `git-gateway` backend) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise. |
| `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` | OAuth client URL for the `github` backend. **Required** when using an external OAuth server with the `github` backend. |

0 comments on commit 9cacb21

Please sign in to comment.