Help us shape the future of Go! Take the 2026 Go Developer Survey

oauth

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package oauth resolves ACL facts from a dedicated, trusted OAuth/OIDC issuer.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bearer

func Bearer(ctx context.Context) string

Bearer returns the unverified request credential. Only a trusted verifier may interpret it; possession of this context value never establishes authority.

func NewCapabilityPermissionResolver

func NewCapabilityPermissionResolver(bindings []CapabilityPermissionBinding) (func(context.Context, authz.Facts, authz.Entity, string) (bool, error), error)

func NewEntityRoleResolver

func NewEntityRoleResolver(bindings []EntityRoleBinding) (func(context.Context, authz.Facts, authz.Entity) ([]string, error), error)

func NewJWKSKeyfunc

func NewJWKSKeyfunc(config JWKSConfig) (jwt.Keyfunc, error)

NewJWKSKeyfunc resolves asymmetric verification keys from a trusted issuer endpoint. It refreshes on the configured lease; an untrusted unknown key ID cannot force a network fetch on every request. Failed refreshes discard the old key set.

func NewLeasedCapabilityPermissionResolver

func NewLeasedCapabilityPermissionResolver(bindings []CapabilityPermissionBinding, permission func(context.Context, authz.Facts, authz.Entity, string) (bool, time.Time, error)) (func(context.Context, authz.Facts, authz.Entity, string) (bool, time.Time, error), error)

NewLeasedCapabilityPermissionResolver maps configured capabilities to an injected authority and preserves its remaining lease.

func VerifyToken

func VerifyToken(ctx context.Context, config Config, claims jwt.Claims) (string, error)

VerifyToken validates the generic signed OAuth/OIDC credential contract. The caller supplies the claim type; provider-specific claims remain host code.

func WithBearer

func WithBearer(ctx context.Context, token string) context.Context

WithBearer carries the incoming credential to Resolve; it does not mark the token verified. Resolve validates its signature and registered claims.

Types

type CapabilityPermissionBinding

type CapabilityPermissionBinding struct {
	EntityType string `json:"entityType"`
	Capability string `json:"capability"`
	Permission string `json:"permission"`
}

CapabilityPermissionBinding maps one authored UI capability to one exact identity-provider entity permission. Names are deployment configuration.

type Claims

type Claims struct {
	EntityPermissions []access.EntityPermission `json:"entityPermissions,omitempty"`
	jwt.RegisteredClaims
	AccountID        string   `json:"accountId,omitempty"`
	MembershipGroups []string `json:"membershipGroups,omitempty"`
	Tenant           string   `json:"tenant"`
	Roles            []string `json:"roles"`
	Exposures        []string `json:"exposures"`
	Scope            string   `json:"scope,omitempty"`
	// EntityGroups is the canonical typed allowedEntities claim.
	EntityGroups access.EntityGroups `json:"-"`
	// AllowedEntities accepts legacy flat Go callers. Tokens are serialized in
	// grouped form; received flat tokens are validated and normalized.
	AllowedEntities []access.Entity `json:"-"`
}

func (Claims) MarshalJSON

func (c Claims) MarshalJSON() ([]byte, error)

func (*Claims) UnmarshalJSON

func (c *Claims) UnmarshalJSON(raw []byte) error

type Config

type Config struct {
	Issuer     string
	Audience   string
	Algorithms []string
	Keyfunc    jwt.Keyfunc
}

Config separates the authorization issuer/audience from authoring or model credentials. Keyfunc must use deployment-owned keys/JWKS, never a token URL.

type EntityEvaluationScopeProvider

type EntityEvaluationScopeProvider struct {
	Client     gating.EntityPermissionProvider
	Principals gating.PrincipalResolver
	Permission func(authz.Request, authz.Document) (string, error)
}

EntityEvaluationScopeProvider delegates entity bounds to an injected authority. Permission is a trusted host mapping (typically read for scope admission); mandatory action-specific gates continue to be evaluated independently.

func (*EntityEvaluationScopeProvider) ResolveSelectedScope

func (p *EntityEvaluationScopeProvider) ResolveSelectedScope(ctx context.Context, request authz.Request, document authz.Document, facts authz.Facts) (authz.SelectedScopeDecision, error)

type EntityRoleBinding

type EntityRoleBinding struct {
	EntityType string `json:"entityType"`
	Permission string `json:"permission"`
	Role       string `json:"role"`
}

EntityRoleBinding exposes one named IdP entity permission as one UI role. Both names are host configuration; no permission is implicitly a role.

type FactEntityPermissionProvider

type FactEntityPermissionProvider struct{ Principals gating.PrincipalResolver }

