From cf8c9a0137267b2710ba0a4bedcfbd578ce9c11a Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Mon, 13 Nov 2017 18:21:57 -0800 Subject: [PATCH] Additional edits to auth doc --- docs/authentication-backends.md | 77 ++++++++++++++++----------------- 1 file changed, 37 insertions(+), 40 deletions(-) diff --git a/docs/authentication-backends.md b/docs/authentication-backends.md index 70aebf079355..58741601e543 100644 --- a/docs/authentication-backends.md +++ b/docs/authentication-backends.md @@ -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 @@ -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 @@ -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. | \ No newline at end of file +| 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. | \ No newline at end of file