Documentation
¶
Overview ¶
Package dex provides an embedded Dex OIDC identity provider.
Package dex provides an embedded Dex OIDC identity provider.
Index ¶
- func DecodeDexUserID(encodedID string) (userID, connectorID string, err error)
- func EncodeDexUserID(userID, connectorID string) string
- type Config
- type Connector
- type ConnectorConfig
- type Expiry
- type Frontend
- type GRPC
- type Logger
- type LogrusHandler
- type MFAAuthenticator
- type MFAConfig
- type OAuth2
- type Password
- type Provider
- func (p *Provider) CreateConnector(ctx context.Context, cfg *ConnectorConfig) (*ConnectorConfig, error)
- func (p *Provider) CreateUser(ctx context.Context, email, username, password string) (string, error)
- func (p *Provider) DeleteConnector(ctx context.Context, id string) error
- func (p *Provider) DeleteUser(ctx context.Context, email string) error
- func (p *Provider) DisableLocalAuth(ctx context.Context) error
- func (p *Provider) EnableLocalAuth(ctx context.Context) error
- func (p *Provider) EnsureDefaultClients(ctx context.Context, dashboardURIs, cliURIs []string) error
- func (p *Provider) GetAuthorizationEndpoint() string
- func (p *Provider) GetConnector(ctx context.Context, id string) (*ConnectorConfig, error)
- func (p *Provider) GetDeviceAuthEndpoint() string
- func (p *Provider) GetIssuer() string
- func (p *Provider) GetJWKS(ctx context.Context) (*nbjwt.Jwks, error)
- func (p *Provider) GetKeysLocation() string
- func (p *Provider) GetRedirectURI() string
- func (p *Provider) GetTokenEndpoint() string
- func (p *Provider) GetUser(ctx context.Context, email string) (storage.Password, error)
- func (p *Provider) GetUserByID(ctx context.Context, userID string) (storage.Password, error)
- func (p *Provider) Handler() http.Handler
- func (p *Provider) HasNonLocalConnectors(ctx context.Context) (bool, error)
- func (p *Provider) ListConnectors(ctx context.Context) ([]*ConnectorConfig, error)
- func (p *Provider) ListUsers(ctx context.Context) ([]storage.Password, error)
- func (p *Provider) SetClientsMFAChain(ctx context.Context, clientIDs []string, mfaChain []string) error
- func (p *Provider) Start(_ context.Context) error
- func (p *Provider) Stop(ctx context.Context) error
- func (p *Provider) Storage() storage.Storage
- func (p *Provider) UpdateConnector(ctx context.Context, cfg *ConnectorConfig) error
- func (p *Provider) UpdateUserPassword(ctx context.Context, userID string, oldPassword, newPassword string) error
- type RefreshTokensExpiry
- type Sessions
- type Storage
- type StorageConfig
- type TOTPConfig
- type Web
- type WebAuthnConfig
- type YAMLConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeDexUserID ¶
DecodeDexUserID decodes Dex's base64-encoded user ID back to the raw user ID and connector ID.
func EncodeDexUserID ¶
EncodeDexUserID encodes user ID and connector ID into Dex's base64-encoded protobuf format. Dex uses this format for the 'sub' claim in JWT tokens. Format: base64(protobuf message with field 1 = user_id, field 2 = connector_id)
Types ¶
type Config ¶
type Config struct {
Issuer string
Port int
DataDir string
DevMode bool
// GRPCAddr is the address for the gRPC API (e.g., ":5557"). Empty disables gRPC.
GRPCAddr string
}
Config matches what management/internals/server/server.go expects
type Connector ¶
type Connector struct {
Type string `yaml:"type" json:"type"`
Name string `yaml:"name" json:"name"`
ID string `yaml:"id" json:"id"`
Config map[string]interface{} `yaml:"config" json:"config"`
}
Connector is a connector configuration that can unmarshal YAML dynamically.
func (*Connector) ToStorageConnector ¶
ToStorageConnector converts a Connector to storage.Connector type. It maps custom connector types (e.g., "zitadel", "entra") to Dex-native types and augments the config with OIDC defaults when needed.
type ConnectorConfig ¶
type ConnectorConfig struct {
// ID is the unique identifier for the connector
ID string
// Name is a human-readable name for the connector
Name string
// Type is the connector type (oidc, google, microsoft)
Type string
// Issuer is the OIDC issuer URL (for OIDC-based connectors)
Issuer string
// ClientID is the OAuth2 client ID
ClientID string
// ClientSecret is the OAuth2 client secret
ClientSecret string
// RedirectURI is the OAuth2 redirect URI
RedirectURI string
}
ConnectorConfig represents the configuration for an identity provider connector
type Expiry ¶
type Expiry struct {
SigningKeys string `yaml:"signingKeys" json:"signingKeys"`
IDTokens string `yaml:"idTokens" json:"idTokens"`
AuthRequests string `yaml:"authRequests" json:"authRequests"`
DeviceRequests string `yaml:"deviceRequests" json:"deviceRequests"`
RefreshTokens RefreshTokensExpiry `yaml:"refreshTokens" json:"refreshTokens"`
}
Expiry holds configuration for the validity period of components.
type Frontend ¶
type Frontend struct {
Dir string `yaml:"dir" json:"dir"`
Theme string `yaml:"theme" json:"theme"`
Issuer string `yaml:"issuer" json:"issuer"`
LogoURL string `yaml:"logoURL" json:"logoURL"`
Extra map[string]string `yaml:"extra" json:"extra"`
}
Frontend holds the server's frontend templates and assets config.
type GRPC ¶
type GRPC struct {
Addr string `yaml:"addr" json:"addr"`
TLSCert string `yaml:"tlsCert" json:"tlsCert"`
TLSKey string `yaml:"tlsKey" json:"tlsKey"`
TLSClientCA string `yaml:"tlsClientCA" json:"tlsClientCA"`
}
GRPC is the config for the gRPC API.
type Logger ¶
type Logger struct {
Level string `yaml:"level" json:"level"`
Format string `yaml:"format" json:"format"`
}
Logger holds configuration required to customize logging.
type LogrusHandler ¶ added in v0.62.2
type LogrusHandler struct {
// contains filtered or unexported fields
}
LogrusHandler is an slog.Handler that delegates to logrus. This allows Dex to use the same log format as the rest of NetBird.
func NewLogrusHandler ¶ added in v0.62.2
func NewLogrusHandler(level slog.Level) *LogrusHandler
NewLogrusHandler creates a new slog handler that wraps logrus with NetBird's text formatter.
func (*LogrusHandler) Enabled ¶ added in v0.62.2
Enabled reports whether the handler handles records at the given level.
type MFAAuthenticator ¶ added in v0.71.0
type MFAConfig ¶ added in v0.71.0
type MFAConfig struct {
Authenticators []MFAAuthenticator `yaml:"authenticators" json:"authenticators"`
}
type OAuth2 ¶
type OAuth2 struct {
SkipApprovalScreen bool `yaml:"skipApprovalScreen" json:"skipApprovalScreen"`
AlwaysShowLoginScreen bool `yaml:"alwaysShowLoginScreen" json:"alwaysShowLoginScreen"`
PasswordConnector string `yaml:"passwordConnector" json:"passwordConnector"`
ResponseTypes []string `yaml:"responseTypes" json:"responseTypes"`
GrantTypes []string `yaml:"grantTypes" json:"grantTypes"`
}
OAuth2 describes enabled OAuth2 extensions.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps a Dex server
func NewProvider ¶
NewProvider creates and initializes the Dex server
func NewProviderFromYAML ¶
func NewProviderFromYAML(ctx context.Context, yamlConfig *YAMLConfig) (*Provider, error)
NewProviderFromYAML creates and initializes the Dex server from a YAMLConfig
func (*Provider) CreateConnector ¶
func (p *Provider) CreateConnector(ctx context.Context, cfg *ConnectorConfig) (*ConnectorConfig, error)
CreateConnector creates a new connector in Dex storage. It maps the connector config to the appropriate Dex connector type and configuration.
func (*Provider) CreateUser ¶
func (p *Provider) CreateUser(ctx context.Context, email, username, password string) (string, error)
CreateUser creates a new user with the given email, username, and password. Returns the encoded user ID in Dex's format (base64-encoded protobuf with connector ID).
func (*Provider) DeleteConnector ¶
DeleteConnector removes a connector from Dex storage.
func (*Provider) DeleteUser ¶
DeleteUser removes a user by email
func (*Provider) DisableLocalAuth ¶ added in v0.64.4
DisableLocalAuth removes the local (password) connector. Returns an error if no other connectors are configured.
func (*Provider) EnableLocalAuth ¶ added in v0.64.4
EnableLocalAuth creates the local (password) connector if it doesn't exist.
func (*Provider) EnsureDefaultClients ¶
EnsureDefaultClients creates dashboard and CLI OAuth clients Uses Dex's storage.Client directly - no custom wrappers
func (*Provider) GetAuthorizationEndpoint ¶
GetAuthorizationEndpoint returns the OAuth2 authorization endpoint URL.
func (*Provider) GetConnector ¶
GetConnector retrieves a connector by ID from Dex storage.
func (*Provider) GetDeviceAuthEndpoint ¶
GetDeviceAuthEndpoint returns the OAuth2 device authorization endpoint URL.
func (*Provider) GetJWKS ¶ added in v0.67.2
GetJWKS reads signing keys directly from Dex storage and returns them as Jwks. This avoids HTTP round-trips when the embedded IDP is co-located with the management server. The key retrieval mirrors Dex's own handlePublicKeys/ValidationKeys logic: SigningKeyPub first, then all VerificationKeys, serialized via go-jose.
func (*Provider) GetKeysLocation ¶
GetKeysLocation returns the JWKS endpoint URL for token validation.
func (*Provider) GetRedirectURI ¶
GetRedirectURI returns the default redirect URI for connectors.
func (*Provider) GetTokenEndpoint ¶
GetTokenEndpoint returns the OAuth2 token endpoint URL.
func (*Provider) GetUserByID ¶
GetUserByID returns a user by user ID. The userID can be either an encoded Dex ID (base64 protobuf) or a raw UUID. Note: This requires iterating through all users since dex storage doesn't index by userID.
func (*Provider) Handler ¶
Handler returns the Dex server as an http.Handler for embedding in another server. The handler expects requests with path prefix "/oauth2/".
func (*Provider) HasNonLocalConnectors ¶ added in v0.64.4
HasNonLocalConnectors checks if there are any connectors other than the local connector.
func (*Provider) ListConnectors ¶
func (p *Provider) ListConnectors(ctx context.Context) ([]*ConnectorConfig, error)
ListConnectors returns all connectors from Dex storage (excluding the local connector).
func (*Provider) SetClientsMFAChain ¶ added in v0.71.0
func (p *Provider) SetClientsMFAChain(ctx context.Context, clientIDs []string, mfaChain []string) error
SetClientsMFAChain updates the MFAChain field on the dashboard and CLI OAuth2 clients. Pass a non-empty slice (e.g. []string{"default-totp"}) to enable MFA, or nil to disable it.
func (*Provider) Storage ¶
Storage returns the underlying Dex storage for direct access Users can use storage.Client, storage.Password, storage.Connector directly
func (*Provider) UpdateConnector ¶
func (p *Provider) UpdateConnector(ctx context.Context, cfg *ConnectorConfig) error
UpdateConnector updates an existing connector in Dex storage. It overlays user-mutable config fields (issuer, clientID, clientSecret, redirectURI) onto the stored connector config, and updates the connector name when cfg.Name is set. Empty fields on cfg leave stored values unchanged, so partial updates preserve create-time defaults such as scopes, claimMapping, and userIDKey.
func (*Provider) UpdateUserPassword ¶ added in v0.64.0
func (p *Provider) UpdateUserPassword(ctx context.Context, userID string, oldPassword, newPassword string) error
UpdateUserPassword updates the password for a user identified by userID. The userID can be either an encoded Dex ID (base64 protobuf) or a raw UUID. It verifies the current password before updating.
type RefreshTokensExpiry ¶
type RefreshTokensExpiry struct {
ReuseInterval string `yaml:"reuseInterval" json:"reuseInterval"`
ValidIfNotUsedFor string `yaml:"validIfNotUsedFor" json:"validIfNotUsedFor"`
AbsoluteLifetime string `yaml:"absoluteLifetime" json:"absoluteLifetime"`
DisableRotation bool `yaml:"disableRotation" json:"disableRotation"`
}
RefreshTokensExpiry holds configuration for refresh token expiry.
type Sessions ¶ added in v0.71.0
type Sessions struct {
// CookieName is the name of the session cookie. Defaults to "dex_session".
CookieName string `yaml:"cookieName" json:"cookieName"`
// AbsoluteLifetime is the maximum session lifetime from creation. Defaults to "24h".
AbsoluteLifetime string `yaml:"absoluteLifetime" json:"absoluteLifetime"`
// ValidIfNotUsedFor is the idle timeout. Defaults to "1h".
ValidIfNotUsedFor string `yaml:"validIfNotUsedFor" json:"validIfNotUsedFor"`
// RememberMeCheckedByDefault controls the default state of the "remember me" checkbox.
RememberMeCheckedByDefault *bool `yaml:"rememberMeCheckedByDefault" json:"rememberMeCheckedByDefault"`
// CookieEncryptionKey is the AES key for encrypting session cookies.
// Must be 16, 24, or 32 bytes for AES-128, AES-192, or AES-256.
// If empty, cookies are not encrypted.
CookieEncryptionKey string `yaml:"cookieEncryptionKey" json:"cookieEncryptionKey"`
// "all" = share with all clients, "none" = share with no one (default: "none").
SSOSharedWithDefault string `yaml:"ssoSharedWithDefault" json:"ssoSharedWithDefault"`
}
type Storage ¶
type Storage struct {
Type string `yaml:"type" json:"type"`
Config map[string]interface{} `yaml:"config" json:"config"`
}
Storage holds app's storage configuration.
type StorageConfig ¶
StorageConfig is a configuration that can create a storage.
type TOTPConfig ¶ added in v0.71.0
type TOTPConfig struct {
Issuer string `yaml:"issuer" json:"issuer"`
}
type Web ¶
type Web struct {
HTTP string `yaml:"http" json:"http"`
HTTPS string `yaml:"https" json:"https"`
AllowedOrigins []string `yaml:"allowedOrigins" json:"allowedOrigins"`
AllowedHeaders []string `yaml:"allowedHeaders" json:"allowedHeaders"`
}
Web is the config format for the HTTP server.
type WebAuthnConfig ¶ added in v0.71.0
type WebAuthnConfig struct {
// RPDisplayName is the human-readable relying party name shown in the browser
// dialog during key registration and authentication (e.g., "My Company SSO").
RPDisplayName string `yaml:"rpDisplayName" json:"rpDisplayName"`
// RPID is the relying party identifier — must match the domain in the browser
// address bar. If empty, derived from the issuer URL hostname.
// Example: "auth.example.com"
RPID string `yaml:"rpID" json:"rpID"`
// RPOrigins is the list of allowed origins for WebAuthn ceremonies.
// If empty, derived from the issuer URL (scheme + host).
// Example: ["https://auth.example.com"]
RPOrigins []string `yaml:"rpOrigins" json:"rpOrigins"`
// AttestationPreference controls what attestation data the authenticator should provide:
// "none" — don't request attestation (simpler, more private)
// "indirect" — authenticator may anonymize attestation (default)
// "direct" — request full attestation (for enterprise key model verification)
AttestationPreference string `yaml:"attestationPreference" json:"attestationPreference"`
// Timeout is the duration allowed for the browser WebAuthn ceremony
// (registration or login). Defaults to "60s".
Timeout string `yaml:"timeout" json:"timeout"`
}
WebAuthnConfig holds configuration for a WebAuthn authenticator.
type YAMLConfig ¶
type YAMLConfig struct {
Issuer string `yaml:"issuer" json:"issuer"`
Storage Storage `yaml:"storage" json:"storage"`
Web Web `yaml:"web" json:"web"`
GRPC GRPC `yaml:"grpc" json:"grpc"`
OAuth2 OAuth2 `yaml:"oauth2" json:"oauth2"`
Expiry Expiry `yaml:"expiry" json:"expiry"`
Logger Logger `yaml:"logger" json:"logger"`
Frontend Frontend `yaml:"frontend" json:"frontend"`
// StaticConnectors are user defined connectors specified in the config file
StaticConnectors []Connector `yaml:"connectors" json:"connectors"`
// StaticClients cause the server to use this list of clients rather than
// querying the storage. Write operations, like creating a client, will fail.
StaticClients []storage.Client `yaml:"staticClients" json:"staticClients"`
// If enabled, the server will maintain a list of passwords which can be used
// to identify a user.
EnablePasswordDB bool `yaml:"enablePasswordDB" json:"enablePasswordDB"`
// StaticPasswords cause the server use this list of passwords rather than
// querying the storage.
StaticPasswords []Password `yaml:"staticPasswords" json:"staticPasswords"`
// Sessions holds authentication session configuration.
// Requires DEX_SESSIONS_ENABLED=true feature flag.
Sessions *Sessions `yaml:"sessions" json:"sessions"`
// MFA holds multi-factor authentication configuration.
MFA MFAConfig `yaml:"mfa" json:"mfa"`
}
YAMLConfig represents the YAML configuration file format (mirrors dex's config format)
func LoadConfig ¶
func LoadConfig(path string) (*YAMLConfig, error)
LoadConfig loads configuration from a YAML file
func (*YAMLConfig) GetRefreshTokenPolicy ¶
func (c *YAMLConfig) GetRefreshTokenPolicy(logger *slog.Logger) (*server.RefreshTokenPolicy, error)
GetRefreshTokenPolicy creates a RefreshTokenPolicy from the expiry config. This should be called after ToServerConfig and the policy set on the config.
func (*YAMLConfig) ToServerConfig ¶
ToServerConfig converts YAMLConfig to dex server.Config
func (*YAMLConfig) Validate ¶
func (c *YAMLConfig) Validate() error
Validate validates the configuration