Using Keycloak Identity Brokering to Add GitHub Social Login

Introduction

In this article, we demonstrate how to use GitHub as an external Identity Provider (IdP) and authenticate users in your application through Skycloak, a managed Keycloak service hosted in the cloud.

Using Skycloak allows organizations to harness the powerful features of the open-source Keycloak IAM product while avoiding the challenges of installing, maintaining, and scaling Keycloak for production-grade environments — all in a cost-effective way.

Using Identity Brokering allows you to delegate authentication to external providers such as GitHub without adding OAuth logic into your application code. Keycloak acts as the broker, your application remains the relying party, and GitHub becomes the authentication source.

This article focuses on using GitHub as a social identity provider using the OpenID Connect protocol.

Overview

Authentication flow:

Below is the high-level sequence when a user logs in through GitHub via Skycloak:

1. The user accesses your application.
2. Your application redirects the user to Keycloak (Skycloak) for authentication.
3. On the Keycloak login screen, the user selects “GitHub”.
4. Keycloak (acting as an OIDC client) redirects the user to GitHub for login.
5. The user authenticates at GitHub.
6. GitHub redirects back to Keycloak with an authorization code.
7. Keycloak exchanges the code for an access token from GitHub.
8. Keycloak fetches the user’s GitHub profile.
9. Keycloak creates (or updates) a local user identity.
10. Keycloak completes login and redirects the user back to your application with an ID token and/or access token for OIDC client.

This process allows your application to rely only on Keycloak, while GitHub handles password authentication.

For more details on Identity Provider, please refer Social Identity Providers session at the Keycloak server admin guide.

Configuration Steps

Summary of Steps

1. Create or identify your Keycloak client application. (OIDC or SAML applications are supported.)
2. Register a new OAuth App in GitHub
3. Configure GitHub as an Identity Provider in Keycloak
4. Test the authentication flow.

Note:

This article assumes your client application is already configured in Keycloak.
For quick testing, you can use the Keycloak Account Console URL.

Step 1. Register an OAuth App in GitHub

1. Log in to your GitHub account and go to
   Settings -> Developer Settings -> OAuth Apps
2. Click New OAuth App fill in the details:’
   • Application Name: skycloak-github-idp (or any suitable name)
   • Homepage URL: https://your-skycloak-domain
   • Authorization call-back URL: https://your-skycloak-domain/realms/<your_realm>/broker/github/endpoint
3. Click Register Application, then copy the following since they have to be specified at Keycloak:
   • Client ID
   • Client Secret

Step 2. Configure GitHub as an Identity Provider in Keycloak

1. Log in to the Keycloak Admin Console.
2. Select your realm (e.g., acme).
3. Navigate to:
   Identity Providers -> Add provider -> GitHub
4. Enter the following details:
   • Client ID: (from GitHub)’
   • Client Secret: (from GitHub)
5. Click Save.

Keycloak will automatically fetch GitHub’s OIDC endpoints from GitHub’s discovery document.

Step 3. Configure OIDC client at Keycloak

(If you already have a Keycloak client configured, you can skip this step.)

You can test GitHub identity brokering using the built-in Account Console:

https://<skycloak_hostname>/realms/<realm_name>/account

Otherwise, configure your own OIDC or SAML application in Keycloak as the final relying party.

Step 4. Test the integration

1. Access your application or the Keycloak Account Console.
2. You will be redirected to the Skycloak login page.
3. You should now see a “GitHub” login option.
4. Click GitHub.
5. You will be redirected to GitHub’s login page (if not already logged in).
   • Enter your GitHub username/password
   • Or authorize the application if GitHub prompts for consent
6. After authentication, GitHub redirects back to Keycloak with an authorization code.
7. Keycloak exchanges the code for user profile information and creates a local user (if first login)
8. Authentication completes, and you are redirected back to your application.
9. Keycloak completes login and redirects you back to your application (or the account console).

This verifies that GitHub identity brokering has been successfully set up.

Summary

In this article, we implemented Identity Brokering using Skycloak, the managed Keycloak IAM platform.
By integrating GitHub as an external Identity Provider, you can deliver seamless social login without embedding Github’s OAuth logic directly into your application’s codebase.

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more.