oidcboot

package
v1.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package oidcboot holds the refusal rules that decide whether an OIDC provider environment can boot.

Why this is a leaf package rather than a helper inside modules/oidc: two independent places need the same answer, and they cannot import each other.

  • modules/oidc.LoadConfig needs it to refuse startup with a specific error.
  • modules/common.isOIDCFullyConfigured needs it to avoid reporting a configuration as usable when the module it configures cannot start.

modules/oidc transitively imports modules/common, so the dependency can only run one way — which is how the second place ended up as a hand-maintained mirror of the first. That mirror then drifted, and the drift has a disproportionate blast radius:

a typo in the provider kind
  -> LoadConfig errors, the module registers 404 handlers for every endpoint
  -> but the mirror still answers "fully configured"
  -> so anyThirdPartyLoginConfigured stays true and login.local_off=1 is honoured
  -> password login also stays off
  -> an SSO-only deployment has no working login path at all, and the only
     recovery is a redeploy.

Keeping the rules here means there is one copy. That sentence was an overstatement for several rounds — the boolean parser, the base-URL fallback, the alias resolution, the two logout-URL checks and the issuer length bound each lived outside it and each produced the same lockout when the two readers disagreed. They are all here now, and SharedEnvKeys generates the pin scenarios so a new key cannot be added without both directions covered. RefusedScenarios additionally pins the tests on both sides to the same table, so a future provider kind cannot re-open the gap by being added in only one of them.

The package deliberately depends on nothing outside the standard library.

Index

Constants

View Source
const (
	KindOIDC   = "oidc"
	KindOAuth2 = "oauth2"
)

Supported provider kinds.

View Source
const AppIDDescription = "alphanumeric first character, then letters/digits/underscore/hyphen, max 64 characters"

AppIDDescription is the human-readable form of the rule, for error messages. Callers must not need the regexp object itself.

View Source
const IssuerMaxLen = 255

IssuerMaxLen is the width of user_oidc_identity.issuer (VARCHAR(255)), compared in bytes — intentionally conservative, see the subject bound's note.

It lives here because both readers need it. newOAuth2Provider refuses an over-long issuer at construction, which leaves cfg.Enabled true and provider nil: real routes mount and every login entry point answers 500, while a settings helper that does not know the rule reports "configured", `login.local_off` stays honoured, and an SSO-only deployment cannot mint a session at all. That is the fifth field on which this exact asymmetry has appeared.

View Source
const LogoutPathPrefix = "public/sp/slo"

LogoutPathPrefix is the fixed path prefix of the plain-OAuth2 upstream's single-logout endpoint; the app id is appended as the final path segment.

Variables

View Source
var AcceptedScenarios = []AcceptedScenario{
	{Name: "default kind", Env: map[string]string{}},
	{Name: "explicit oidc", Env: map[string]string{"OCTO_OIDC_PROVIDER_KIND": "oidc"}},
	{Name: "oauth2 with base url", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
		"OCTO_OIDC_PROVIDER_BASE_URL": "https://idp.example.com",
	}},
	{Name: "oauth2 falling back to the issuer as base url", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_KIND": "oauth2",
	}},

	{Name: "standard kind with a whitespace-only base URL", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_BASE_URL": "   ",
	}},
	{Name: "oauth2 with app id and post-logout redirect", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_KIND":            "oauth2",
		"OCTO_OIDC_PROVIDER_APP_ID":          "app1",
		"OCTO_OIDC_POST_LOGOUT_REDIRECT_URI": "https://app.example.com/login",
	}},

	{Name: "oauth2 with a whitespace-only base URL and a usable issuer", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
		"OCTO_OIDC_PROVIDER_BASE_URL": "   ",
	}},
	{Name: "standard kind with a whitespace-only app id", Env: map[string]string{
		"OCTO_OIDC_PROVIDER_APP_ID": " \t ",
	}},
}

AcceptedScenarios pins the **accepting** direction of the agreement.

RefusedScenarios only pins one half: "if the module refuses to boot, the settings helper must not report configured". The other half matters just as much, and it was the one that broke: the rules were unified but the input normalisation was not, so a whitespace-only BASE_URL made the module refuse to boot while the helper reported configured — every OIDC route a 404, `login.local_off` still honoured, no login path left. RefusedScenarios could not express that, because after the fix the correct verdict for that input is *accept* on both sides, not refuse on both.

Both consumers' pin tests walk this table. It replaces a local copy that each side maintained separately — the accepting direction was already tested, just not against a shared list, which is why the divergence had somewhere to hide.

