Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposed changes to auth docs update #780

Merged
merged 1 commit into from
Nov 7, 2017
Merged

proposed changes to auth docs update #780

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 61 additions & 45 deletions docs/authentication-backends.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,65 @@
# Authentication & Backends

Committing content changes to your project repo requires authentication with the GitHub API. This is a server-side process, and Netlify CMS offers a few different options to handle this.
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.

## Git Gateway with Netlify Identity

You can check out this authentication method by using the deploy button in the [Test Drive](/test-drive/). It allows you to invite and manage CMS users from the site dashboard on Netlify, giving them permission to use the CMS without requiring commit access to the repo or even a GitHub account at all. All commits are run through a personal access token with limited access rights. (It also lets you to make cool zero-config templates like that one in the Test Drive.)
[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/).

To use it in your own project, add the following lines to your `config.yml` file:
Using it in your own project is simple:

``` yaml
backend:
name: git-gateway
accept_roles: admin, editor #optional - accepts all user roles if left out
```
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:

*Find [More Config Options](#more-config-options) for this backend at the end of this doc.*
``` 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.

Then, you can go to the Netlify dashboard to set up [Identity](https://www.netlify.com/docs/identity/) and enable their managed version of [Git Gateway](https://www.netlify.com/docs/git-gateway/). You'll also need to add a login form to your site, or use the [Netlify Identity widget](https://github.com/netlify/netlify-identity-widget).

For the optional `accepts_roles` field above, you name your own roles when [managing users](https://www.netlify.com/docs/identity/#managing-existing-users) in Netlify Identity. If a user role matches an accepted role, the user will be granted access to the CMS on login.

### Git Gateway without Netlify

The instructions above leverage Netlify services, but [Git Gateway](https://github.com/netlify/git-gateway) is open source, so you can roll your own Git Gateway server, and connect to 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).
## 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).

## GitHub Backend

If all of your content editors already have commit access to your project repo, you may prefer to authenticate directly with GitHub. With this backend, any GitHub user with commit access to your repo will be able to log in to Netlify CMS.
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.

To enable it, add the following lines to your `config.yml` file:
Because Github [requires a
server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for
authentication, Netlify facilitates basic GitHub authentication.

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

*Find [More Config Options](#more-config-options) for this backend at the end of this doc.*
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 `config.yml` file:

Though GitHub handles the access control in this setup, their OAuth flow [still requires a server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723). Netlify provides an [easy setup for this](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider), or you can use another service.
``` yaml
backend:
name: github
repo: owner-name/repo-name # Path to your Github repository
```

Below is a list of community-submitted OAuth providers—feel free to [submit a pull request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add yours!
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!

## External OAuth Clients:
| Author | Supported Git hosts | Languages | Link |
Expand All @@ -53,26 +71,24 @@ Check each project's README for instructions on how to configure it.

## Bitbucket and GitLab 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 PRs in progress for [`bitbucket`](https://github.com/netlify/netlify-cms/pull/525) and [`gitlab`](https://github.com/netlify/netlify-cms/pull/517) backends.

Git Gateway could also be modified to support these 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).

## More Config Options

Both `git-gateway` and `github` backends allow some additional optional fields for certain use cases. You would add these options indented once under the `backend` field, on the same level as the `name` field.
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 PRs in progress for
[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) and
[Gitlab](https://github.com/netlify/netlify-cms/pull/517) backends.

### Sample Syntax
Git Gateway could also be modified to support these 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).

```
branch: production
api_root: https://github.some.domain.com/api/v3
site_domain: static.site.url.com
base_url: https://auth.server.url.com
```
## Options

### Descriptions
Both `git-gateway` and `github` backends 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.

* `branch`: Defaults to `master`. All commits in the simple workflow commit to this branch. All pull requests created in the [editorial workflow](/docs/editorial-workflow) compare and merge to this branch.
* `api_root`: The API endpoint. `git-gateway` ignores this setting; `github` defaults to `https://api.github.com`. Only necessary in certain cases, like when using the `github` backend with GitHub Enterprise.
* `site_domain`: Sets the `site_id` query param sent to the API endpoint. Defaults to `location.hostname`, minus any port, or `cms.netlify.com` when on localhost so that authentication "just works" during local development. Sites with non-Netlify authentication will often need to set this for local development to work properly.
* `base_url`: OAuth client URL for the `github` backend. Defaults to `https://api.netlify.com` as a convenience. This is **required** when using an external OAuth server with the `github` backend.
| 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. |