FactEntityPermissionProvider checks the exact named permissions returned by a verified identity provider. Entity membership alone is not sufficient.

func (*FactEntityPermissionProvider) CheckEntityPermission

func (p *FactEntityPermissionProvider) CheckEntityPermission(ctx context.Context, request gating.ProviderRequest) (gating.Decision, error)

type HTTPAccountRequirement

type HTTPAccountRequirement struct {
	ResourceType string `json:"resourceType"`
	Permission   string `json:"permission"`
}

type HTTPEvaluationConfig

type HTTPEvaluationConfig struct {
	// SourceClockSkew is explicit tolerance for the evaluation endpoint only; zero remains strict.
	SourceClockSkew        string                            `json:"sourceClockSkew,omitempty"`
	URL                    string                            `json:"url"`
	CacheTTL               string                            `json:"cacheTTL,omitempty"`
	MaxEntries             int                               `json:"maxEntries,omitempty"`
	Mapping                HTTPEvaluationMapping             `json:"mapping"`
	EntitlementProviderRef string                            `json:"entitlementProviderRef,omitempty"`
	Entitlements           map[string]HTTPAccountRequirement `json:"entitlements,omitempty"`
	Client                 *http.Client                      `json:"-"`
}

Evaluation names are ordinary endpoint field paths, not protocol extensions. Entitlement bindings keep business requirement names in operator configuration.

type HTTPEvaluationMapping

type HTTPEvaluationMapping struct {
	RequestEntityType   string `json:"requestEntityType"`
	RequestEntityIDs    string `json:"requestEntityIds"`
	RequestPermissions  string `json:"requestPermissions"`
	RequestScope        string `json:"requestScope,omitempty"`
	RequestResourceType string `json:"requestResourceType,omitempty"`
	IntegerEntityIDs    bool   `json:"integerEntityIds,omitempty"`
	Status              string `json:"status,omitempty"`
	StatusValue         string `json:"statusValue,omitempty"`
	Issuer              string `json:"issuer"`
	Subject             string `json:"subject"`
	UserID              string `json:"userId,omitempty"`
	AccountID           string `json:"accountId"`
	EntityType          string `json:"entityType"`
	Results             string `json:"results"`
	ResultEntityID      string `json:"resultEntityId"`
	ResultPermissions   string `json:"resultPermissions"`
	Scope               string `json:"scope,omitempty"`
	ResourceType        string `json:"resourceType,omitempty"`
	Permissions         string `json:"permissions,omitempty"`
	AuthorityRevision   string `json:"authorityRevision"`
	EvaluatedAt         string `json:"evaluatedAt"`
	ValidUntil          string `json:"validUntil"`
}

type HTTPEvaluationProvider

type HTTPEvaluationProvider struct {
	// contains filtered or unexported fields
}

func (*HTTPEvaluationProvider) CheckEntitlement

func (*HTTPEvaluationProvider) CheckEntityPermission

func (e *HTTPEvaluationProvider) CheckEntityPermission(ctx context.Context, r gating.ProviderRequest) (gating.Decision, error)

func (*HTTPEvaluationProvider) PermissionWithLease

func (e *HTTPEvaluationProvider) PermissionWithLease(ctx context.Context, facts authz.Facts, entity authz.Entity, permission string) (bool, time.Time, error)

type HTTPIdentityConfig

type HTTPIdentityConfig struct {
	// Keyfunc is a trusted process binding, never decoded from an identity
	// document. Embedders can reuse the host verifier instead of configuring JWKS twice.
	Keyfunc jwt.Keyfunc `json:"-"`

	Kind                string   `json:"kind"`
	Issuer              string   `json:"issuer"`
	Audience            string   `json:"audience"`
	Algorithms          []string `json:"algorithms"`
	UserInfoURL         string   `json:"userInfoUrl"`
	JWKSURL             string   `json:"jwksUrl"`
	JWKSRefreshInterval string   `json:"jwksRefreshInterval"`
	FactLease           string   `json:"factLease"`
	// UserInfoCacheTTL defaults to fifteen minutes with a signed JWT account
	// mapping. Without that mapping, omission preserves uncached legacy reads;
	// an explicitly positive TTL still requires the signed account mapping.
	UserInfoCacheTTL        string              `json:"userInfoCacheTTL,omitempty"`
	UserInfoCacheMaxEntries int                 `json:"userInfoCacheMaxEntries,omitempty"`
	Now                     func() time.Time    `json:"-"`
	SourceClockSkew         string              `json:"sourceClockSkew,omitempty"`
	TenantByAccount         map[string]string   `json:"tenantByAccount,omitempty"`
	TenantForAllAccounts    string              `json:"tenantForAllAccounts,omitempty"`
	Mapping                 HTTPIdentityMapping `json:"mapping"`
	Query                   map[string]string   `json:"query,omitempty"`
	Client                  *http.Client        `json:"-"`
}