View Source
var ErrUnknownKind = errors.New("oidcboot: unknown provider kind")

ErrUnknownKind is returned for a provider kind this build does not implement.

View Source
var RefusedScenarios = []RefusedScenario{
	{
		Name:  "unknown kind (typo)",
		Input: KindInput{Kind: "oauth22", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND": "oauth22",
		},
		ExpectKeyInError: "oauth22",
	},
	{
		Name: "oauth2 with a plaintext base url and no escape hatch",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "http://idp.example.com",
			RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL": "http://idp.example.com",
		},
		ExpectKeyInError: "https",
	},
	{
		Name: "oauth2 with a non-absolute base url",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "idp.example.com",
			RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL": "idp.example.com",
		},
		ExpectKeyInError: "absolute",
	},
	{
		Name: "oauth2 with an end-session override that cannot take effect",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			EndSessionURL: "https://idp.example.com/logout", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":            "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL":        "https://idp.example.com",
			"OCTO_OIDC_PROVIDER_END_SESSION_URL": "https://idp.example.com/logout",
		},
		ExpectKeyInError: "END_SESSION_URL",
	},
	{
		Name: "oauth2 with a path-traversing app id",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			AppID: "../../evil", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL": "https://idp.example.com",
			"OCTO_OIDC_PROVIDER_APP_ID":   "../../evil",
		},
		ExpectKeyInError: "APP_ID",
	},
	{

		Name: "oauth2 with an app id starting with an underscore",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			AppID: "_tenant", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL": "https://idp.example.com",
			"OCTO_OIDC_PROVIDER_APP_ID":   "_tenant",
		},
		ExpectKeyInError: "APP_ID",
	},
	{
		Name: "oauth2 with an app id over the length cap",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			AppID: strings.Repeat("a", 65), RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL": "https://idp.example.com",
			"OCTO_OIDC_PROVIDER_APP_ID":   strings.Repeat("a", 65),
		},
		ExpectKeyInError: "APP_ID",
	},
	{

		Name: "relative post-logout redirect URI",
		Input: KindInput{Kind: KindOIDC, PostLogoutRedirectURI: "/login",
			AutoLinkByEmail: true, RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_POST_LOGOUT_REDIRECT_URI": "/login",
		},
		ExpectKeyInError: "POST_LOGOUT_REDIRECT_URI",
	},
	{
		Name: "plain-http end-session URL without the insecure opt-in",
		Input: KindInput{Kind: KindOIDC, EndSessionURL: "http://idp.example.com/logout",
			AutoLinkByEmail: true, RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_END_SESSION_URL": "http://idp.example.com/logout",
		},
		ExpectKeyInError: "END_SESSION_URL",
	},
	{

		Name: "oauth2 with a malformed primary flag contradicted by its legacy alias",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			AutoLinkByEmail: true, RequireEmailVerified: false},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":                 "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL":             "https://idp.example.com",
			"DM_OIDC_PROVIDER_AUTO_LINK_BY_EMAIL":     "true",
			"DM_OIDC_PROVIDER_REQUIRE_EMAIL_VERIFIED": "not-a-bool",
			"DM_OIDC_AEGIS_REQUIRE_EMAIL_VERIFIED":    "false",
		},
		ExpectKeyInError: "REQUIRE_EMAIL_VERIFIED",
	},
	{
		Name: "oauth2 with a post-logout redirect but no app id",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			PostLogoutRedirectURI: "https://app.example.com/login", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":            "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL":        "https://idp.example.com",
			"OCTO_OIDC_POST_LOGOUT_REDIRECT_URI": "https://app.example.com/login",
		},
		ExpectKeyInError: "APP_ID",
	},
	{
		Name: "oauth2 with autolink on and verification not required",
		Input: KindInput{Kind: KindOAuth2, BaseURL: "https://idp.example.com",
			AutoLinkByEmail: true, RequireEmailVerified: false},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":                 "oauth2",
			"OCTO_OIDC_PROVIDER_BASE_URL":             "https://idp.example.com",
			"DM_OIDC_PROVIDER_AUTO_LINK_BY_EMAIL":     "true",
			"DM_OIDC_PROVIDER_REQUIRE_EMAIL_VERIFIED": "false",
		},
		ExpectKeyInError: "AUTO_LINK_BY_EMAIL",
	},
	{
		Name: "oidc kind with a base url that would be ignored",
		Input: KindInput{Kind: KindOIDC, BaseURL: "https://idp.example.com",
			RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":     "oidc",
			"OCTO_OIDC_PROVIDER_BASE_URL": "https://idp.example.com",
		},
		ExpectKeyInError: "BASE_URL",
	},
	{
		Name:  "oidc kind with an app id that would be ignored",
		Input: KindInput{Kind: KindOIDC, AppID: "app1", RequireEmailVerified: true},
		Env: map[string]string{
			"OCTO_OIDC_PROVIDER_KIND":   "oidc",
			"OCTO_OIDC_PROVIDER_APP_ID": "app1",
		},
		ExpectKeyInError: "APP_ID",
	},
}

