sso

package

v1.0.0 Latest Latest Go to latest Published: Jul 29, 2026 License: MIT Imports: 26 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/eadwinCode/better-auth-go

Links

Open Source Insights

Documentation ¶

Overview ¶

Package sso provides Better Auth-shaped OIDC, OAuth 2.0, and SAML enterprise single sign-on.

Stability: Experimental. This package is tested but is outside the better-auth-go v1 compatibility guarantee pending pinned differential and live enterprise interoperability certification.

Constants ¶

View Source

const ModelSSOProvider = "ssoProvider"

Variables ¶

This section is empty.

Functions ¶

func New ¶

func New(config Config) (betterauth.Plugin, error)

func PublicHTTPSURLPolicy ¶

func PublicHTTPSURLPolicy(_ context.Context, target *url.URL) error

PublicHTTPSURLPolicy rejects non-HTTPS, credential-bearing, loopback, unspecified, link-local, multicast, and private literal-IP destinations. Applications that need private IdPs must provide an explicit replacement.

Types ¶

type Config ¶

type Config struct {
	Cipher                      betterauth.TokenCipher
	HTTPClient                  HTTPDoer
	OutboundURLPolicy           OutboundURLPolicy
	OrganizationAuthorizer      OrganizationAuthorizer
	DNSResolver                 DNSResolver
	DefaultProviders            []ProviderRegistration
	ProvisionUser               ProvisionUser
	ProvisionUserOnEveryLogin   bool
	OrganizationProvisioning    OrganizationProvisioning
	DefaultOverrideUserInfo     bool
	DisableImplicitSignUp       bool
	DisableProviderRegistration bool
	ProvidersLimit              int
	RedirectURI                 string
	DomainVerification          bool
	DomainVerificationPrefix    string
	DiscoveryTimeout            time.Duration
	DiscoveryResponseLimit      int64
	StateTTL                    time.Duration
	SAML                        SAMLPolicy
	Schema                      betterauth.ModelSchema
}

type DNSResolver ¶

type DNSResolver interface {
	LookupTXT(context.Context, string) ([]string, error)
}

DNSResolver is used for optional provider-domain verification.

type DiscoveryDocument ¶

type DiscoveryDocument struct {
	Issuer                            string   `json:"issuer"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint"`
	TokenEndpoint                     string   `json:"token_endpoint"`
	UserInfoEndpoint                  string   `json:"userinfo_endpoint"`
	JWKSURI                           string   `json:"jwks_uri"`
	ScopesSupported                   []string `json:"scopes_supported"`
	ResponseTypesSupported            []string `json:"response_types_supported"`
	SubjectTypesSupported             []string `json:"subject_types_supported"`
	IDTokenSigningAlgorithmsSupported []string `json:"id_token_signing_alg_values_supported"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`
}

func DiscoverOIDC ¶

func DiscoverOIDC(
	ctx context.Context,
	client HTTPDoer,
	policy OutboundURLPolicy,
	issuer string,
	limit int64,
) (DiscoveryDocument, error)

DiscoverOIDC fetches and validates an OIDC discovery document using the plugin's bounded client and outbound URL policy.

type HTTPDoer ¶

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPDoer is the bounded network port used for OIDC discovery, token, JWKS, user-info, and SAML metadata requests.

type OIDCConfig ¶

type OIDCConfig struct {
	Issuer                      string      `json:"issuer"`
	ClientID                    string      `json:"clientId"`
	ClientSecret                string      `json:"clientSecret"`
	AuthorizationEndpoint       string      `json:"authorizationEndpoint,omitempty"`
	DiscoveryEndpoint           string      `json:"discoveryEndpoint,omitempty"`
	TokenEndpoint               string      `json:"tokenEndpoint,omitempty"`
	UserInfoEndpoint            string      `json:"userInfoEndpoint,omitempty"`
	JWKSEndpoint                string      `json:"jwksEndpoint,omitempty"`
	TokenEndpointAuthentication string      `json:"tokenEndpointAuthentication,omitempty"`
	Scopes                      []string    `json:"scopes,omitempty"`
	OverrideUserInfo            bool        `json:"overrideUserInfo,omitempty"`
	Mapping                     OIDCMapping `json:"mapping,omitempty"`
}

OIDCConfig follows Better Auth's stored provider vocabulary. PKCE S256 is mandatory and therefore is not a disable-able option.

type OIDCMapping ¶

type OIDCMapping struct {
	ID            string            `json:"id,omitempty"`
	Email         string            `json:"email,omitempty"`
	EmailVerified string            `json:"emailVerified,omitempty"`
	Name          string            `json:"name,omitempty"`
	Image         string            `json:"image,omitempty"`
	ExtraFields   map[string]string `json:"extraFields,omitempty"`
}

