Calagopus

GitHub OAuth Setup ​

This guide walks through setting up GitHub OAuth for your Calagopus Panel.

Prerequisites ​

To set up GitHub OAuth, you need:

Downloading required files ​

Download the github.yml template to import the GitHub provider configuration without entering values manually.

Right-click the link below and save the file locally.

Download github.yml ➚

Import the template config ​

Once github.yml has been downloaded, head to your Calagopus Panel's admin page, and click on OAuth Providers on the side. OAuth Providers tab

Then, click on the Import button and import the github.yml file. Import OAuth Button

Once imported, click on the newly created GitHub provider's ID and you should arrive to a page similar to this: GitHub OAuth page

Copy the Redirect URL provided by the panel and proceed to the next step.

Create your application ​

Open this page or navigate to your GitHub account/organisation settings → Developer Settings → OAuth Apps → New OAuth App.

Once on the page, fill out these values:

  • Application name: Can be anything you want, will be shown on the login page.
  • Homepage URL: Your Calagopus Panel URL (not used by Calagopus).
  • Application description: Optional.
  • Authorization callback URL: Paste your redirect URL generated by the panel at the previous step.
  • Enable Device Flow: Do not tick this checkbox as it will not work with Calagopus.

With the required fields filled out, it should look something similar to this: Example of what could be the setup with fields filled out Once done, you can click on the Register Application button, add a logo if you want, and proceed to the next step.

Generate a client secret ​

Click Generate a new client secret, confirm your identity, then copy both your Client ID and Client Secret - you will need them in the next step.

Configuring the OAuth Provider ​

Back in the panel, enter the Client ID and Client Secret you copied from GitHub.

On the switches below, choose if you want to enable GitHub OAuth, only allow login, allow the user to view the connection and allow the user to link and unlink their accounts.

The template also fills in the Avatar URL Template, so a user's GitHub avatar becomes their panel avatar the first time they log in. Clear that field if you'd rather leave avatars alone, or read Avatars for what it does.

It should normally look like this: GitHub Config

Finally, save your changes.

Test the configuration ​

To test your configuration, head into your account settings, click on OAuth Links at the sidebar, and connect to your GitHub account. Testing GitHub

If everything works correctly, you should now be able to see your GitHub account in your list. List

Troubleshooting ​

SymptomFix
Error: "Redirect URI Mismatch" or "Invalid Redirect URI"The authorization callback URL in GitHub doesn't match the one provided by Calagopus Panel. Go back to your Calagopus Panel OAuth provider configuration page and copy the exact Redirect URL shown, then go to your GitHub OAuth App settings (Account Settings → Developer Settings → OAuth Apps), click your application, update the "Authorization callback URL" field to match exactly (including https://, trailing slashes, etc.), and click Update application.
Error: "Invalid Client Credentials" or "Bad Credentials"The Client ID or Client Secret is incorrect or expired. Go to your GitHub OAuth App settings, copy your Client ID, click Generate a new client secret, copy the new Client Secret immediately (it won't be shown again), then update both values in your Calagopus Panel OAuth provider configuration and save.
OAuth connection doesn't work, with a "device_flow" errorDevice Flow is enabled on your GitHub OAuth App. Go to your GitHub OAuth App settings, make sure the Enable Device Flow checkbox is unchecked, click Update application, and try the OAuth connection again.