RefusedScenarios is the shared table both sides' tests iterate.

Adding a provider kind means adding its refusal cases here once; the tests in modules/oidc and modules/common then both pick them up, which is what stops the two from drifting again.

View Source
var SharedEnvKeys = []struct {
	Primary, Alias string
	// Fallback is a legal value of the right shape, used to build the accepted case
	// (whitespace primary + real value elsewhere). Empty means the key has no alias and
	// only the refused direction is generated.
	Fallback string
	// WhitespaceIsFatal is true when a whitespace-only value with no fallback makes the
	// module refuse to boot. False means the module falls back to a default, so the
	// generated scenario belongs in the accepted table instead.
	WhitespaceIsFatal bool
}{
	{Primary: "DM_OIDC_PROVIDER_ISSUER", Alias: "DM_OIDC_AEGIS_ISSUER",
		Fallback: "https://legacy-issuer.example.com", WhitespaceIsFatal: true},
	{Primary: "DM_OIDC_PROVIDER_CLIENT_ID", Alias: "DM_OIDC_AEGIS_CLIENT_ID",
		Fallback: "legacy-cid", WhitespaceIsFatal: true},
	{Primary: "DM_OIDC_PROVIDER_CLIENT_SECRET", Alias: "DM_OIDC_AEGIS_CLIENT_SECRET",
		Fallback: "legacy-secret", WhitespaceIsFatal: true},
	{Primary: "DM_OIDC_PROVIDER_REDIRECT_URI", Alias: "DM_OIDC_AEGIS_REDIRECT_URI",
		Fallback: "https://legacy-app.example.com/callback", WhitespaceIsFatal: true},

	{Primary: "OCTO_OIDC_PROVIDER_KIND"},
	{Primary: "DM_OIDC_PROVIDER_ID"},
	{Primary: "OCTO_OIDC_PROVIDER_BASE_URL"},
	{Primary: "OCTO_OIDC_PROVIDER_APP_ID"},
}

SharedEnvKeys is every environment key both config readers consult, with the legacy alias where one exists and a value of the right shape for the fallback case.

**Declared once, with the scenario tables generated from it.** The whitespace-divergence class has now appeared on six separate fields — base URL, a boolean, the issuer, the required-key loop, the provider kind, and the provider id — and every single time the cause was the same: the shared table happened not to list that one field. Enumerating the credential fields only was the mistake; the axis is "every key either reader reads".

Adding a key here pins both directions automatically. That is the point.

Functions

func EnvBool

func EnvBool(primary, alias string, def bool) bool

EnvBool reads a boolean env var with an optional legacy alias.

**This is the only definition.** Two copies existed — one in the module's own config loader, one in the settings helper that decides whether a login method counts as configured — with a comment on the second claiming it matched the first. It did not: on a value that is present but unparseable, one fell through to the legacy alias and the other returned the default.

That single disagreement is enough to remove every login path. With `kind=oauth2`, `AUTO_LINK_BY_EMAIL=true`, a malformed `REQUIRE_EMAIL_VERIFIED` and a legacy alias saying `false`, the module refuses to boot (all endpoints 404) while the helper reports "configured" — so `login.local_off` stays honoured and an SSO-only deployment has nothing left to log in with, recoverable only by redeploy.

Fall-through on an unparseable primary is the deliberate semantic: during a key migration a typo in the new key must not swallow a still-valid old key.

func EnvString

func EnvString(primary, alias string) string

EnvString reads a string env var with an optional legacy alias.

**Single definition.** Two copies existed and differed in one detail: one tested the primary **untrimmed** (`v != ""`), so a whitespace-only value counted as configured and the alias was never consulted; the other trimmed first and fell through to the alias. Under kind=oauth2 the issuer doubles as the base URL, so that single difference made the module refuse to boot while the settings helper reported "configured" — the same total lockout as the BASE_URL and boolean cases, on a third field.

A value that is only whitespace is not a configured value. Trim, then decide.

func UpstreamBaseURL

func UpstreamBaseURL(kind, baseURL, issuer string) string