HTTPIdentityConfig is operator-owned. Mapping paths select fields from the independently verified JWT and the configured identity endpoint, never UI input.

type HTTPIdentityMapping

type HTTPIdentityMapping struct {
	Subject            string            `json:"subject"`
	UserID             string            `json:"userId,omitempty"`
	AccountID          string            `json:"accountId"`
	JWTUserID          string            `json:"jwtUserId,omitempty"`
	JWTAccountID       string            `json:"jwtAccountId,omitempty"`
	Roles              string            `json:"roles,omitempty"`
	Exposures          string            `json:"exposures,omitempty"`
	MembershipGroups   string            `json:"membershipGroups,omitempty"`
	EntityPermissions  string            `json:"entityPermissions,omitempty"`
	Status             string            `json:"status,omitempty"`
	StatusValue        string            `json:"statusValue,omitempty"`
	AuthorityRevision  string            `json:"authorityRevision,omitempty"`
	EvaluatedAt        string            `json:"evaluatedAt,omitempty"`
	ValidUntil         string            `json:"validUntil,omitempty"`
	RequireSourceLease bool              `json:"requireSourceLease,omitempty"`
	AccountProjection  map[string]string `json:"accountProjection,omitempty"`
}

type HTTPIdentityProvider

type HTTPIdentityProvider struct {
	// contains filtered or unexported fields
}

func (*HTTPIdentityProvider) Account

func (p *HTTPIdentityProvider) Account(ctx context.Context, expected authz.Facts) (string, error)

func (*HTTPIdentityProvider) AuthorityRevision

func (p *HTTPIdentityProvider) AuthorityRevision(ctx context.Context, expected authz.Facts, account string) (string, time.Time, error)

func (*HTTPIdentityProvider) BeginDecision

func (p *HTTPIdentityProvider) BeginDecision(ctx context.Context) (context.Context, func() error, error)

func (*HTTPIdentityProvider) BeginFreshOperation added in v0.1.1

func (p *HTTPIdentityProvider) BeginFreshOperation(ctx context.Context) (context.Context, func() error, error)

BeginFreshOperation starts a control-plane operation from freshly verified userinfo. It never extends a cached decision or reuses an enclosing scope. Business calls still belong to the producer; this is for renewing metadata admission while an ordinary profile cache entry remains valid.

func (*HTTPIdentityProvider) BeginMetadataRead

func (p *HTTPIdentityProvider) BeginMetadataRead(ctx context.Context) (context.Context, func() error, error)

func (*HTTPIdentityProvider) BeginOperation

func (p *HTTPIdentityProvider) BeginOperation(ctx context.Context) (context.Context, func() error, error)

BeginOperation captures one verified userinfo profile for an operation. Local identity/display reads reuse it; the actual data producer remains responsible for authorizing business requests. Finish closes the scope without fetching userinfo again or comparing business roles after a producer call. No profile is retained outside this context; token/account/expiry checks still apply.

func (*HTTPIdentityProvider) CopyDecision

func (p *HTTPIdentityProvider) CopyDecision(ctx, scoped context.Context) (context.Context, error)

CopyDecision preserves the caller's request values while carrying this provider's active, credential-bound decision scope. It never copies facts, extends the scope lease, or upgrades a metadata-only scope.

func (*HTTPIdentityProvider) MetadataReadActive

func (p *HTTPIdentityProvider) MetadataReadActive(ctx context.Context) bool

func (*HTTPIdentityProvider) PermissionWithLease

func (p *HTTPIdentityProvider) PermissionWithLease(ctx context.Context, expected authz.Facts, entity authz.Entity, permission string) (bool, time.Time, error)

func (*HTTPIdentityProvider) ProjectAccount

func (p *HTTPIdentityProvider) ProjectAccount(ctx context.Context, expected authz.Facts, account string) (map[string]any, error)

func (*HTTPIdentityProvider) Resolve

func (p *HTTPIdentityProvider) Resolve(ctx context.Context) (authz.Facts, error)

func (*HTTPIdentityProvider) ResolveIdentityPrincipal

func (p *HTTPIdentityProvider) ResolveIdentityPrincipal(ctx context.Context) (gating.Principal, error)

ResolveIdentityPrincipal grants identity only, never role/feature/entity authority. A configured signed account claim permits zero-userinfo template delivery; an unproven account cannot silently become a trusted native context.

func (*HTTPIdentityProvider) ResolvePrincipal

func (p *HTTPIdentityProvider) ResolvePrincipal(ctx context.Context) (gating.Principal, error)

