Implementing OAuth Single Sign-On

Setting Up OAuth SSO with GitHub

In this guide, you will learn how to configure OAuth SSO for your Knack Next-Gen App using GitHub as the identity provider.

By the end of this guide, you will have registered an OAuth application in GitHub, configured the necessary provider settings in Knack, and learned how to ensure users' email addresses are shared correctly during login.

---

What You'll Need

• A Knack Next-Gen App with a login page
• A GitHub account
• About 10 minutes

---

Overview of the Setup Process

Setting up GitHub OAuth involves a few back-and-forth steps between Knack and GitHub:

1. Add the OAuth provider in Knack — to get the callback URL you need for GitHub
2. Register an OAuth App in GitHub — to generate your Client ID and Client Secret
3. Configure the OAuth settings in Knack — using the credentials from GitHub and standard GitHub API endpoints
4. Test the configuration — and ensure users have their GitHub email visibility set correctly

---

Step 1: Add the OAuth Provider in Knack

First, create the SSO provider entry in your Knack app. This will give you the callback URL you need to register the app in GitHub.

Start by creating the SSO provider entry in your Knack app. You won't have all the real values yet - that's fine. You'll use placeholders now and update them in Step 6.

👍

We recommend setting up SAML SSO from Settings > User Logins > Login Access and select Add SSO Provider

Go to Settings > User Logins > Login Access and select Add SSO Provider

Or, in the Knack Builder, go to Pages and open the login page where you want to add SSO, go to the Access tab, and select +Add New SSO Provider

1. Click on the login view to open its settings.
2. Click Add SSO Credentials and select OAuth from the Provider Type dropdown.

4. Under Login Button, configure the appearance:

   • Provider Name: A short, display-friendly name for the login button (e.g., GitHub). No spaces allowed, and this cannot be changed after saving.
   • Button Icon: Upload a GitHub logo (optional, 5 MB max).
   • Button Color / Button Font Color: Customize to match your branding or GitHub's brand colors (e.g., #24292F for the button background).

5. Leave the Knack settings window open for now — you will need to copy the Callback URL (which typically looks like https://api.knack.com/v1/oauth/YOUR_APP_ID/consume) into GitHub in the next step.

---

Step 2: Register an OAuth App in GitHub

Now, head over to GitHub to register your Knack app. This tells GitHub that your app is allowed to request user authentication.

1. Log in to your GitHub account.

2. In the upper-right corner of any page, click your profile photo, then click Settings.

1. In the left sidebar, scroll down and click Developer settings.

1. In the left sidebar, click OAuth Apps.

2. Click the New OAuth App button.

1. Fill out the registration form:

   • Application name: Enter a recognizable name for your app (e.g., BrightCare Patient Portal). This is what users will see when they are asked to authorize the login.
   • Homepage URL: Enter the base URL of your Knack Live App (e.g., https://apps.knack.com).
   • Authorization callback URL: Paste the callback URL (https://apps.knack.com/accountslug/appslug)

   

   
   

2. Click Register application.

Once registered, GitHub will take you to the app's settings page. Here, you will find your Client ID.

You will also need to click Generate a new client secret to create your Client Secret. Keep this page open, as you will need both of these values for the next step.

---

Step 3: Configure the OAuth Settings in Knack

Go back to your Knack Builder window to fill in the rest of the Provider Settings. You will use the credentials from GitHub along with standard GitHub API endpoint URLs.

Fill in the Provider Settings fields exactly as follows:

Next, scroll down to the property mapping section. This tells Knack which fields from the GitHub user profile to use when creating or logging in a user.

Note: If you leave the First Name, Last Name, or Email Address properties blank, users will be prompted to enter them manually the first time they log in.

Once all fields are filled out, click Save SSO Provider.

Your GitHub OAuth is now availalable to add to any log in page.

---

Step 4: Testing and the Email Visibility Requirement

Your GitHub OAuth integration is now fully configured! To test it:

1. Open your Knack Live App in an incognito or private browsing window.
2. Navigate to your login page and click the new GitHub SSO button.
3. You will be redirected to GitHub to authorize the application.
4. After authorizing, you should be redirected back to Knack and logged in.

⚠️ Important: The GitHub Email Visibility Requirement

During testing, you might encounter a 401 Unauthorized error or a message saying "No email provided" when trying to log in.

This happens because GitHub allows users to keep their email addresses private. If a user's primary email address is set to private in their GitHub profile, GitHub will not send that email address to Knack during the OAuth flow. Since Knack requires an email address to create or match a user account, the login will fail.

How to fix this: Users who want to log in to your Knack app using GitHub must ensure they have a public email address selected in their GitHub profile.

To change this setting in GitHub:

1. Go to Settings > Public profile.
2. Under the Public email dropdown, select an email address instead of "Select a verified email to display".
3. Save the changes.

You may want to add a brief instruction note above your login button in Knack, advising users to ensure their GitHub email is public before attempting to log in.

---

Field Reference

The table below summarizes every field in the Knack OAuth provider settings panel for quick reference.