OAuth Authentication

Pro knot supports OAuth authentication through external identity providers, allowing users to sign in with their existing GitHub, GitLab, Google, or Auth0 accounts — or any OpenID Connect compatible provider.

OAuth providers are configured in knot.toml using the [[server.auth_providers]] TOML array-of-tables. Multiple providers can be enabled simultaneously.

Supported Providers

Prerequisites

• A valid knot Pro license
• OAuth application credentials from your chosen provider(s)
• Your knot server must be accessible at a public or internal URL (configured via server.url)

GitHub Setup

1. Create a GitHub OAuth App

1. Go to Settings > Developer settings > OAuth Apps > New OAuth App (or visit github.com/settings/developers).
2. Fill in the application details:
   • Application name — A descriptive name (e.g., “Knot”)
   • Homepage URL — Your knot server URL (e.g., https://knot.example.com)
   • Authorization callback URL — {your-knot-url}/auth/github/callback (e.g., https://knot.example.com/auth/github/callback)
3. Click Register application.
4. Note the Client ID.
5. Click Generate a new client secret and note the value (it is only shown once).

2. Configure knot

Add the following to your knot.toml:

[[server.auth_providers]]
provider = "github"
client_id = "your-github-client-id"
client_secret = "your-github-client-secret"

Restart knot to apply the configuration.

GitHub is currently integrated using a GitHub OAuth App. GitHub OAuth Apps return an access token, but do not provide refresh tokens in this flow. GitHub refresh tokens are available with GitHub Apps using expiring user-to-server tokens, which is a different integration model.

GitLab Setup

1. Create a GitLab Application

1. Go to Preferences > Applications (or visit gitlab.com/-/user_settings/applications).
2. Fill in the application details:
   • Name — A descriptive name (e.g., “Knot”)
   • Redirect URI — {your-knot-url}/auth/gitlab/callback (e.g., https://knot.example.com/auth/gitlab/callback)
   • Scopes — Select read_user
3. Click Save application.
4. Note the Application ID and Secret.

2. Configure knot

Add the following to your knot.toml:

[[server.auth_providers]]
provider = "gitlab"
client_id = "your-gitlab-application-id"
client_secret = "your-gitlab-secret"

Restart knot to apply the configuration.

Self-Hosted GitLab

To use a self-hosted GitLab instance, set the base_url field to your GitLab server URL:

[[server.auth_providers]]
provider = "gitlab"
base_url = "https://gitlab.example.com"
client_id = "your-gitlab-application-id"
client_secret = "your-gitlab-secret"

When base_url is set, all OAuth and API requests are directed to your self-hosted instance instead of gitlab.com.

Google Setup

1. Create a Google OAuth Client

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Navigate to APIs & Services > Credentials.
4. Click Create Credentials > OAuth client ID.
5. Configure the consent screen if prompted.
6. Set the application type to Web application.
7. Add an Authorized redirect URI: {your-knot-url}/auth/google/callback (e.g., https://knot.example.com/auth/google/callback)
8. Click Create and note the Client ID and Client Secret.

2. Configure knot

Add the following to your knot.toml:

[[server.auth_providers]]
provider = "google"
client_id = "your-google-client-id.apps.googleusercontent.com"
client_secret = "your-google-client-secret"

Restart knot to apply the configuration.

knot requests offline access for Google automatically so refresh tokens can be issued. Google may only return a refresh token the first time the user consents, or after the app has been revoked and consent is granted again.

Auth0 Setup

1. Create an Auth0 Application

1. Go to the Auth0 Dashboard and select your tenant.
2. Navigate to Applications > Applications > Create Application.
3. Choose Regular Web Application and click Create.
4. Go to the Settings tab and note the Domain (e.g., your-tenant.us.auth0.com), Client ID, and Client Secret.
5. In Allowed Callback URLs, add: {your-knot-url}/auth/auth0/callback (e.g., https://knot.example.com/auth/auth0/callback)
6. In Allowed Logout URLs, add: {your-knot-url} (e.g., https://knot.example.com)
7. Click Save Changes.
8. Enable refresh token issuance for the application if your tenant requires it.

2. Configure knot

Add the following to your knot.toml:

[[server.auth_providers]]
provider = "auth0"
base_url = "https://your-tenant.us.auth0.com"
client_id = "your-auth0-client-id"
client_secret = "your-auth0-client-secret"

The base_url is your Auth0 tenant domain. It can be the Auth0 domain (e.g., your-tenant.us.auth0.com) or a custom domain.

Restart knot to apply the configuration.

knot requests the offline_access scope for Auth0 automatically so refresh tokens can be issued.

Generic OIDC Setup

The generic OIDC provider supports any OpenID Connect compatible identity provider (Okta, Keycloak, Azure AD, Dex, and others). It uses OIDC discovery to automatically configure endpoints.

Multiple OIDC providers can be configured by adding separate [[server.auth_providers]] entries with different name values.

1. Configure your Identity Provider

Create an OAuth 2.0 / OpenID Connect client in your identity provider with:

• Redirect URI — {your-knot-url}/auth/{name}/callback where {name} is the name you configure below (e.g., https://knot.example.com/auth/okta/callback)
• Scopes — openid, profile, email
• Refresh tokens — add offline_access if your identity provider requires it for refresh token issuance
• Response type — code (Authorization Code flow)

Note the Client ID, Client Secret, and the discovery URL (typically https://your-idp.example.com/.well-known/openid-configuration).

2. Configure knot

Add the following to your knot.toml:

[[server.auth_providers]]
provider = "oidc"
name = "okta"
display_name = "Okta"
discovery_url = "https://your-idp.example.com/.well-known/openid-configuration"
client_id = "your-oidc-client-id"
client_secret = "your-oidc-client-secret"
scopes = ["openid", "profile", "email", "offline_access"]

The name field is a unique slug used in URLs (e.g., /auth/okta/callback). The display_name is shown in the UI and is optional — it defaults to the capitalized name.

On startup, knot fetches the discovery document to configure the authorization, token, and userinfo endpoints automatically.

Restart knot to apply the configuration.

Example: Multiple OIDC Providers

[[server.auth_providers]]
provider = "oidc"
name = "okta"
display_name = "Okta"
discovery_url = "https://your-org.okta.com/.well-known/openid-configuration"
client_id = "okta-client-id"
client_secret = "okta-client-secret"
allowed_domains = ["yourcompany.com"]

[[server.auth_providers]]
provider = "oidc"
name = "keycloak"
display_name = "Keycloak"
discovery_url = "https://keycloak.example.com/realms/your-realm/.well-known/openid-configuration"
client_id = "knot-client"
client_secret = "keycloak-secret"

Full Configuration Reference

Each provider is defined as a [[server.auth_providers]] entry with the following fields:

Example: Multiple Providers with Auto-Provisioning

[[server.auth_providers]]
provider = "github"
client_id = "Iv1.example123"
client_secret = "ghp_example_secret"
auto_create_users = true
default_roles = ["User"]
default_groups = ["Developers"]

[[server.auth_providers]]
provider = "gitlab"
client_id = "your-gitlab-application-id"
client_secret = "your-gitlab-secret"
# base_url = "https://gitlab.example.com"  # Self-hosted GitLab
auto_create_users = true
default_roles = ["User"]
default_groups = ["Developers"]

[[server.auth_providers]]
provider = "google"
client_id = "123456789.example.apps.googleusercontent.com"
client_secret = "GOCSPX-example_secret"
allowed_domains = ["yourcompany.com"]
auto_create_users = true
default_roles = ["User"]
default_groups = ["Developers"]

[[server.auth_providers]]
provider = "auth0"
base_url = "https://your-tenant.us.auth0.com"
client_id = "your-auth0-client-id"
client_secret = "your-auth0-client-secret"
auto_create_users = true
default_roles = ["User"]
default_groups = ["Developers"]

[[server.auth_providers]]
provider = "oidc"
name = "keycloak"
display_name = "Keycloak"
discovery_url = "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration"
client_id = "knot-client"
client_secret = "your-keycloak-secret"
scopes = ["openid", "profile", "email", "offline_access"]
auto_create_users = true
default_roles = ["User"]
default_groups = ["Developers"]

User Experience

When OAuth providers are configured:

• Sign-in buttons for each enabled provider appear on the knot login page alongside the standard email/password form.
• On first login via OAuth, knot either matches the user by email address or creates a new account (if auto_create_users is enabled).
• Users can link and unlink OAuth providers from their profile settings.
• Users created via OAuth are prompted to set a password for CLI access.
• When a provider returns a refresh token, knot stores it encrypted alongside the linked provider so future token refresh flows can be supported cleanly.
• GitHub is the exception in the current implementation because the built-in GitHub provider uses a GitHub OAuth App flow rather than a GitHub App user-token flow.

Domain Restrictions

When allowed_domains is set, only users with an email address matching one of the listed domains can authenticate. For GitHub, this checks the user’s primary verified email. For GitLab, it checks the email returned by the user API. For Google, Auth0, and OIDC providers, it checks the email returned by the userinfo endpoint.

Callback URLs

The OAuth callback URLs follow a consistent pattern based on your configured server.url:

Ensure these URLs are registered as authorized redirect URIs in your provider’s application settings.