Generic OAuth Setup

This guide covers setting up a generic OIDC OAuth provider for your Calagopus Panel. It first explains how to locate the required identifiers from your provider, then walks through the integration configuration.

Example files

These are example files made by the community that you can use as a preset. You will need to replace id.example.com with your own OIDC provider.
Pocket-ID: Download pocket-id.yml ➚
Authentik: Download authentik.yml ➚

If your provider isn't listed here, you may have to follow the steps below to adapt to your setup.

Find the required identifiers

Most OIDC providers (hosted or self-hosted) expose a standard "well-known" URL. Depending on your provider, it is typically available at /.well-known/openid-configuration and returns a JSON object containing the 3 URLs needed below.

For example, if your provider's URL is https://id.example.com, add /.well-known/openid-configuration at the end, so you would go to https://id.example.com/.well-known/openid-configuration.

WARNING

If that file does not exist, you may need to refer to your provider's documentation to find the 3 URLs needed.

Visit the well-known URL in a browser (e.g. https://id.example.com/.well-known/openid-configuration) and note the following 3 values:

Identifier	JSON Key
Auth URL	authorization_endpoint
Token URL	token_endpoint
Info URL	userinfo_endpoint

On the same JSON object, look for the claims_supported key, and find the claims you need. Below are some JSON path examples that you could use, although you may need to tweak them a little for your specific provider.

Identifier	Example	Required
Identifier Path	$.sub	✅
Email Path	$.email	❌
Username Path	$.preferred_username	❌
First Name Path	$.given_name	❌
Last Name Path	$.family_name	❌

Finally, look for the scopes_supported key, and find the scopes you need. Usually, you should only put openid, profile and email, but it may depend on your provider.

Then, on your provider, set up a Client ID and Client Secret for Calagopus to use.

Configuring the OAuth Provider

Once you have your URLs, your claims and your scopes, head to your Calagopus Panel's admin page, and click on OAuth Providers on the side.

Then, click on the Create button and you should arrive to a page similar to this:

On that page, fill out these fields according to the guide below. It will explain what each field represents and give you some examples for Download pocket-id.yml ➚.

General Information

Name

The name of your provider, displayed on the user's OAuth list.

Required: ✅
Example: Pocket-ID

Description

A description of your provider, useful for organization.

Required: ❌

OAuth Provider Config

Client ID

This is your Client ID that your provider has given you.

Required: ✅

Client Secret

This is your Client Secret that your provider has given you.

Required: ✅

OAuth URLs

Auth URL

This is the Authentication URL that you have grabbed from the authorization_endpoint JSON key.

Required: ✅
Example: https://id.example.com/authorize

Token URL

This is the Token URL that you have grabbed from the token_endpoint JSON key.

Required: ✅
Example: https://id.example.com/api/oidc/token

Info URL

This is the User Info URL that you have grabbed from the userinfo_endpoint JSON key.

Required: ✅
Example: https://id.example.com/api/oidc/userinfo

Basic Auth

Enable this if your provider transmits the Client ID and Client Secret via HTTP Basic Authentication. Do not enable this option unless you know what you are doing.

Required: ❌
Example: Off

Scopes and Paths

For all the paths, make sure to also add $. at the beginning, for example if your email path is email, you would do: $.email.

Scopes

The scopes used to get the user data via OIDC.

Required: ❌ (technically optional per panel validation, but required in practice to extract email, username, first name, last name, and potentially the identifier).
Example: openid, email, profile

Identifier Path

The Path to use to extract the unique user identifier from the Info URL response (https://serdejsonpath.live)

Required: ✅
Example: $.sub

Email Path

The Path to use to extract the email from the Info URL response (https://serdejsonpath.live)

Required: ❌
Example: $.email

Username Path

The Path to use to extract the username from the Info URL response (https://serdejsonpath.live)

Required: ❌
Example: $.preferred_username

First Name Path

The Path to use to extract the first name from the Info URL response (https://serdejsonpath.live)

Required: ❌
Example: $.given_name

Last Name Path

The Path to use to extract the last name from the Info URL response (https://serdejsonpath.live)

Required: ❌
Example: $.family_name

Options

Enabled

Enable this if you want users to be able to access the panel via the custom provider.

Only allow Login

Enable this if you don't want people registering accounts via your OIDC provider.

Link Viewable to User

Allows the User to see the Connection and its identifier in the Client UI.

Link Manageable by User

Allows the User to connect and disconnect with this provider

---

Click Save and your custom OIDC provider will be set up.

Test the configuration

To test your configuration, head into your account settings, click OAuth Links in the sidebar, and connect your OIDC provider account. If everything works correctly, the provider will appear in your linked accounts list.

Troubleshooting

Error: "Redirect URI Mismatch" or "Invalid Redirect URI"

Cause: The redirect URL in your OIDC provider doesn't match the one provided by Calagopus Panel.

Solution:

1. Go back to your Calagopus Panel OAuth provider configuration page
2. Copy the exact Redirect URL shown
3. Go to your OIDC provider's configuration
4. Update the redirect/callback URL to match exactly (including https://, trailing slashes, etc.)
5. Save the changes in your OIDC provider

Error: "Invalid URLs" or connection fails immediately

Cause: One or more of the OAuth URLs (Auth URL, Token URL, Info URL) are incorrect.

Solution:

1. Visit your OIDC provider's well-known URL: https://your-provider/.well-known/openid-configuration
2. Verify the following values match:
   • Auth URL matches authorization_endpoint
   • Token URL matches token_endpoint
   • Info URL matches userinfo_endpoint
3. Update the URLs in your Calagopus Panel OAuth provider configuration
4. Save the changes

Error: "Failed to extract user data" or missing user information

Cause: The JSON paths for extracting user data are incorrect.

Solution:

1. Check your OIDC provider's userinfo_endpoint response format
2. Visit https://serdejsonpath.live to test your JSON paths
3. Verify each path:
   • Identifier Path (required) - usually $.sub
   • Email Path - usually $.email
   • Username Path - usually $.preferred_username or $.username
   • First Name Path - usually $.given_name
   • Last Name Path - usually $.family_name
4. Update the paths in your Calagopus Panel configuration
5. Save the changes

Error: "Invalid Scope" or "Insufficient Scopes"

Cause: The requested scopes are not supported by your OIDC provider or are incorrectly configured.

Solution:

1. Visit your OIDC provider's well-known URL: https://your-provider/.well-known/openid-configuration
2. Check the scopes_supported array
3. Ensure your configuration includes the necessary scopes (typically openid, profile, email)
4. Update the scopes in your Calagopus Panel OAuth provider configuration
5. Save the changes

Error: "Invalid Client" or "Authentication Failed"

Cause: Client ID, Client Secret, or Basic Auth configuration is incorrect.

Solution:

1. Verify your Client ID and Client Secret from your OIDC provider
2. Update both values in your Calagopus Panel configuration
3. Check if your provider requires HTTP Basic Authentication:
   • If yes, enable the Basic Auth option
   • If no, ensure Basic Auth is disabled
4. Save the changes

OAuth connection button doesn't appear

Cause: The OAuth provider is not enabled in the panel.

Solution:

1. Go to your Calagopus Panel admin page
2. Navigate to OAuth Providers
3. Click on your custom provider
4. Ensure the Enabled switch is turned on
5. Save the changes

Error: "Access Denied" after clicking authorize

Cause: User denied permission or OIDC provider account has issues.

Solution:

1. Try the authorization process again
2. Ensure you click the authorization/consent button on your provider's page
3. Verify your account with the OIDC provider is active and verified
4. Check if your OIDC provider requires additional configuration or permissions