func (*HTTPIdentityProvider) WithoutDecision

func (p *HTTPIdentityProvider) WithoutDecision(ctx context.Context) context.Context

func (*HTTPIdentityProvider) WithoutMetadataRead

func (p *HTTPIdentityProvider) WithoutMetadataRead(ctx context.Context) context.Context

type HTTPProviders

type HTTPProviders struct {
	NativeWindowIdentity func(context.Context) (gating.Principal, error)
	Entitlements         map[string]gating.EntitlementProvider
	AccountProjection    func(context.Context, authz.Facts, string) (map[string]any, error)
	DecisionScope        interface {
		BeginDecision(context.Context) (context.Context, func() error, error)
		WithoutDecision(context.Context) context.Context
		MetadataReadActive(context.Context) bool
	}
	MetadataScope interface {
		BeginMetadataRead(context.Context) (context.Context, func() error, error)
		WithoutMetadataRead(context.Context) context.Context
	}
	Identity            IdentityAuthority
	AllowsTenant        func(string) bool
	EntityPermissions   gating.EntityPermissionProvider
	PermissionWithLease func(context.Context, authz.Facts, authz.Entity, string) (bool, time.Time, error)
}

type IdentityAuthority

type IdentityAuthority interface {
	authz.Provider
	gating.PrincipalResolver
	Account(context.Context, authz.Facts) (string, error)
	AuthorityRevision(context.Context, authz.Facts, string) (string, time.Time, error)
}

IdentityAuthority is implemented by a trusted host binding. Account and policy tenant mappings are explicit; neither is derived by this package.

type IdentityProvider

type IdentityProvider struct {
	// contains filtered or unexported fields
}

IdentityProvider supplies verified registered identity claims only. It grants no tenant membership, roles, exposures, or entity authority.

func NewIdentity

func NewIdentity(config Config) (*IdentityProvider, error)

func (*IdentityProvider) Resolve

func (p *IdentityProvider) Resolve(ctx context.Context) (authz.Facts, error)

type JWKSConfig

type JWKSConfig struct {
	URL             string
	RefreshInterval time.Duration
	Client          *http.Client
	Now             func() time.Time
}

JWKSConfig is deployment-owned. The configured URL is never selected by a token, caller payload or user-info response.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

func New

func New(config Config) (*Provider, error)

func (*Provider) Account

func (p *Provider) Account(ctx context.Context, expected authz.Facts) (string, error)

Account rechecks the generic signed principal against a consumer's snapshot. Account IDs are opaque strings; their meaning is owned by the trusted issuer.

func (*Provider) AuthorityRevision

func (p *Provider) AuthorityRevision(ctx context.Context, expected authz.Facts, accountID string) (string, time.Time, error)

AuthorityRevision supplies the credential revision and verified expiry for the same generic signed account authority used by ACL facts.

func (*Provider) Resolve

func (p *Provider) Resolve(ctx context.Context) (access.Facts, error)

func (*Provider) ResolvePrincipal

func (p *Provider) ResolvePrincipal(ctx context.Context) (gating.Principal, error)

ResolvePrincipal accepts account context only when the trusted issuer signed an explicit accountId. Tenant ownership and account membership stay distinct.

type StaticAuthorization

type StaticAuthorization struct {
	EntityCapabilityWithLease func(context.Context, authz.Facts, authz.Entity, string) (bool, time.Time, error)
	Identity                  IdentityAuthority
	ACL                       *authz.Service
	Gates                     *gating.Evaluator
	Policies                  *authz.StaticStore
	Requirements              *gating.StaticStore
	EntityCapability          func(context.Context, authz.Facts, authz.Entity, string) (bool, error)
	EntityRoleProjection      func(context.Context, authz.Facts, authz.Entity) ([]string, error)
}

func NewStaticAuthorization

func NewStaticAuthorization(config StaticAuthorizationConfig) (*StaticAuthorization, error)

type StaticAuthorizationConfig

type StaticAuthorizationConfig struct {
	Identity IdentityAuthority
	// AllowsTenant validates policy namespaces using trusted host configuration.
	AllowsTenant              func(string) bool
	EntityCapabilityWithLease func(context.Context, authz.Facts, authz.Entity, string) (bool, time.Time, error)
	Policies                  []authz.Document
	Requirements              []gating.Binding
	EntityPermissions         gating.EntityPermissionProvider
	CapabilityPermissions     []CapabilityPermissionBinding
	EntityRoles               []EntityRoleBinding
	Entitlements              map[string]gating.EntitlementProvider
}

StaticAuthorizationConfig assembles trusted policies with injected authorities. Hosts supply account, capability, and policy namespace mappings.

Jump to

Keyboard shortcuts

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