Skip to main content

Step-by-step guide to develop a social connector

The fastest way to get yourself started is to copy the code from an existing official connector and modify it to fit your needs. Let's take the GitHub connector as an example.

Step 1: Clone an existing connector package​

In a connector source folder, you will find the following files:

  • index.ts: The main entry file of the connector.
  • constant.ts: The constants used in the connector.
  • types.ts: The TypeScript types used in the connector.
  • index.test.ts: The test cases for the connector.
  • mock.ts: The mock data used in the connector test cases.

Besides these files, you will also need to provide a README.md file to describe the connector, a logo.svg (optionally a logo-dark.svg for better dark mode user experience), and a package.json file to define the npm package information.

Step 2: Modify the main entry file (index.ts)​

In the index.ts file, you will find most of the connector logic. There are typically 4 functions you need to implement:

  • getAuthorizationUri: Generate the authorization URI for the third-party social platform. For GitHub, it would be: https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}. Refer to the developer documentation of your target social platform to get the correct URI.
  • authorizationCallbackHandler: Safeguard the returned parameter values in the authorization callback URI, extract the authorization code and handle potential errors.
  • getAccessToken: Exchange the authorization code for an access token.
  • getUserInfo: Fetch user information from the third-party social platform with the access token.

Most of the other common logics have been taken care of in the Logto connector kit, which should make your work easier.

Finally, in the end of the file, you will just need to export the connector object, following the same code structure as the GitHub connector.

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

Step 3: Test the connector​

Unit test​

First, write some unit test cases and make sure the basic functionalities work as expected.

Local test​

  • Setup Logto in your local environment: Logto provides several ways to run locally, you can either use CLI, or docker, or even build from source code. Check out the documentations for more details.
  • Link your custom connector to your Logto instance: Use the CLI to create a symbolic link of your connector to the Logto instance. More details. 
    cd logto
    npx @logto/cli connector link -p .
  • After linking the connector, you should see it in the <logto-root-path>/packages/core/connectors folder.
  • Restart your Logto instance, go to the Logto Admin Console, you should be able to see it in the social connectors list.
  • Configure your connector in Console > Sign-in experience > Sign-up and sign-in > Social sign-in. And try it in our demo app with the "Live preview" feature.