auth

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: May 24, 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.

func ProfileFromContext added in v0.6.0 

func ProfileFromContext(ctx context.Context) string

ProfileFromContext retrieves the profile name from the context. Returns an empty string if no profile is set (default profile).

func WithProfile added in v0.6.0 

func WithProfile(ctx context.Context, profile string) context.Context

WithProfile returns a new context with the given profile name attached. An empty string represents the default (unnamed) profile.

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"`
	Flow          Flow         `json:"flow,omitempty" yaml:"flow,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.