× press ESC to close

Netlify builds, deploys, and hosts your front end.

This feature is in beta.

Netlify Identity service brings a full suite of authentication functionality, backed by the GoTrue API. This allows you to manage and authenticate users on your site or app, without requiring them to be users of Netlify or any other service. You can use this for gated content, site administration, and more.

For a working example using Netlify Identity service with Git Gateway to manage users in Netlify CMS, try deploying this repository:

Deploy to Netlify

After clicking the Deploy to Netlify button above, you can follow the steps below to invite a user to the project. When that user clicks the link in the invitation email that follows, they’ll have access to edit site content with Netlify CMS, without a GitHub account or access to the repository.

That’s one example of something awesome that you can do with Identity service. To add Identity service to your existing web projects, check out the instructions below.

Getting Started

Note: Identity service requires HTTPS. If you’re using a custom domain, be sure to enable HTTPS before integrating Identity service with your site.

To enable Identity service on your site, select the Identity tab and click Enable Identity. This will create an Identity service instance for your site, and allow you to invite users and change settings. To use the service in your site, you can add the Netlify Identity widget to your repository, or develop a custom solution with the gotrue-js library.

null

Adding Users

User registration

By default, user registration is open, meaning users can sign up using a form on your site. You can include the Netlify Identity widget in your site to handle this, or build your own form and integrate it using gotrue-js.

When a user registers for your site, it will trigger an email requesting that the user confirm their address (following the template below). If you would like to skip this confirmation step, go to Settings > Identity > Email templates > Confirmation, then select Edit settings. Check the box to allow users to sign up without verifying their email address.

To disable new user registration, go to Settings > Identity > Identity configuration, and select Invite only under Registration preferences.

null

When Invite only is selected, all new users, including those logging in with external providers, will need to be invited before they can register for your site.

Inviting users

You can invite new users to your site from the Identity tab, triggering emails (following the template described below) to the addresses you specify.

null

The confirmation link in the email will direct to your site, with an invite_token appended. If you use the Netlify Identity widget in your site, it will handle this address automatically, prompting the user for a name and password. Alternatively, you can handle it with your own code using the gotrue-js library.

External providers

You can allow your users to log in to your site using an account with an external service provider. Go to Settings > Identity > Identity confirguration, and under External providers, select the providers you would like to include. We currently support Google, GitHub, Bitbucket, and GitLab.

null

If you use the Netlify Identity widget in your site, it will automatically include login/registration buttons for all providers you’ve enabled. When a user registers using an external provider, no email confirmation is required. However, if you’ve set your registration preference to Invite only, you will need to invite them before they can register.

null

Managing Existing Users

You can access settings for an individual user by clicking their entry under Identity > Registered users.

null

Password recovery

From an individual user page, click the Send reset password email button to trigger an email to the user, following the template below. The .ConfirmationURL variable in that email will include your site address with a recovery_token appended. The Netlify Identity widget will handle this link automatically, or you can develop a custom password reset form with gotrue-js.

User account metadata

Information stored in this section will be set in the user object on the /user endpoint in the GoTrue API (accessible via auth.currentUser() in gotrue-js). You can edit these fields by clicking Edit settings on an individual user page:

  • Name: user editable; set under "user_metadata": {"full_name": "Jessica Jones"}
  • Email: user editable; triggers email change confirmation email; changes user login credentials; set under "user_metadata": {"email": "jessica@aliasinvestigations.com"}
  • Roles: not user editable; you can assign one or more roles of your choosing, then use them to control access to areas or functionality in your site by checking this property: "app_metadata": {"roles": \["investigator", "photographer"\]} You can also use these roles with other Netlify services, like Git Gateway.

Email templates

Some Netlify Identity functions will trigger an email to the user. These emails have basic templates built in, but you may customize them by creating new templates and saving them to your site repository, then specifying the path to the template in Settings > Identity > Email templates.

A few general notes:

  • You may use any email-ready html in your templates. CSS must be included inline, and images must use absolute links.
  • You may include certain variables using Go template syntax, like {{ .SiteURL }}. The following variables are available:
    • {{ .SiteURL }}: URL of your site
    • {{ .ConfirmationURL }}: site URL with corresponding email action parameters appended
    • {{ .Email }}: user’s current registered email address
    • {{ .NewEmail }} (email change template only): new email address the user would like to use in place of the current address
  • You may change the email subject line directly in the settings UI.

Default templates are as follows:

Invitation:

<h2>You have been invited</h2>

<p>You have been invited to create a user on {{ .SiteURL }}. Follow this link to accept the invite:</p>
<p><a href="{{ .ConfirmationURL }}">Accept the invite</a></p>

Confirmation:

<h2>Confirm your signup</h2>

<p>Follow this link to confirm your account:</p>
<p><a href="{{ .ConfirmationURL }}">Confirm your mail</a></p>

Password recovery:

<h2>Reset Password</h2>

<p>Follow this link to reset the password for your account:</p>
<p><a href="{{ .ConfirmationURL }}">Reset Password</a></p>

Email change:

<h2>Confirm Change of Email</h2>

<p>Follow this link to confirm the update of your email from {{ .Email }} to {{ .NewEmail }}:</p>
<p><a href="{{ .ConfirmationURL }}">Change Email</a></p>

Notice something is incorrect or outdated?

First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.

Want to get started quick?