Add instructions for auth with Netlify Identity and Git Gateway

[verythorough]

In the current docs outline, this requires changes in a few places:

/docs/intro.md

• Change to a Git Gateway backend in the sample config.yml? (I'm a bit torn on this one, but leaning towards changing.)

/docs/test-drive.md (see PR #626)

• Replace the link in the Deploy to Netlify button with https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/one-click-hugo-cms&stack=cms
• Replace the Authenticate with GitHub section with an Invite users section with instructions for inviting a user (and accepting) with Netlify Identity

/docs/quick-start.md

• Replace the Authenticating with GitHub section with a section about setting up Netlify Identity and Git Gateway. It can link to the Netlify docs at https://www.netlify.com/docs/identity/ and https://www.netlify.com/docs/git-gateway/
• Update the sample index.html file to pull the latest beta version (@>0.5.0-beta.1), and make a note that this setup requires use of the beta version
• In Configuration > Backend, replace the github backend with git-gateway (see the test drive repo config for an example)
• In Accessing the app, modify the sentence about adding users to use Netlify Identity rather than adding repo collaborators (Or cover that in the modified authenticating section above, and remove the sentence here)

/docs/custom-authentication.md (see PR #751)

• Probably rename this to "Authentication" (will require updates to any links to this page, plus a change to https://github.com/netlify/netlify-cms-www/blob/master/markdown.config.js#L20)
• Include instructions for github backend with Netlify auth as well as external providers
• Include instructions for git-gateway with the Netlify-managed Git Gateway/Identity setup, as well as a reference to diy options using the open source Git Gateway and GoTrue or another JWT Oauth provider. (This does not need to be a full guide at this point, but an indicator that it can be done, with links.)

I think that covers everything for now (until we restructure the docs as described in #598). Feel free to add anything I'm missing.

[eamonnbell]

I'd be very happy to help on this, on an ongoing basis, having spent some time this morning trying to get my head around the dependencies between GitHub, the SPA and api.netlify.com.

In particular, I think we can make the docs more explicit about the need for and the nature of any dependencies on Netlify-owned servers (i.e. api.netlify.com for the github backend).

As a concrete example, in the new Authentication section, we should make it clear that when used in a local dev environment, netlify-cms will identify itself as cms.netlify.com to the Netlify auth service.

My sense is as the git-gateway documentation is developed, then the language to describe the Netlify auth ("Authentication Provider") for the github backend will firm up

[verythorough]

Thanks, @eamonnbell! In the interest of getting the simplest parts working before tackling the more involved ones, I'm planning to put up a PR for the test-drive changes today. Then I'll do one for quick-start, probably tomorrow. When those are done and people can see a clearer view of how the git-gateway backend works, we can talk about how to structure the new Authentication page.

Let me know if you'd like to jump in on any of these before I get started (in a few hours).

[eamonnbell]

Sorry for my late reply, I hope I didn't hold up anything. If you haven't started, I could jump in on the "test-drive" changes and have a PR for you to have a look at by tomorrow AM. Or, just @ me when the Authentication page is ready for discussion and we can go from there.

[verythorough]

@eamonnbell no problem! PR #626 referenced above ^ has my update to the Test Drive doc. I'd love it if you could take a look. I'm thinking I'll start next on the Quick Start, but it occurs to me that if it gets published before the Custom Authentication page gets updated, there won't be any docs for the github backend anymore, so I guess both pages will have to be updated together.

[verythorough]

As we re-structure the docs as outlined in #598, I'm using the remaining check points of this issue to track improvements to the authentication and backends documentation. Here's the general page outline from #598:

Backends & authentication

• Detailed config reference and setup guide for available backends:
  • git-gateway
    • requires version 0.5.0
    • full instructions for Netlify Identity setup (detailed in the new Quick Start)
    • links to repos for DIY GoTrue/Git Gateway setup, plus details on any CMS config differences
  • github
    • full instructions with Netlify OAuth provider setup (found in older versions of the Quick Start)
    • details and links to other projects for other options (pull from custom-authentication.md)
  • GitLab, Bitbucket when available (see (WIP) Add GitLab Backend #517 & (WIP) Bitbucket integration #525)

I've called for full instructions for Netlify-enabled backends, and external links for more DIY options, but if there are contributors who would like to write full instructions for those, we can do that.

[DirtyF]

I just followed the documentation and it works great, except for the redirect from the index page, instead a modal is displayed to confirm I'm logged in:

Note: as there's a redirection to latest package version you could simply write
<link rel="stylesheet" href="https://unpkg.com/netlify-cms/dist/cms.js" /> in the documentation.

[AustinGreen]

@DirtyF I'm having trouble getting this working as well. Seems like the init event is never firing. Did you find a solution?

[DirtyF]

@AustinGreen nope, functions still return undefined:

  if (window.netlifyIdentity) {
    window.netlifyIdentity.on("init", user => {
      if (!user) {
        window.netlifyIdentity.on("login", () => {
          document.location.href = "/admin/";
        });
      }
    });
  }
undefined
window.netlifyIdentity
Object { on: on(), open: open(), close: close(), currentUser: currentUser(), logout: logout(), gotrue: Getter, init: init() }
window.netlifyIdentity.on("init", user => {})
undefined
window.netlifyIdentity.on("login", () => {})
undefined

[erquhart]

@DirtyF source issue here: netlify/netlify-identity-widget#86

[erquhart]

Auth issues should be addressed as of 0.7.6.

[verythorough]

#751 Finished this out.