auth

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 27, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package auth provides authentication handler types and utilities for scafctl plugins.

Index

Constants

View Source 
const DefaultMinValidFor = 60 * time.Second

DefaultMinValidFor is the default minimum validity duration for tokens.

Variables

This section is empty.

Functions

func HasCapability 

func HasCapability(capabilities []Capability, capability Capability) bool

HasCapability checks if a set of capabilities includes the specified capability.

Types

type CachedTokenInfo 

type CachedTokenInfo struct {
	Handler     string    `json:"handler" yaml:"handler"`
	TokenKind   string    `json:"tokenKind" yaml:"tokenKind"`
	Scope       string    `json:"scope,omitempty" yaml:"scope,omitempty"`
	TokenType   string    `json:"tokenType,omitempty" yaml:"tokenType,omitempty"`
	Flow        Flow      `json:"flow,omitempty" yaml:"flow,omitempty"`
	Fingerprint string    `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty"`
	ExpiresAt   time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
	CachedAt    time.Time `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty"`
	IsExpired   bool      `json:"isExpired" yaml:"isExpired"`
	SessionID   string    `json:"sessionId,omitempty" yaml:"sessionId,omitempty"`
}

CachedTokenInfo holds display metadata for a cached token.

func (*CachedTokenInfo) TimeUntilExpiry 

func (c *CachedTokenInfo) TimeUntilExpiry() time.Duration

TimeUntilExpiry returns the duration until this cached token expires.

type Capability 

type Capability string

Capability represents a feature or behavior that an auth handler supports. Capabilities allow CLI commands to dynamically adapt their flags and validation based on what each handler supports, enabling plugin-loaded handlers to work without hardcoded knowledge of their features. 

const (
	// CapScopesOnLogin indicates the handler supports specifying OAuth scopes at login time.
	// Both GitHub (device code) and Entra (device code/SP/WI) support this.
	CapScopesOnLogin Capability = "scopes_on_login"

	// CapScopesOnTokenRequest indicates the handler supports specifying per-request scopes
	// when acquiring tokens. Entra supports this (different resource scopes per request),
	// but GitHub does not (scopes are fixed at login time).
	CapScopesOnTokenRequest Capability = "scopes_on_token_request"

	// CapTenantID indicates the handler supports a tenant ID parameter.
	// Entra uses this for Azure AD tenant selection.
	CapTenantID Capability = "tenant_id"

	// CapHostname indicates the handler supports a hostname parameter.
	// GitHub uses this for GitHub Enterprise Server (GHES) support.
	CapHostname Capability = "hostname"

	// CapFederatedToken indicates the handler supports federated token input.
	// Entra uses this for workload identity (Kubernetes) authentication.
	CapFederatedToken Capability = "federated_token"

	// CapCallbackPort indicates the handler supports binding the OAuth callback
	// server to a specific port via --callback-port. Handlers that use the
	// authorization code + PKCE flow (Entra, GCP) advertise this capability.
	CapCallbackPort Capability = "callback_port"

	// CapFlowOverride indicates the handler supports runtime flow selection via --flow.
	CapFlowOverride Capability = "flow_override"
)

type Claims 

type Claims struct {
	Issuer    string    `` /* 130-byte string literal not displayed */
	Subject   string    `json:"subject,omitempty" yaml:"subject,omitempty" doc:"Subject identifier" example:"user@example.com" maxLength:"512"`
	TenantID  string    `` /* 139-byte string literal not displayed */
	ObjectID  string    `` /* 147-byte string literal not displayed */
	ClientID  string    `` /* 142-byte string literal not displayed */
	Email     string    `json:"email,omitempty" yaml:"email,omitempty" doc:"Email address of the identity" example:"user@example.com" maxLength:"320"`
	Name      string    `json:"name,omitempty" yaml:"name,omitempty" doc:"Display name of the identity" example:"Jane Doe" maxLength:"256"`
	Username  string    `json:"username,omitempty" yaml:"username,omitempty" doc:"Username or login name" example:"janedoe" maxLength:"256"`
	IssuedAt  time.Time `json:"issuedAt,omitempty" yaml:"issuedAt,omitempty" doc:"Time the token was issued"`
	ExpiresAt time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty" doc:"Time the token expires"`
}

Claims represents normalized identity claims from any auth handler.

func (*Claims) DisplayIdentity 

func (c *Claims) DisplayIdentity() string

DisplayIdentity returns the best available identity string for display.

func (*Claims) IsEmpty 

func (c *Claims) IsEmpty() bool

IsEmpty returns true if the claims have no meaningful data.

type Flow 

type Flow string

Flow represents an authentication flow type. 

