Identity

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 an Identity 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 to be secure. If you’re using a custom domain, 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 Identity 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.

Adding Identity users

Identity user registration

By default, Identity 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 an Identity 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 > Emails > Confirmation template, then select Edit settings. Check the box to allow Identity users to sign up without verifying their email address.

Invite-only mode

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

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

Inviting Identity users

You can invite new Identity users to your site from the Identity tab. This will send email invitations (using the template described below) to the addresses you enter.

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 Provider Login

You can allow your Identity users to log in to your site using an account with another service provider, like Google, GitHub, GitLab, or Bitbucket. Go to Settings > Identity > Registration, and under External providers, select Add provider.

If you use the Netlify Identity widget in your site, it will automatically include login/registration buttons for all providers you’ve enabled. When an Identity 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.

Branded external OAuth integration

This feature may not be available at all levels.

By default, we use our own Netlify Identity app to request authorization from external OAuth providers. This means that when your site visitors use their external account to log in, they will see “Netlify Identity” as the app requesting authorization.

Alternatively, you can set up your own authentication credentials so that your visitors will see your app name as the app requesting authorization. To do this, you’ll need to register your app with the external service and get a client ID and client secret to enter into your settings on Netlify.

Instructions for registering your app can be found in the documentation for the external providers we currently support:

Managing existing Identity users

You can access settings for an individual Identity user by clicking their entry in the list on the site’s Identity tab.

Password recovery

From an individual Identity 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.

Identity user metadata

Information stored in this section will be set in the Identity 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 Identity user page:

  • Name: Identity user editable; set under "user_metadata": {"full_name": "Jessica Jones"}
  • Email: Identity user editable; triggers email change confirmation email; changes Identity user login credentials; set under "user_metadata": {"email": "jessica@aliasinvestigations.com"}
  • Roles: not Identity 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.

Identity-Generated Emails

Some Netlify Identity actions, like inviting an Identity user or resetting a password, will trigger an email to the user. You can customize the email sender address, as well as the templates used.

Custom sender address

This feature may not be available at all levels.

By default, all Identity-generated emails are sent from no-reply@netlify.com. You can change this to an address you own by going to Settings > Identity > Emails, and editing settings under Outgoing email address.

Email templates

All Identity-generated 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 > Emails.

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 Identity user would like to use in place of the current address
    • {{ .Token }}: The token needed to confirm the action. To customize the path the emails link to you can use the following patterns:
      • Confirmation: {{ .SiteURL }}/some/path/#confirmation_token={{ .Token }}
      • Email change: {{ .SiteURL }}/some/path/#email_change_token={{ .Token }}
      • Invite: {{ .SiteURL }}/some/path/#invite_token={{ .Token }}
      • Recovery: {{ .SiteURL }}/some/path/#recovery_token={{ .Token }}
  • 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 user:</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 user:</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>

Identity audit log

This feature may not be available at all levels.

Netlify keeps a log of actions taken by your Netlify Identity users. To see a site’s Identity audit log from the site dashboard, select the Identity tab, then click the Identity audit log button.

Searching audit logs

To search a site’s Identity audit logs, provide a scoped search term and press enter or click the magnifying glass icon in the search field.

Searches require a scope: prefix. The following search scopes are available:

  • author:example — search all logs for events by a particular author.

Usage and Billing

You can check your Identity service usage under Settings > Identity > Identity Instance > Usage. This shows your current usage level and tracks your usage of the following services:

  • Active users: If your site is set to open registration, we’ll track the number of visitors who have logged in to your site during this billing period.
  • Invite-only users: If your site registration is set to Invite only, we’ll count all users in your Identity user list, regardless of activity.
  • Branded external OAuth integration: If you enable external provider login, you have the option to use our default configuration, or upgrade levels to customize login using your own app credentials.
  • Custom outgoing email address: Identity-generated emails like password resets are sent from no-reply@netlify.com by default. At higher levels, you can send them from an address you own.
  • Audit log: At higher levels, you can view and search an activity history for your Identity service.

Metered features like your Identity user count are charged based on usage. When usage reaches a level limit, the site will automatically upgrade to the next level or package.

Changing levels

Any team member with the ability to change settings on your site can also change levels for services on that site.

To do this, go to Settings > Identity > Identity Instance > Usage, and select Change level. Add-on fees will be prorated and charged at the end of the billing cycle, to the team’s payment method.


Notice something is incorrect or outdated?

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



Want to have a conversation?

Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.

Want to get started quick?