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 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 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 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.

With open registration, your site can have up to 1000 active users per month on Identity Free. (“Active users” have logged in at least once in the current billing period.) If your site has more users, we’ll automatically upgrade the site to Identity Pro, which includes up to 5000 active users per month, plus additional features.

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

Invite-only mode

To disable open user registration, go to Settings > Identity > Registration, 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.

For sites with registration set to Invite only, all users in your Identity user list count as invite-only users. Identity Free includes up to 5 invite-only users. If you invite more, we’ll automatically upgrade the site to Identity Pro, which includes up to 100 invite-only users, plus additional features.

Inviting users

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

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

You can allow your 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.

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

Branded external OAuth integration

This feature is available on sites with Identity Pro.

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.

If your site is on an Identity Pro plan, 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 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.

Identity-Generated Emails

Some Netlify Identity actions, like inviting a 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 is available on sites with Identity Pro.

By default, all Identity-generated emails are sent from no-reply@netlify.com. If your site is on an Identity Pro plan, you can change this to an address you own. To do this, go to Settings > Identity > Emails, and edit 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 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 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>

Identity Audit Log

This feature is available on sites with Identity Pro.

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.

null

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.

null

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 plan 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. Identity Free includes up to 1000 active users, and Identity Pro includes up to 5000 active users.
  • 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. Identity Free includes up to 5 invite-only users, and Identity Pro includes up to 100 invite-only users.
  • Branded external OAuth integration: If you enable external provider login, you have the option to use our default configuration, or customize it using your own app credentials with the Identity Pro plan.
  • Custom outgoing email address: Identity-generated emails like password resets are sent from no-reply@netlify.com. With the Identity Pro plan, you can send them from an address you own.
  • Audit log: With an Identity Pro plan, you can view and search a history of all activity for your Identity service.

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

Changing plans

Any user with the ability to change settings on your site can also change plans for services on that site.

To do this, go to Settings > Identity > Identity Instance > Usage, and select Change plan. Plan fees will be prorated and charged at the end of the billing cycle, to the account of the site owner.


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?