Configure OpenID Connect with GitHub

Overview

This guide will walk you through configuring OpenID Connect authentication with GitHub for Discngine Admin Center. Once completed, users will be able to log in using their GitHub credentials.

Important: GitHub users must have a public email address configured to link on email. Alternatively, you can configure linking on username or anonymous linking.

Prerequisites

Before configuring GitHub OpenID Connect, ensure you have:

• Organization Administrator access to Discngine Admin Center
• A GitHub account
• Permissions to create OAuth applications on GitHub

Register a GitHub OAuth Application

Step 1: Access GitHub Settings

1. Log in to GitHub
2. Navigate to Settings (click your profile picture → Settings)
3. In the left sidebar, navigate to Developer settings → OAuth Apps
4. Click Register a new application

Step 2: Configure OAuth Application

Fill in the following fields:

1. Application name: Enter a name (e.g., "Discngine Admin Center")
2. Homepage URL: Enter your organization's homepage (e.g., https://www.yourcompany.com)
3. Application description: (Optional) Add a description
4. Authorization callback URL: Set to: https://account.discngine.cloud/oauth2/callback
5. Click Register application

Step 3: Generate Client Secret

1. Once the application is created, you'll see the Client ID - copy and save it
2. Click Generate a new client secret
3. Copy the Client Secret immediately - you won't be able to see it again

Configure OpenID Connect in Discngine Admin Center

Step 1: Access Identity Providers

1. Log in to Discngine Admin Center as an Organization Administrator
2. Navigate to Settings → Identity Providers
3. Click Add Provider and select OpenID Connect

Step 2: Configure Provider Settings

Fill in the following fields:

Basic Settings:

• Name: GitHub
• Client ID: Enter the Client ID from GitHub
• Client Authentication Method: Select HTTP Basic authentication (client_secret_basic)
• Client Secret: Enter the Client Secret from GitHub

Discovery Settings:

• Discover Endpoints: Disable this option (GitHub doesn't support auto-discovery)

Manual Endpoint Configuration:
Since GitHub doesn't implement a well-known configuration endpoint, you need to enter these endpoints manually:

• Authorization Endpoint: https://github.com/login/oauth/authorize
• Token Endpoint: https://github.com/login/oauth/access_token
• Userinfo Endpoint: https://api.github.com/user

Scopes:

• Scope: user:email

Linking Strategy:

• Select Link on email. Create the user if they do not exist
• Alternative: If users don't have public email addresses, use Link on username or Create an anonymous link

Button Customization:

• Button Text: Login with GitHub (or customize as needed)
• Button Icon: Optionally add a URL to a GitHub icon

Step 3: Configure Advanced Options

Navigate to the Options tab and configure:

• Unique ID Claim: id
• Email Claim: email
• Username Claim: login

These mappings ensure that GitHub user data is correctly mapped to Discngine Admin Center user profiles.

Step 4: Enable for Applications

1. Scroll down to the Applications section
2. Enable the identity provider for your desired applications
3. Toggle Create Registration to automatically register users
4. Click Save

Testing the Configuration

Step 1: Access Login Page

Navigate to https://admin-<organisation-name>.discngine.cloud/

Step 2: Test Login

1. Enter your email address
2. You should see the Login with GitHub button
3. Click the button
4. You will be redirected to GitHub's authorization page
5. Review the permissions being requested
6. Click Authorize to grant access
7. After successful authentication, you'll be redirected back to Discngine Admin Center

Troubleshooting

Common Issues

Email Address Not Available Error
If you see: An email address was not provided for the user. This account cannot be used to login, unable to complete this login request.

Solutions:

1. Option 1: Require users to make their email address public on GitHub
   • Go to GitHub → Settings → Profile → Public email
   • Select an email address from the dropdown
2. Option 2: Change the linking strategy in Discngine Admin Center
   • Use Link on username or Create an anonymous link
   • This works for all users regardless of email privacy settings

Redirect URI Mismatch

• Ensure the callback URL in GitHub exactly matches: https://account.discngine.cloud/oauth2/callback
• Check for typos and ensure there are no trailing slashes

Invalid Client Credentials

• Double-check that you copied the Client ID and Client Secret correctly
• If the secret was lost, generate a new one in GitHub

Scope Issues

• Verify that user:email scope is configured
• Without this scope, email information won't be available

Authorization Declined

• Users must click "Authorize" when prompted by GitHub
• If authorization is declined, they cannot complete the login

Endpoint Configuration

• Ensure all three endpoints are entered correctly without typos
• Verify that "Discover endpoints" is disabled

GitHub Email Privacy

GitHub allows users to keep their email addresses private. Here are the implications:

• Public Email Required: By default, linking on email requires a public email address
• Privacy-Friendly Alternative: Use username-based linking to work with all GitHub privacy settings
• Anonymous Linking: Creates accounts without requiring email verification

Configure the appropriate linking strategy based on your organization's requirements and your users' privacy preferences.

Additional Resources

• GitHub - Creating an OAuth App
• GitHub OAuth Documentation
• GitHub API Documentation

Next Steps

• Return to OpenID Connect Overview