Obtain GitHub OAuth Credentials

  • Let’s get the redirect url first from Hanko console, as you’ll need it in a moment. To do so, sign in to Hanko and select your project. Navigate to ‘Settings’ in the left sidebar and then to ‘Identity Providers’. Copy the ‘Redirect URL’ from here.

    Hanko Callback URL
  • Navigate to GitHub and click on your profile photo at the top right corner.

  • Select ‘Settings’ at the bottom of the sidebar menu.

    GitHub settings option
  • Scroll down and select ‘Developer Settings’ in the left sidebar.

    GitHub Developer Settings
  • Choose ‘OAuth Apps’ followed by ‘New OAuth App’. This action opens the registration form. But before it, you need to retrieve the ‘Redirect URL’ from the Hanko cloud.

    GitHub New OAuth App option

    The redirect URL is crucial. It guides GitHub on where to redirect users post-authentication. It’s a blend of Hanko API’s base URL and the /thirdparty/callback endpoint. The exact Hanko API base URL (and hence your redirect URL) hinges on your Hanko setup: whether you use Hanko Cloud or have a self-hosted Hanko API.

  • Get back to OAuth app registration form, fill in the required details, and paste the copied redirect URL into the ‘Application Callback URL’ field. Finish by clicking ‘Register application’.

    GitHub OAuth Registration Form
  • You’ll now see an overview of OAuth app, note down the provided ‘Client ID’. Also, generate a ‘Client Secret’ by selecting ‘Generate a new client secret’. Copy these, as you’ll need them in next step.

    GitHub OAuth Registration Form

Configure GitHub Credentials with Hanko

  • Head back to Identity providers in Hanko and under ‘Identity provider settings’ configure the following:

    Hanko Callback URL
    • Error Redirect URL: This URL, on your frontend, is where the Hanko API redirects if an error occurs during third-party sign-in. With hanko-elements web components, it should link to the page embedding the web component to process errors correctly.

    • Allowed Redirect URL: A URL on your frontend that the Hanko API can redirect to after a successful third-party authentication. Using hanko-elements web components? Make it the URL of the embedding page.

      Supports wildcard matching through globbing:

      • https://*.example.com matches https://foo.example.com and https://bar.example.com.
      • https://foo.example.com/* matches URLs like https://foo.example.com/page1 and https://foo.example.com/page2.
      • Use ** to act as a super-wildcard/match-all.
  • In the ‘Providers’ section, select GitHub and enable its toggle switch.

  • Input the earlier noted ‘Client ID’ and ‘Client Secret’, then click ‘Save’.

    Hanko Callback URL

Implement GitHub Login in Your Frontend Application

Whether you choose to use the pre-designed UI from the @teamhanko/hanko-elements package or opt for a custom UI with the @teamhanko/hanko-frontend-sdk will determine your approach to frontend integration.

  • Integrate the <hanko-auth> component from hanko-elements based on our frontend guides. If everything is good, the component will display a button for signing in with ‘Github’ in login view.

    Make sure to configure the page the web component is embedded on as your error redirect URL as well as an allowed redirect URL.

    Post successful GitHub authentication, the backend sets a session cookie and errors during authentication are displayed within the component accordingly.