const (
	FlowDeviceCode        Flow = "device_code"
	FlowInteractive       Flow = "interactive"
	FlowServicePrincipal  Flow = "service_principal"
	FlowWorkloadIdentity  Flow = "workload_identity"
	FlowPAT               Flow = "pat"
	FlowMetadata          Flow = "metadata"
	FlowGcloudADC         Flow = "gcloud_adc"
	FlowGitHubApp         Flow = "github_app"
	FlowClientCredentials Flow = "client_credentials"
)

func ParseFlow 

func ParseFlow(flowStr, handlerName string) (Flow, error)

ParseFlow converts a flow string to a Flow constant. If flowStr is empty, an empty Flow is returned (caller should auto-detect). handlerName is used to produce handler-specific error messages for unrecognised values.

type IdentityType 

type IdentityType string

IdentityType represents the type of authenticated identity. 

const (
	IdentityTypeUser             IdentityType = "user"
	IdentityTypeServicePrincipal IdentityType = "service-principal"
	IdentityTypeWorkloadIdentity IdentityType = "workload-identity"
)

type LoginOptions 

type LoginOptions struct {
	TenantID           string                                          `json:"tenantId,omitempty" yaml:"tenantId,omitempty"`
	Scopes             []string                                        `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	Flow               Flow                                            `json:"flow,omitempty" yaml:"flow,omitempty"`
	Timeout            time.Duration                                   `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	CallbackPort       int                                             `json:"callbackPort,omitempty" yaml:"callbackPort,omitempty"`
	DeviceCodeCallback func(userCode, verificationURI, message string) `json:"-" yaml:"-"`
}

LoginOptions configures the login process.

type Result 

type Result struct {
	Claims    *Claims   `json:"claims,omitempty" yaml:"claims,omitempty"`
	ExpiresAt time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
}

Result contains the result of a successful authentication.

type Status 

type Status struct {
	Authenticated bool         `json:"authenticated" yaml:"authenticated"`
	Reason        string       `json:"reason,omitempty" yaml:"reason,omitempty"`
	Claims        *Claims      `json:"claims,omitempty" yaml:"claims,omitempty"`
	ExpiresAt     time.Time    `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
	LastRefresh   time.Time    `json:"lastRefresh,omitempty" yaml:"lastRefresh,omitempty"`
	TenantID      string       `json:"tenantId,omitempty" yaml:"tenantId,omitempty"`
	IdentityType  IdentityType `json:"identityType,omitempty" yaml:"identityType,omitempty"`
	ClientID      string       `json:"clientId,omitempty" yaml:"clientId,omitempty"`
	TokenFile     string       `json:"tokenFile,omitempty" yaml:"tokenFile,omitempty"`
	Scopes        []string     `json:"scopes,omitempty" yaml:"scopes,omitempty"`
}

Status represents the current authentication state.

type Token 

type Token struct {
	AccessToken string    `json:"accessToken" yaml:"accessToken"` //nolint:gosec
	TokenType   string    `json:"tokenType" yaml:"tokenType"`
	ExpiresAt   time.Time `json:"expiresAt" yaml:"expiresAt"`
	Scope       string    `json:"scope,omitempty" yaml:"scope,omitempty"`
	CachedAt    time.Time `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty"`
	Flow        Flow      `json:"flow,omitempty" yaml:"flow,omitempty"`
	SessionID   string    `json:"sessionId,omitempty" yaml:"sessionId,omitempty"`
}

Token represents a short-lived access token.

func (*Token) IsExpired 

func (t *Token) IsExpired() bool

IsExpired returns true if the token has expired.

func (*Token) IsValidFor 

func (t *Token) IsValidFor(duration time.Duration) bool

IsValidFor returns true if the token will be valid for at least the specified duration.

func (*Token) TimeUntilExpiry 

func (t *Token) TimeUntilExpiry() time.Duration

TimeUntilExpiry returns the duration until the token expires.

type TokenLister 

type TokenLister interface {
	ListCachedTokens(ctx context.Context) ([]*CachedTokenInfo, error)
}

TokenLister is an optional interface for auth handlers that can enumerate cached tokens.

type TokenOptions 

type TokenOptions struct {
	Scope        string        `json:"scope,omitempty" yaml:"scope,omitempty"`
	MinValidFor  time.Duration `json:"minValidFor,omitempty" yaml:"minValidFor,omitempty"`
	ForceRefresh bool          `json:"forceRefresh,omitempty" yaml:"forceRefresh,omitempty"`
}

TokenOptions configures token acquisition.

type TokenPurger 

type TokenPurger interface {
	PurgeExpiredTokens(ctx context.Context) (int, error)
}

TokenPurger is an optional interface for auth handlers that can remove expired tokens.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.