Documentation
¶
Index ¶
- Constants
- type AuthorizeRequest
- type AuthorizeResponse
- type CallbackRequest
- type CallbackResponse
- type CallbackResult
- type CallbackSession
- type ErrorResponse
- type OAuth2PluginConfig
- type OAuth2Provider
- type OAuthAuthorizationCode
- type OAuthClient
- type OAuthConsent
- type OAuthConsentRequest
- type OAuthFlowState
- type OAuthLoginTransaction
- type ProviderConfig
- type RedirectResponse
- type UserInfo
Constants ¶
const ( OAuthClientOwnerTypeUser = "user" OAuthClientOwnerTypeOrganization = "organization" OAuthGrantTypeAuthorizationCode = "authorization_code" OAuthGrantTypeClientCredentials = "client_credentials" OAuthConsentSourceExplicit = "explicit" OAuthConsentSourceTrusted = "trusted" OAuthConsentSourcePromptNone = "prompt_none" CodeChallengeMethodS256 = "S256" OAuthFlowPurposeLogin = "login" OAuthFlowPurposeLink = "link" ScopeOpenID = "openid" ScopeProfile = "profile" ScopeEmail = "email" )
OAuth client ownership and protocol constants shared by the authorization server repositories and services.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthorizeRequest ¶
type AuthorizeRequest struct {
ProviderID string `path:"provider"`
RedirectTo string `query:"redirect_to" json:"redirect_to,omitempty" nullable:"true"`
// ActorID is set when an already signed-in user starts a linking flow.
ActorID string `json:"-"`
}
AuthorizeRequest represents an authorization request
type AuthorizeResponse ¶
type AuthorizeResponse struct {
AuthURL string `json:"auth_url" required:"true" nullable:"false"`
}
AuthorizeResponse represents an authorization response
type CallbackRequest ¶
type CallbackRequest struct {
ProviderID string `path:"provider"`
Code string `query:"code" json:"code,omitempty" nullable:"true"`
State string `query:"state" json:"state,omitempty" nullable:"true"`
Error string `query:"error" json:"error,omitempty" nullable:"true"`
ErrorDescription string `query:"error_description" json:"error_description,omitempty" nullable:"true"`
// ActorID and SessionID are populated from the request context when a signed-in
// user starts a linking flow.
ActorID string `json:"-"`
SessionID string `json:"-"`
// Binding is populated from the browser-binding cookie and is folded into the
// state lookup hash.
Binding string `json:"-"`
}
CallbackRequest represents an OAuth2 callback request
type CallbackResponse ¶
type CallbackResponse struct {
User *models.User `json:"user" required:"true" nullable:"false"`
Session *CallbackSession `json:"session" required:"true" nullable:"false"`
}
CallbackResponse represents an OAuth2 callback response. It intentionally omits the session token, IP address, and user agent.
type CallbackResult ¶
type CallbackResult struct {
User *models.User
Session *models.Session
SessionToken string
RedirectTo string
ReusedSession bool
}
CallbackResult represents the result of OAuth2 callback
type CallbackSession ¶ added in v1.50.0
type CallbackSession struct {
ID string `json:"id" required:"true" nullable:"false"`
UserID string `json:"user_id" required:"true" nullable:"false"`
ExpiresAt time.Time `json:"expires_at" required:"true" nullable:"false"`
}
CallbackSession is the safe public view of a session.
type ErrorResponse ¶ added in v1.50.0
type ErrorResponse struct {
Message string `json:"message" required:"true" nullable:"false"`
}
ErrorResponse is the generic error body returned by OAuth2 endpoints.
type OAuth2PluginConfig ¶
type OAuth2PluginConfig struct {
Enabled bool `json:"enabled" toml:"enabled"`
HTTPTimeout time.Duration `json:"http_timeout" toml:"http_timeout"`
Providers map[string]ProviderConfig `json:"providers" toml:"providers"`
AuthorizationServerEnabled bool `json:"authorization_server_enabled" toml:"authorization_server_enabled"`
ClientManagementEnabled bool `json:"client_management_enabled" toml:"client_management_enabled"`
LoginURL string `json:"login_url" toml:"login_url"`
ConsentURL string `json:"consent_url" toml:"consent_url"`
ConsentOrigins []string `json:"consent_origins" toml:"consent_origins"`
AllowedScopes []string `json:"allowed_scopes" toml:"allowed_scopes"`
AllowOrgClients bool `json:"allow_org_clients" toml:"allow_org_clients"`
AuthorizationCodeTTL time.Duration `json:"authorization_code_ttl" toml:"authorization_code_ttl"`
ConsentRequestTTL time.Duration `json:"consent_request_ttl" toml:"consent_request_ttl"`
FlowStateTTL time.Duration `json:"flow_state_ttl" toml:"flow_state_ttl"`
IDTokenTTL time.Duration `json:"id_token_ttl" toml:"id_token_ttl"`
AutoCleanup bool `json:"auto_cleanup" toml:"auto_cleanup"`
CleanupInterval time.Duration `json:"cleanup_interval" toml:"cleanup_interval"`
}
OAuth2PluginConfig represents the OAuth2 plugin configuration
func (*OAuth2PluginConfig) ApplyDefaults ¶
func (c *OAuth2PluginConfig) ApplyDefaults()
ApplyDefaults applies default values to the config
type OAuth2Provider ¶
type OAuth2Provider interface {
Name() string
GetConfig() *oauth2.Config
GetAuthURL(state string, opts ...oauth2.AuthCodeOption) string
Exchange(ctx context.Context, code string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)
GetUserInfo(ctx context.Context, token *oauth2.Token) (*UserInfo, error)
RequiresPKCE() bool
}
OAuth2Provider interface defines the contract for OAuth2 providers
type OAuthAuthorizationCode ¶ added in v1.51.0
type OAuthAuthorizationCode struct {
bun.BaseModel `bun:"table:authorization_codes"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
CodeHash string `json:"code_hash" bun:"column:code_hash,unique" required:"true" nullable:"false"`
ClientID string `json:"client_id" bun:"column:client_id" required:"true" nullable:"false"`
UserID string `json:"user_id" bun:"column:user_id" required:"true" nullable:"false"`
SessionID string `json:"session_id" bun:"column:session_id" required:"true" nullable:"false"`
ConsentID string `json:"consent_id" bun:"column:consent_id" required:"true" nullable:"false"`
RedirectURI string `json:"redirect_uri" bun:"column:redirect_uri" required:"true" nullable:"false"`
Scope string `json:"scope" bun:"column:scope" required:"true" nullable:"false"`
Nonce *string `json:"nonce" bun:"column:nonce" nullable:"true"`
CodeChallenge string `json:"code_challenge" bun:"column:code_challenge" required:"true" nullable:"false"`
CodeChallengeMethod string `json:"code_challenge_method" bun:"column:code_challenge_method" required:"true" nullable:"false"`
AuthTime time.Time `json:"auth_time" bun:"column:auth_time" required:"true" nullable:"false"`
ExpiresAt time.Time `json:"expires_at" bun:"column:expires_at" required:"true" nullable:"false"`
ConsumedAt *time.Time `json:"consumed_at,omitempty" bun:"column:consumed_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthAuthorizationCode is a single-use authorization code. Only the SHA-256 hash of the code is stored.
type OAuthClient ¶ added in v1.51.0
type OAuthClient struct {
bun.BaseModel `bun:"table:oauth_clients"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
ClientID string `json:"client_id" bun:"column:client_id,unique" required:"true" nullable:"false"`
ClientSecretHash string `json:"-" bun:"column:client_secret_hash" required:"true" nullable:"false"`
ClientSecretSalt string `json:"-" bun:"column:client_secret_salt" required:"true" nullable:"false"`
ClientSecretPrefix string `json:"client_secret_prefix" bun:"column:client_secret_prefix" required:"true" nullable:"false"`
Name string `json:"name" bun:"column:name" required:"true" nullable:"false"`
RedirectURIs []string `json:"redirect_uris" bun:"column:redirect_uris" required:"true" nullable:"false"`
AllowedGrants []string `json:"allowed_grants" bun:"column:allowed_grants" required:"true" nullable:"false"`
AllowedScopes []string `json:"allowed_scopes" bun:"column:allowed_scopes" required:"true" nullable:"false"`
OwnerType string `json:"owner_type" bun:"column:owner_type" required:"true" nullable:"false"`
OwnerID string `json:"owner_id" bun:"column:owner_id" required:"true" nullable:"false"`
CreatorID string `json:"creator_id" bun:"column:creator_id" required:"true" nullable:"false"`
OrganizationID *string `json:"organization_id" bun:"column:organization_id" nullable:"true"`
IsActive bool `json:"is_active" bun:"column:is_active" required:"true" nullable:"false"`
DeletedAt *time.Time `json:"deleted_at,omitempty" bun:"column:deleted_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
UpdatedAt time.Time `json:"updated_at" bun:"column:updated_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthClient is a registered OAuth 2.0 client. Client secrets and other one-time credentials are never stored in plain text.
type OAuthConsent ¶ added in v1.51.0
type OAuthConsent struct {
bun.BaseModel `bun:"table:oauth_consents"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
UserID string `json:"user_id" bun:"column:user_id" required:"true" nullable:"false"`
ClientID string `json:"client_id" bun:"column:client_id" required:"true" nullable:"false"`
Scope string `json:"scope" bun:"column:scope" required:"true" nullable:"false"`
Source string `json:"source" bun:"column:source" required:"true" nullable:"false"`
RevokedAt *time.Time `json:"revoked_at,omitempty" bun:"column:revoked_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
UpdatedAt time.Time `json:"updated_at" bun:"column:updated_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthConsent records a user's grant of scopes to a client. Revoked rows are retained so scope changes can be audited.
type OAuthConsentRequest ¶ added in v1.51.0
type OAuthConsentRequest struct {
bun.BaseModel `bun:"table:oauth_consent_requests"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
RequestHash string `json:"-" bun:"column:request_hash,unique" required:"true" nullable:"false"`
ClientID string `json:"client_id" bun:"column:client_id" required:"true" nullable:"false"`
UserID string `json:"user_id" bun:"column:user_id" required:"true" nullable:"false"`
SessionID string `json:"session_id" bun:"column:session_id" required:"true" nullable:"false"`
RedirectURI string `json:"redirect_uri" bun:"column:redirect_uri" required:"true" nullable:"false"`
Scope string `json:"scope" bun:"column:scope" required:"true" nullable:"false"`
State *string `json:"state" bun:"column:state" nullable:"true"`
Nonce *string `json:"nonce" bun:"column:nonce" nullable:"true"`
CodeChallenge string `json:"code_challenge" bun:"column:code_challenge" required:"true" nullable:"false"`
CodeChallengeMethod string `json:"code_challenge_method" bun:"column:code_challenge_method" required:"true" nullable:"false"`
Prompt string `json:"prompt" bun:"column:prompt" nullable:"true"`
MaxAge *int `json:"max_age" bun:"column:max_age" nullable:"true"`
AuthTime time.Time `json:"auth_time" bun:"column:auth_time" required:"true" nullable:"false"`
ExpiresAt time.Time `json:"expires_at" bun:"column:expires_at" required:"true" nullable:"false"`
ConsumedAt *time.Time `json:"consumed_at,omitempty" bun:"column:consumed_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthConsentRequest preserves an authorization request while the user is asked for consent. The raw consent token is only returned to the caller.
type OAuthFlowState ¶ added in v1.51.0
type OAuthFlowState struct {
bun.BaseModel `bun:"table:oauth_flow_states"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
StateHash string `json:"-" bun:"column:state_hash,unique" required:"true" nullable:"false"`
Provider string `json:"provider" bun:"column:provider" required:"true" nullable:"false"`
Purpose string `json:"purpose" bun:"column:purpose" required:"true" nullable:"false"`
UserID *string `json:"user_id" bun:"column:user_id" nullable:"true"`
RedirectTo *string `json:"redirect_to" bun:"column:redirect_to" nullable:"true"`
CodeVerifierEncrypted *string `json:"-" bun:"column:code_verifier_encrypted" nullable:"true"`
ExpiresAt time.Time `json:"expires_at" bun:"column:expires_at" required:"true" nullable:"false"`
ConsumedAt *time.Time `json:"consumed_at,omitempty" bun:"column:consumed_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthFlowState stores a single-use outbound provider flow. The stored PKCE verifier is encrypted with the token service, not hashed.
type OAuthLoginTransaction ¶ added in v1.51.0
type OAuthLoginTransaction struct {
bun.BaseModel `bun:"table:oauth_login_transactions"`
ID string `json:"id" bun:"column:id,pk" required:"true" nullable:"false"`
TransactionHash string `json:"-" bun:"column:transaction_hash,unique" required:"true" nullable:"false"`
ClientID string `json:"client_id" bun:"column:client_id" required:"true" nullable:"false"`
RedirectURI string `json:"redirect_uri" bun:"column:redirect_uri" required:"true" nullable:"false"`
Scope string `json:"scope" bun:"column:scope" required:"true" nullable:"false"`
State *string `json:"state" bun:"column:state" nullable:"true"`
Nonce *string `json:"nonce" bun:"column:nonce" nullable:"true"`
CodeChallenge string `json:"code_challenge" bun:"column:code_challenge" required:"true" nullable:"false"`
CodeChallengeMethod string `json:"code_challenge_method" bun:"column:code_challenge_method" required:"true" nullable:"false"`
Prompt string `json:"prompt" bun:"column:prompt" nullable:"true"`
MaxAge *int `json:"max_age" bun:"column:max_age" nullable:"true"`
AuthTime time.Time `json:"auth_time" bun:"column:auth_time" required:"true" nullable:"false"`
CompletedAt *time.Time `json:"completed_at,omitempty" bun:"column:completed_at,nullzero" nullable:"true"`
ExpiresAt time.Time `json:"expires_at" bun:"column:expires_at" required:"true" nullable:"false"`
ConsumedAt *time.Time `json:"consumed_at,omitempty" bun:"column:consumed_at,nullzero" nullable:"true"`
CreatedAt time.Time `json:"created_at" bun:"column:created_at,default:current_timestamp" required:"true" nullable:"false"`
}
OAuthLoginTransaction preserves an authorize request across a login redirect for prompt=login and max_age handling.
type ProviderConfig ¶
type ProviderConfig struct {
// Enabled defaults to true when absent. Set it explicitly to false to disable a provider.
Enabled *bool `json:"enabled,omitempty" toml:"enabled,omitempty"`
ClientID string `json:"client_id" toml:"client_id"`
ClientSecret string `json:"client_secret" toml:"client_secret"`
RedirectURL string `json:"redirect_url" toml:"redirect_url"`
Scopes []string `json:"scopes" toml:"scopes"`
AuthURL string `json:"auth_url" toml:"auth_url"`
TokenURL string `json:"token_url" toml:"token_url"`
UserInfoURL string `json:"user_info_url" toml:"user_info_url"`
UserIDField string `json:"user_id_field" toml:"user_id_field"`
EmailField string `json:"email_field" toml:"email_field"`
NameField string `json:"name_field" toml:"name_field"`
PictureField string `json:"picture_field" toml:"picture_field"`
// EmailVerifiedField is the field that carries the provider's email verification flag.
EmailVerifiedField string `json:"email_verified_field" toml:"email_verified_field"`
// PKCE controls whether this provider must use PKCE with S256. It defaults to true.
// Setting it to false is an explicit opt-out and is not OAuth 2.1 compliant.
PKCE *bool `json:"pkce,omitempty" toml:"pkce,omitempty"`
TenantID *string `json:"tenant_id,omitempty" toml:"tenant_id,omitempty"` // Microsoft only: common (default), organizations, consumers or a tenant ID
// AuthURLParams are extra query parameters appended to the provider's
// authorization URL. Provider configuration overrides provider defaults.
// Empty values remove a default parameter. Protocol-managed parameters are
// rejected during configuration validation.
AuthURLParams map[string]string `json:"auth_url_params,omitempty" toml:"auth_url_params,omitempty"`
}
ProviderConfig represents configuration for an OAuth2 provider
func (ProviderConfig) IsEnabled ¶ added in v1.50.0
func (c ProviderConfig) IsEnabled() bool
IsEnabled reports whether the provider is enabled. Absent means enabled.
func (ProviderConfig) PKCEEnabled ¶ added in v1.50.1
func (c ProviderConfig) PKCEEnabled() bool
PKCEEnabled reports whether PKCE is required for this provider. Absent means enabled.
type RedirectResponse ¶ added in v1.50.0
type RedirectResponse struct{}
RedirectResponse documents the empty body returned with a 302 response.
type UserInfo ¶
type UserInfo struct {
ProviderAccountID string `json:"provider_account_id"`
Email string `json:"email"`
EmailVerified bool `json:"email_verified"`
Name string `json:"name"`
Picture string `json:"picture"`
Raw map[string]any `json:"raw"`
}
UserInfo represents normalized user information from OAuth2 providers