auth

Documentation

Overview

Package auth provides OIDC and OAuth 2.0 authentication for desktop apps.

The package implements the Authorization Code flow with PKCE, which is the recommended flow for native/desktop applications. It opens the user's system browser for authentication and receives the callback on a temporary localhost HTTP server.

Supported providers: Google, Microsoft (Entra ID), Apple, GitHub, Okta, Keycloak, and any custom OIDC-compliant provider.

Index

• Variables
• func ClearToken(provider string) error
• func LoadToken(provider string) (refreshToken, email string, err error)
• func SaveToken(provider, refreshToken, email string) error
• type OIDCConfig
• type OIDCResult
  • func Authenticate(cfg OIDCConfig) (*OIDCResult, error)
• type ProviderPreset

Variables

var ErrNoAppID = errors.New("auth: storing a sign-in token needs an app ID; create the app with app.NewWithID")

ErrNoAppID is returned by SaveToken, LoadToken and ClearToken when the running app has no unique ID. Tokens are stored per app, so an app that signs users in must be created with app.NewWithID (or have an ID in its manifest.pxf), as Preferences already require.

var Providers = map[string]ProviderPreset{
	"google": {
		Name:       "Google",
		Issuer:     "https://accounts.google.com",
		Logo:       bellui.NewStaticResource("google.svg", googleLogo),
		BgColor:    color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		TextColor:  color.NRGBA{R: 0x1F, G: 0x1F, B: 0x1F, A: 0xFF},
		ButtonText: "Sign in with Google",
	},
	"microsoft": {
		Name:       "Microsoft",
		Issuer:     "https://login.microsoftonline.com/common/v2.0",
		Logo:       bellui.NewStaticResource("microsoft.svg", microsoftLogo),
		BgColor:    color.NRGBA{R: 0x2F, G: 0x2F, B: 0x2F, A: 0xFF},
		TextColor:  color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		ButtonText: "Sign in with Microsoft",
	},
	"apple": {
		Name:       "Apple",
		Issuer:     "https://appleid.apple.com",
		Logo:       bellui.NewStaticResource("apple.svg", appleLogo),
		BgColor:    color.NRGBA{R: 0x00, G: 0x00, B: 0x00, A: 0xFF},
		TextColor:  color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		ButtonText: "Sign in with Apple",
	},
	"github": {
		Name:       "GitHub",
		Issuer:     "",
		Logo:       bellui.NewStaticResource("github.svg", githubLogo),
		BgColor:    color.NRGBA{R: 0x24, G: 0x29, B: 0x2E, A: 0xFF},
		TextColor:  color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		ButtonText: "Sign in with GitHub",
	},
	"okta": {
		Name:       "Okta",
		Issuer:     "",
		Logo:       bellui.NewStaticResource("okta.svg", oktaLogo),
		BgColor:    color.NRGBA{R: 0x00, G: 0x7D, B: 0xC1, A: 0xFF},
		TextColor:  color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		ButtonText: "Sign in with Okta",
	},
	"keycloak": {
		Name:       "Keycloak",
		Issuer:     "",
		Logo:       nil,
		BgColor:    color.NRGBA{R: 0x4D, G: 0x4D, B: 0x4D, A: 0xFF},
		TextColor:  color.NRGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF},
		ButtonText: "Sign in with Keycloak",
	},
}

Providers maps provider keys to their presets.

Functions

func ClearToken

func ClearToken(provider string) error

ClearToken removes the running app's stored token for a provider.

func LoadToken

func LoadToken(provider string) (refreshToken, email string, err error)

LoadToken reads and decrypts the running app's stored refresh token for a provider. Returns empty strings if no token is stored.

func SaveToken

func SaveToken(provider, refreshToken, email string) error

SaveToken encrypts and persists a refresh token for a provider. Tokens are stored per app (by the running app's unique ID), so two apps that sign in with the same provider keep separate tokens.

Types

type OIDCConfig

type OIDCConfig struct {
	// Provider is a known provider key ("google", "microsoft", "apple",
	// "github", "okta", "keycloak") or "custom" for arbitrary OIDC providers.
	Provider string

	// Issuer is the OIDC issuer URL. For known providers this is set
	// automatically from the preset. Required for "okta", "keycloak",
	// and "custom" providers.
	Issuer string

	// ClientID is the OAuth 2.0 client identifier.
	ClientID string

	// Scopes to request. Defaults to ["openid", "email", "profile"], or to
	// ["user:email", "read:user"] for GitHub.
	Scopes []string

	// Timeout for the entire flow. Defaults to 5 minutes.
	Timeout time.Duration
}

OIDCConfig configures an authentication flow.

type OIDCResult

type OIDCResult struct {
	Email        string `json:"email"`
	Name         string `json:"name"`
	Picture      string `json:"picture"`
	Sub          string `json:"sub"` // unique user identifier
	AccessToken  string `json:"-"`
	RefreshToken string `json:"-"`
	IDToken      string `json:"-"`
}

OIDCResult contains the authenticated user's information.

func Authenticate

func Authenticate(cfg OIDCConfig) (*OIDCResult, error)

Authenticate runs the full OIDC Authorization Code + PKCE flow. It opens the system browser, waits for the callback, exchanges the code for tokens, and returns the user's claims.

type ProviderPreset

type ProviderPreset struct {
	// Name is the human-readable provider name.
	Name string

	// Issuer is the OIDC discovery base URL.
	// Empty for providers that need a tenant-specific issuer (Okta, Keycloak).
	Issuer string

	// Logo is the provider's brand icon.
	Logo bellui.Resource

	// BgColor is the brand-compliant button background color.
	BgColor color.NRGBA

	// TextColor is the brand-compliant button text color.
	TextColor color.NRGBA

	// ButtonText is the default button label (e.g., "Sign in with Google").
	ButtonText string
}

ProviderPreset defines the visual identity and discovery URL for a known authentication provider.