type OrganizationAuthorizer ¶

type OrganizationAuthorizer interface {
	AuthorizeSSOProvider(*betterauth.HookContext, string) error
	ProvisionSSOUser(*betterauth.HookContext, string, string, string) error
}

OrganizationAuthorizer enforces organization-scoped provider management and provisioning. Implementations must derive authority from the stored target, not from an untrusted request identifier.

type OrganizationProvisioning ¶

type OrganizationProvisioning struct {
	Disabled    bool
	DefaultRole string
	GetRole     func(*betterauth.HookContext, betterauth.User, UserInfo, Provider) (string, error)
}

type OutboundURLPolicy ¶

type OutboundURLPolicy func(context.Context, *url.URL) error

OutboundURLPolicy validates every configured or discovered provider URL. Returning an error rejects the provider.

type Provider ¶

type Provider struct {
	ID             string    `json:"id"`
	Issuer         string    `json:"issuer"`
	Domain         string    `json:"domain"`
	ProviderID     string    `json:"providerId"`
	UserID         string    `json:"userId"`
	OrganizationID string    `json:"organizationId,omitempty"`
	Type           string    `json:"type"`
	DomainVerified bool      `json:"domainVerified,omitempty"`
	CreatedAt      time.Time `json:"createdAt"`
	UpdatedAt      time.Time `json:"updatedAt"`
}

Provider is the non-secret public provider representation.

type ProviderRegistration ¶

type ProviderRegistration struct {
	Issuer         string      `json:"issuer"`
	Domain         string      `json:"domain"`
	ProviderID     string      `json:"providerId"`
	OrganizationID string      `json:"organizationId,omitempty"`
	OIDC           *OIDCConfig `json:"oidcConfig,omitempty"`
	SAML           *SAMLConfig `json:"samlConfig,omitempty"`
}

ProviderRegistration is accepted by configured default providers and the management layer. Exactly one protocol config must be present.

type ProvisionUser ¶

type ProvisionUser func(
	*betterauth.HookContext,
	betterauth.User,
	UserInfo,
	*Tokens,
	Provider,
) error

type SAMLConfig ¶

type SAMLConfig struct {
	Issuer                  string            `json:"issuer"`
	EntryPoint              string            `json:"entryPoint"`
	LogoutEndpoint          string            `json:"logoutEndpoint,omitempty"`
	Certificate             string            `json:"cert"`
	Audience                string            `json:"audience,omitempty"`
	SPEntityID              string            `json:"spEntityId"`
	SPPrivateKey            string            `json:"spPrivateKey,omitempty"`
	EncryptionPrivateKey    string            `json:"encryptionPrivateKey,omitempty"`
	WantAssertionsSigned    bool              `json:"wantAssertionsSigned"`
	AuthnRequestsSigned     bool              `json:"authnRequestsSigned,omitempty"`
	IdentifierFormat        string            `json:"identifierFormat,omitempty"`
	IDPInitiatedCallbackURL string            `json:"idpInitiatedCallbackUrl,omitempty"`
	AdditionalParams        map[string]string `json:"additionalParams,omitempty"`
	Mapping                 SAMLMapping       `json:"mapping,omitempty"`
}

type SAMLMapping ¶

type SAMLMapping struct {
	ID            string            `json:"id,omitempty"`
	Email         string            `json:"email,omitempty"`
	EmailVerified string            `json:"emailVerified,omitempty"`
	Name          string            `json:"name,omitempty"`
	FirstName     string            `json:"firstName,omitempty"`
	LastName      string            `json:"lastName,omitempty"`
	ExtraFields   map[string]string `json:"extraFields,omitempty"`
}

type SAMLPolicy ¶

type SAMLPolicy struct {
	EnableInResponseToValidation bool
	AllowIDPInitiated            bool
	RequestTTL                   time.Duration
	ClockSkew                    time.Duration
	RequireTimestamps            bool
	DeprecatedAlgorithms         string
	MaxResponseSize              int64
	MaxMetadataSize              int64
	EnableSingleLogout           bool
	LogoutRequestTTL             time.Duration
	WantLogoutRequestSigned      bool
	WantLogoutResponseSigned     bool
	IDPInitiatedCallbackURL      string
}

type Tokens ¶

type Tokens struct {
	AccessToken  string
	RefreshToken string
	IDToken      string
	TokenType    string
	Scope        string
	ExpiresAt    time.Time
}

type UserInfo ¶

type UserInfo struct {
	ID            string
	Email         string
	EmailVerified bool
	Name          string
	Image         string
	Attributes    map[string]any
}

Source Files ¶

View all Source files

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