Authentication Providers

One challenge for frontend projects is handling authentication. OAuth2 is a widely accepted standard used by many services and APIs, but the OAuth authentication process requires a server to send a signed request to the OAuth server, signed with a secret that you can never expose to the client side of your app.

Netlify solves this problem by providing an integrated a service that will sign the OAuth requests for you and give back an access token ready to use.

Using an Authentication Provider

Before you can use an authentication provider, you’ll need to register an API application with the provider and configure the credentials through the Netlify UI.

Netlify currently supports authentication with GitHub, GitLab, and Bitbucket. We’ll go through an example using GitHub:

  1. In GitHub, go to your account Settings, and click Oauth Applications under Developer Settings (or use this shortcut).
  2. Click Register a new application.
  3. For the Authorization callback URL, enter https://api.netlify.com/auth/done. The other fields can contain anything you want.

When you complete the registration, you’ll be given a Client ID and a Client Secret for the app. You’ll need to add these to your Netlify project:

  1. Go to your Netlify dashboard and click on your project.
  2. Navigate to Settings > Access control > OAuth.
  3. Under Authentication Providers, click Install Provider.
  4. Select GitHub and enter the Client ID and Client Secret, then save.

Once you’ve configured an authentication provider you can use it to obtain an access token in your app.

Here’s a complete example of how to ask the user to authenticate with GitHub and then display the resulting access token:

<!doctype html>
<html>
<head>
  <title>GitHub Authentication Example</title>
  <!--- This example uses jQuery: -->
  <script src="https://code.jquery.com/jquery-1.11.2.js"></script>

  <!-- Make sure to include Nelify's authentiation library -->
  <!-- Also available via npm as netlify-auth-providers -->
  <script src="https://unpkg.com/netlify-auth-providers"></script>

  <script>
    $(function() {
      $("#login").on("click", function(e) {
        e.preventDefault();
        var authenticator = new netlify.default ({});
        authenticator.authenticate({provider:"github", scope: "user"}, function(err, data) {
          if (err) {
            return $("#output").text("Error Authenticating with GitHub: " + err);
          }
          $("#output").text("Authenticated with GitHub. Access Token: " + data.token);
        });
      });
    });
  </script>
</head>
<body>
  <h1>GitHub Auth Demo:</h1>
  <p><a href="#" id="login">Authenticate</a></p>
  <p id="output"></p>
</body>
</html>

You can then use the generated authentication token in your calls to the service API.


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?