1

Obtain GitHub OAuth credentials

  • First, obtain the redirect URL from Hanko Console, as you’ll need it for GitHub configuration. 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 opens the registration form for creating your OAuth application. 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.
  • Return to the OAuth app registration form, fill in the required details, and paste the copied redirect URL into the ‘Application Callback URL’ field. Complete the registration by clicking ‘Register application’. GitHub OAuth registration form
  • You’ll now see an overview of your OAuth app. Note down the provided ‘Client ID’. Generate a ‘Client Secret’ by selecting ‘Generate a new client secret’. Copy both values, as you’ll need them in the next step. GitHub OAuth registration form
2

Configure GitHub credentials with Hanko

  • Return 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
3

Implement Sign in with GitHub 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.