What causes "identity provider issuer is required" in netbirdio/netbird?

Set Issuer to your OIDC issuer base URL, e.g. https://auth.example.com/realms/netbird

identity provider issuer is required

Error message

identity provider issuer is required

What it means

Sentinel error types.ErrIdentityProviderIssuerRequired (management/server/types/identity_provider.go:13), returned by IdentityProvider.Validate when the provider type has no built-in issuer (anything other than google and microsoft, per HasBuiltInIssuer) and the Issuer URL is empty. The issuer is the base URL NetBird uses to discover the OIDC endpoints.

Source

Thrown at management/server/types/identity_provider.go:13

package types

import (
	"errors"
	"net/url"
)

// Identity provider validation errors
var (
	ErrIdentityProviderNameRequired      = errors.New("identity provider name is required")
	ErrIdentityProviderTypeRequired      = errors.New("identity provider type is required")
	ErrIdentityProviderTypeUnsupported   = errors.New("unsupported identity provider type")
	ErrIdentityProviderIssuerRequired    = errors.New("identity provider issuer is required")
	ErrIdentityProviderIssuerInvalid     = errors.New("identity provider issuer must be a valid URL")
	ErrIdentityProviderIssuerUnreachable = errors.New("identity provider issuer is unreachable")
	ErrIdentityProviderIssuerMismatch    = errors.New("identity provider issuer does not match the issuer returned by the provider")
	ErrIdentityProviderClientIDRequired  = errors.New("identity provider client ID is required")
)

// IdentityProviderType is the type of identity provider
type IdentityProviderType string

const (
	// IdentityProviderTypeOIDC is a generic OIDC identity provider
	IdentityProviderTypeOIDC IdentityProviderType = "oidc"
	// IdentityProviderTypeZitadel is the Zitadel identity provider
	IdentityProviderTypeZitadel IdentityProviderType = "zitadel"
	// IdentityProviderTypeEntra is the Microsoft Entra (Azure AD) identity provider
	IdentityProviderTypeEntra IdentityProviderType = "entra"
	// IdentityProviderTypeGoogle is the Google identity provider
	IdentityProviderTypeGoogle IdentityProviderType = "google"

View on GitHub (pinned to 93e97f4bf1)

Solutions

Set Issuer to your OIDC issuer base URL, e.g. https://auth.example.com/realms/netbird
For Google or Microsoft types you may leave it empty; otherwise it is mandatory

Example fix

// before
idp := &types.IdentityProvider{Name: "KC", Type: types.IdentityProviderTypeKeycloak, ClientID: "netbird"}

// after
idp := &types.IdentityProvider{Name: "KC", Type: types.IdentityProviderTypeKeycloak, Issuer: "https://kc.example.com/realms/netbird", ClientID: "netbird"}

Defensive patterns

Strategy: validation

Validate before calling

if !idp.Type.HasBuiltInIssuer() && idp.Issuer == "" {
    return types.ErrIdentityProviderIssuerRequired
}

Try / catch

if err := idp.Validate(); err != nil {
    if errors.Is(err, types.ErrIdentityProviderIssuerRequired) {
        // collect the issuer URL (only google/microsoft may omit it)
    }
    return err
}

Prevention

Include the issuer URL as a mandatory field in IdP setup forms for every type except google and microsoft
Use HasBuiltInIssuer() logic client-side to decide whether the field is required
Document the issuer location for common providers (Keycloak realm URL, Authentik application issuer, etc.)

When it happens

Trigger: Saving an IdP of type oidc/zitadel/okta/keycloak/etc. with an empty issuer field; only google and microsoft types may omit it.

Common situations: Copying a Google-style payload and switching the type to oidc without adding the issuer; setup docs where the issuer line was skipped because it looked optional.

Related errors

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/7745aca751e23b61. Report an issue: GitHub.