Skip to content
Netlify SDK Docs Netlify SDK Docs 2.15.0

Get started with OAuth

This page will help you configure your extension to work with your OAuth identity provider, add an OAuth card element to your extension UI, and add logic to use the OAuth token on API requests while the extension runs.

Prerequisites

Before you start, you need:

  • An extension that is published as a private extension. This is required because you will configure OAuth in the extension’s settings in the Netlify UI.
  • An OAuth identity provider that supports and follows the OAuth 2.0 protocol. You will need access to their developer portal.
  • The authorization URL and token URL for your OAuth identity provider.

A good understanding of how OAuth works is also recommended. Learn more about OAuth 2.0.

Configure your extension for OAuth

To configure your extension to work with OAuth, you need to register a client application with your OAuth identity provider and then configure your extension for OAuth in the Netlify UI.

Register a client application with your OAuth identity provider

OAuth identity providers require you to identify what sites and services can authenticate against the authorization server. These identified sites and services are often referred to as client applications.

To begin, register Netlify’s extension service as a client application with your OAuth identity provider.

  1. Go to the developer portal of the OAuth identity provider you want to integrate with.
  2. Find the section to register a new client application.
  3. Fill in the following details:
    • Name: you can use any value here. For example, Netlify extension service
    • Redirect URI: set this to https://api.netlify.com/auth/done/identeer
    • Scopes: select the scopes you require from the identity provider
  4. After registering the client application, you will receive a client ID and client secret. Keep these safe as you will need them in the next step.

Next, configure your extension for OAuth in the Netlify UI.

Configure your extension to work with your OAuth identity provider

After you create a client application on your OAuth identity provider, you can configure your extension to work with OAuth in the Netlify UI.

You will need to provide the authorization details for your OAuth identity provider and the details for the client application you registered in the steps documented above.

  1. If you haven’t already, follow the steps to publish your extension as a private extension.
  2. In the Netlify UI, select the Extensions tab for your team and find your private extension.
  3. On the extension details page, select Manage.
  4. Under OAuth, select Configure OAuth.
  5. Fill in the details:
    • Short Description: the name of the OAuth identity provider
    • Scopes: the scopes you want to request from your identity provider
    • Authorization URL: the authorization URL for your identity provider
    • Token URL: the token URL for your identity provider
    • Client ID: the ID of the client application you registered with your identity provider
    • Client Secret: the secret for the client application you registered with your identity provider
  6. Select Save.

You can visit this section again later to edit any of the values you provided.

Now that you’ve completed this step, you can add the OAuth card element to your extension UI.

Add OAuth to your extension UI

Now that you have configured your extension to work with OAuth, you can use the OAuth provider card element to add an OAuth section to your extension UI on the extension details page surface. Users will complete this form to authenticate with your OAuth identity provider when they install and configure your extension for use.

src/ui/surfaces/TeamConfiguration.tsx
import {
  ProviderAuthCard,
  TeamConfigurationSurface,
} from "@netlify/sdk/ui/react/components";


export const TeamConfiguration = () => (
  <TeamConfigurationSurface>
    <ProviderAuthCard />
  </TeamConfigurationSurface>
);

Configure your extension before you add the OAuth card

The OAuth card element won’t render until you have configured your extension to work with your OAuth identity provider. Once you add the configuration, the element will render locally and in previews.

Use the OAuth token in your extension

Now that you have configured your extension to use OAuth, an OAuth token is available to the extension through endpoints.

To access the token, use providerToken on the context.auth object that is provided to all endpoints deployed with your extension. You can use this token to make authenticated requests to your API.

src/endpoints/my-function.ts
import { withNetlifySDKContext } from "@netlify/sdk/ui/functions";


export default withNetlifySDKContext((req, context) => {
  const { providerToken } = context.auth;
  // use the token to make authenticated requests to your API


  return Response.json({ message: "Hello World" });
});

Next steps

After you add the element to your UI and add logic to use the authentication token, make sure to commit and push the update to your repository. This will kick off a new build and deploy of your extension site to ensure the latest version is available when users install the extension.

Learn about best practices for using OAuth with your extension.

Got it!

Your feedback helps us improve our docs.