UpstreamBaseURL resolves the base URL that will actually be used.

**Single definition of the fallback.** Under KindOAuth2 the issuer doubles as the site root, so an unset base URL falls back to it. Both config readers must make this decision identically, and they did not: the module tested the **untrimmed** value (`p.BaseURL == ""`) while the settings helper trimmed first. A whitespace-only base URL therefore made the module refuse to boot -- every OIDC route a 404 -- while the helper took the fallback, reported "configured", and left `login.local_off` honoured: an SSO-only deployment with no way to log in and no recovery short of a redeploy.

Normalising inside ValidateKind was not enough, because this decision runs **before** it. That is why the fallback itself has to live here.

func ValidAppID

func ValidAppID(appID string) bool

AppIDPattern limits the app id to URL-safe characters, must start alphanumeric, and caps the length at 64.

The value is interpolated into a URL path segment, so something like "../x" would silently point the logout request at a different endpoint. Rejecting it at boot beats discovering it when a user logs out.

**This is the only definition.** The provider used to carry a second, stricter pattern of its own, so an app id like "_tenant" — or one over 64 characters — passed boot validation and was then refused at runtime, where LogoutURL swallows the error and returns ("", false). Logout degraded silently to clearing the local session, which is precisely the failure the boot-time refusal exists to prevent, reached by another route. It is a function rather than an exported `var` on purpose: a mutable package-level regexp that both boot validation and the runtime URL builder depend on can be reassigned by any importer, which would silently widen the validator both consumers were unified onto.

func ValidateKind

func ValidateKind(in KindInput) error

ValidateKind reports whether the provider configuration can boot.

A nil return means modules/oidc will not refuse startup on account of these settings, and therefore that modules/common may treat the deployment as configured. The two statements must stay equivalent — that is the whole point of this function existing.

func ValidateLogoutURL

func ValidateLogoutURL(envName, raw string, allowInsecure bool) error

ValidateLogoutURL checks one of the two RP-Initiated Logout URLs.

**Single definition.** Both are boot-fatal in the module, and the settings helper had no counterpart -- while its own doc comment claimed to mirror every fatal check and to omit only non-fatal ones. A relative `OCTO_OIDC_POST_LOGOUT_REDIRECT_URI` therefore produced the same total lockout as the cases above.

Empty means "feature off" and is allowed. Non-empty must be absolute and https: both values end up in a browser top-level navigation and the end-session URL carries an id_token, so a misconfiguration can send a token to an arbitrary origin or execute script on navigation. allowInsecure relaxes to http for development only.

Types

type AcceptedScenario

type AcceptedScenario struct {
	Name string
	Env  map[string]string
}

AcceptedScenario is a configuration both readers must agree is usable.

type KindInput

type KindInput struct {
	Kind    string
	BaseURL string
	AppID   string

	EndSessionURL         string
	PostLogoutRedirectURI string

	AutoLinkByEmail      bool
	RequireEmailVerified bool

	// AllowInsecureUpstream permits a plaintext base URL. Separate from the
	// logout-specific escape hatch on purpose: sharing one flag would let
	// "relax the pre-production logout URL" also open the production token
	// endpoint, which carries the client secret.
	AllowInsecureUpstream bool

	// AllowInsecureLogout permits plain http for the two logout URLs (dev only).
	// Deliberately a different flag from AllowInsecureUpstream -- see that field.
	AllowInsecureLogout bool

	// Issuer is the identity namespace. Its length is checked here (IssuerMaxLen); under
	// KindOAuth2 it also doubles as the default base URL via UpstreamBaseURL, which each
	// caller applies before constructing this struct.
	Issuer string
}

KindInput carries the already-resolved provider settings a refusal decision depends on.

Resolved, not raw env: BaseURL in particular falls back to the issuer when unset, and a rule about "the base URL" has to see the value that will actually be used. Callers are responsible for applying that fallback first.

type RefusedScenario

type RefusedScenario struct {
	Name  string
	Input KindInput

	// Env is the same scenario expressed as environment variables, for callers
	// that validate straight from the environment.
	Env map[string]string

	// ExpectKeyInError, when set, is a substring the refusal must mention so an
	// operator can act on the log line.
	ExpectKeyInError string

	// SkipRuleCheck marks a scenario whose refusal comes from a caller's required-env
	// handling rather than from ValidateKind's rules. ValidateKind(Input) is legal for
	// these; only the env-driven consumers are pinned.
	SkipRuleCheck bool
}

RefusedScenario is one configuration that must not be allowed to boot.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址