Login with GitHub
To enable GitHub login for your project, you need to
- Create a GitHub OAuth application
- Create and add your Google OAuth credentials to your Hanko backend configuration
- Add the Hanko
auth
web component or add the required code to your JS Client App using thehanko-frontend-sdk
.
Access your GitHub account
- Go to github.com.
- Click on 'Sign In' at the top right to log in. If you do not have an account yet, create one.
Create a GitHub Oauth App
Go to the GitHub Developer Settings page:
- Click on your profile photo at the top right
- Click Settings near the bottom of the menu
- In the left sidebar, click Developer settings (near the bottom)
- In the left sidebar, click OAuth Apps
Get your callback URL
Before creating your Oauth app, you need to be aware of the provider callback URL. This is where the third party provider redirects after a successful login. The callback URL consists of the base URL of your running Hanko backend instance and the
/thirdparty/callback
endpoint:https://<your_hanko_backend_instance>/thirdparty/callback
Create a new OAuth application
- On GitHub, click 'Register a new application' or 'New OAuth app' if you created one before.
- Fill in the required information
- In 'Application name', enter the name of your app.
- In 'Homepage URL', enter the full URL to your app (i.e.
https://<your_hanko_backend_instance
) - In 'Authorization callback URL', enter the callback URL of your app (see the previous step).
- Click 'Register application'. You should now see an overview of your OAuth app
- Copy and save the 'Client ID'
- Click 'Generate a new client secret'.
- Copy and save the 'Client secret'
Configure GitHub credentials with your Hanko backend
Open up your backend configuration file add the following:
third_party:
# URL the backend redirects to if an error occurs during third party sign-in. Errors are provided
# as 'error' and 'error_description' query params in the redirect location URL.
#
# When using the Hanko web components it should be the URL of the page that embeds the web component
# such that errors can be processed properly by the web component.
#
# You do not have to add this URL to the 'allowed_redirect_urls', it is automatically included when
# validating redirect URLs.
#
# NOTE: URLs MUST NOT have trailing slash
error_redirect_url: <your_error_redirect_url>
# List of URLS the backend is allowed to redirect to after third party sign-in was successful.
#
# When using the Hanko web components it should be the URL of the page that embeds the
# web component.
#
# Supports wildcard matching through globbing. e.g. https://*.example.com will allow
# https://foo.example.com and https://bar.example.com to be accepted. Globbing is also
# supported for paths, e.g. https://foo.example.com/* will match https://foo.example.com/page1
# and https://foo.example.com/page2.
#
# More on globbing: https://pkg.go.dev/github.com/gobwas/glob#Compile
#
# NOTE: URLs in the list MUST NOT have trailing slash
allowed_redirect_urls:
- <your_redirect_url>
redirect_url: https://<your_hanko_backend_instance>/thirdparty/callback
providers:
github:
enabled: true
client_id: <your_github_client_id>
secret: <your_github_client_secret>
Enable login in your frontend app
With Hanko Elements
Depending on what framework your frontend uses, integrate the auth
web component from the hanko-elements
package
according to one of our frontend guides. If everything was successful, the component should now
render a button to login with GitHub on the login view.
Make sure to configure the page the web component is embedded on as both your error_redirect_url
as well
as an allowed_redirect_url
in your third_party
settings.
On successful authentication with the third party provider, the backend issues a JWT (as a cookie or - if enabled
via backend configuration option
session.enable_auth_token_header
- via X-Auth-Token
header). The web component recognizes this and continues the
usual component flow on success or displays errors that occurred during third party
provider authentication accordingly.
With Hanko Frontend SDK
When building your own UI, you can use the @teamhanko/hanko-frontend-sdk
to initialize third party sign in.
Call hanko.thirdParty.auth
with github
as your provider and the target URL in your app you want to redirect to
after successful third party authentication (must be configured as an allowed redirect url via
third_party.allowed_redirect_urls
).
import { Hanko } from "@teamhanko/hanko-frontend-sdk"
const hanko = new Hanko("<your_hanko_backend_instance>")
async function signInWithGitHub() {
try {
await hanko.thirdParty.auth("github", "<your_redirect_url>");
} catch (error) {
// handle error
}
}
On successful authentication with the third party provider, the backend issues a JWT (as a cookie or - if enabled
via backend configuration option
session.enable_auth_token_header
- via X-Auth-Token
header) and redirects to the
target URL provided in the hanko.thirdParty.auth
call.