grpcauthority

package
v3.1.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: GPL-3.0 Imports: 50 Imported by: 0

Documentation

Overview

Package grpcauthority adapts authority-side gRPC APIs to application services.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrBackendRefInvalid means the opaque handle or stored payload is malformed.
	ErrBackendRefInvalid = errors.New("backend reference is invalid")

	// ErrBackendRefExpired means Redis no longer has an active payload for the handle.
	ErrBackendRefExpired = errors.New("backend reference is expired")

	// ErrBackendRefPrincipalMismatch means the caller principal is not bound to the handle.
	ErrBackendRefPrincipalMismatch = errors.New("backend reference service principal mismatch")

	// ErrBackendRefEdgeClusterMismatch means the request came from a different edge cluster.
	ErrBackendRefEdgeClusterMismatch = errors.New("backend reference edge cluster mismatch")

	// ErrBackendRefOperationDenied means the handle is not valid for the requested operation.
	ErrBackendRefOperationDenied = errors.New("backend reference operation denied")

	// ErrBackendRefUsernameMismatch means the handle was issued for another user.
	ErrBackendRefUsernameMismatch = errors.New("backend reference username mismatch")
)
View Source 
var (
	// ErrIdempotencyKeyMissing means a mutating authority request did not carry a key.
	ErrIdempotencyKeyMissing = errors.New("idempotency key is required")

	// ErrIdempotencyKeyReplay means a mutating authority request reused a live key.
	ErrIdempotencyKeyReplay = errors.New("idempotency key replay")
)
View Source 
var ErrWebAuthnCredentialStateMismatch = errors.New("webauthn credential state mismatch")

ErrWebAuthnCredentialStateMismatch reports a stale or missing persistent credential during compare-and-update.

Functions

func NewServer 

func NewServer(deps ServerDeps) (*grpc.Server, error)

NewServer builds a gRPC authority server and registers its services.

func StartServer 

func StartServer(ctx context.Context, deps ServerDeps) (<-chan struct{}, error)

StartServer starts the optional gRPC authority listener and returns a done channel that is closed after graceful shutdown completes. A nil done channel means the listener is disabled.

func UnaryServerInterceptor 

func UnaryServerInterceptor(deps ServerDeps) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns the complete authority unary interceptor chain.

Types

type AuthorityIdentityInput 

type AuthorityIdentityInput struct {
	Context                    *identityv1.RequestContext
	Attributes                 *identityv1.AttributeRequest
	Credential                 *mfa.PersistentCredential
	OldCredential              *mfa.PersistentCredential
	NewCredential              *mfa.PersistentCredential
	Backend                    BackendRefPayload
	Operation                  AuthorityOperation
	Username                   string
	Code                       string
	PendingRegistrationID      string
	IdempotencyKey             string
	CredentialID               []byte
	Count                      uint32
	IncludeMFAState            bool
	IncludeWebAuthnCredentials bool
}

AuthorityIdentityInput carries mapped request data into the authority identity service.

type AuthorityIdentityResult 

type AuthorityIdentityResult struct {
	Status                     *commonv1.OperationStatus
	User                       *AuthorityUserSnapshot
	Credentials                []mfa.PersistentCredential
	Backend                    BackendRefPayload
	MFA                        AuthorityMFAState
	ExpiresAt                  time.Time
	PendingRegistrationID      string
	TOTPSecret                 string
	OTPAuthURL                 string
	MissingAttributes          []string
	DeniedAttributes           []string
	RecoveryCodes              []string
	RecoveryCodeCount          uint32
	RemainingRecoveryCodeCount uint32
	Valid                      bool
	Changed                    bool
}

AuthorityIdentityResult is the domain result returned to the transport adapter.

func (*AuthorityIdentityResult) GetBackend 

func (r *AuthorityIdentityResult) GetBackend() BackendRefPayload

GetBackend returns the effective backend-reference payload.

func (*AuthorityIdentityResult) GetChanged 

func (r *AuthorityIdentityResult) GetChanged() bool

GetChanged reports whether a mutating operation changed backend state.

func (*AuthorityIdentityResult) GetCredentials 

func (r *AuthorityIdentityResult) GetCredentials() []mfa.PersistentCredential

GetCredentials returns public WebAuthn credential records.

func (*AuthorityIdentityResult) GetDeniedAttributes 

func (r *AuthorityIdentityResult) GetDeniedAttributes() []string

GetDeniedAttributes returns requested attributes that were not released.

func (*AuthorityIdentityResult) GetExpiresAt 

func (r *AuthorityIdentityResult) GetExpiresAt() time.Time

GetExpiresAt returns the expiry of temporary setup material.

func (*AuthorityIdentityResult) GetMFA 

func (r *AuthorityIdentityResult) GetMFA() AuthorityMFAState

GetMFA returns the public MFA state.

func (*AuthorityIdentityResult) GetMissingAttributes 

func (r *AuthorityIdentityResult) GetMissingAttributes() []string

GetMissingAttributes returns requested attributes that were unavailable.

func (*AuthorityIdentityResult) GetOTPAuthURL 

func (r *AuthorityIdentityResult) GetOTPAuthURL() string

GetOTPAuthURL returns the provisioning URI for TOTP setup.

func (*AuthorityIdentityResult) GetPendingRegistrationID 

func (r *AuthorityIdentityResult) GetPendingRegistrationID() string

GetPendingRegistrationID returns the temporary TOTP registration handle.

func (*AuthorityIdentityResult) GetRecoveryCodeCount 

func (r *AuthorityIdentityResult) GetRecoveryCodeCount() uint32

GetRecoveryCodeCount returns the number of active recovery codes.

func (*AuthorityIdentityResult) GetRecoveryCodes 

func (r *AuthorityIdentityResult) GetRecoveryCodes() []string

GetRecoveryCodes returns newly generated recovery codes.

func (*AuthorityIdentityResult) GetRemainingRecoveryCodeCount 

func (r *AuthorityIdentityResult) GetRemainingRecoveryCodeCount() uint32

GetRemainingRecoveryCodeCount returns the recovery-code count after a use attempt.

func (*AuthorityIdentityResult) GetTOTPSecret 

func (r *AuthorityIdentityResult) GetTOTPSecret() string

GetTOTPSecret returns one-time TOTP setup material.

func (*AuthorityIdentityResult) GetUser 

func (r *AuthorityIdentityResult) GetUser() *AuthorityUserSnapshot

GetUser returns the released user snapshot.

func (*AuthorityIdentityResult) GetValid 

func (r *AuthorityIdentityResult) GetValid() bool

GetValid returns the verification result for MFA checks.

type AuthorityIdentityService 

type AuthorityIdentityService interface {
	ResolveUser(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	GetMFAState(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	BeginTOTPRegistration(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	FinishTOTPRegistration(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	VerifyTOTP(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	DeleteTOTP(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	GenerateRecoveryCodes(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	UseRecoveryCode(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	DeleteRecoveryCodes(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	GetWebAuthnCredentials(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	SaveWebAuthnCredential(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	UpdateWebAuthnCredential(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
	DeleteWebAuthnCredential(ctx context.Context, input AuthorityIdentityInput) (*AuthorityIdentityResult, error)
}

AuthorityIdentityService runs authority-side identity operations behind the transport adapter.

func NewBackendManagerIdentityService 

func NewBackendManagerIdentityService(deps BackendManagerIdentityServiceDeps) AuthorityIdentityService

NewBackendManagerIdentityService constructs the default authority identity service.

type AuthorityMFAState 

type AuthorityMFAState struct {
	Credentials       []mfa.PersistentCredential
	PreferredMethod   string
	RecoveryCodeCount uint32
	HasTOTP           bool
	HasWebAuthn       bool
}

AuthorityMFAState contains public MFA state only.

type AuthorityOperation 

type AuthorityOperation string

AuthorityOperation names one authority-side operation for scope and backend-ref checks. 

const (
	AuthorityOperationAuthenticate             AuthorityOperation = "authenticate"
	AuthorityOperationLookupIdentity           AuthorityOperation = "lookup_identity"
	AuthorityOperationListAccounts             AuthorityOperation = "list_accounts"
	AuthorityOperationResolveUser              AuthorityOperation = "resolve_user"
	AuthorityOperationGetMFAState              AuthorityOperation = "get_mfa_state"
	AuthorityOperationBeginTOTPRegistration    AuthorityOperation = "begin_totp_registration"
	AuthorityOperationFinishTOTPRegistration   AuthorityOperation = "finish_totp_registration"
	AuthorityOperationVerifyTOTP               AuthorityOperation = "verify_totp"
	AuthorityOperationDeleteTOTP               AuthorityOperation = "delete_totp"
	AuthorityOperationGenerateRecoveryCodes    AuthorityOperation = "generate_recovery_codes"
	AuthorityOperationUseRecoveryCode          AuthorityOperation = "use_recovery_code"
	AuthorityOperationDeleteRecoveryCodes      AuthorityOperation = "delete_recovery_codes"
	AuthorityOperationGetWebAuthnCredentials   AuthorityOperation = "get_webauthn_credentials"
	AuthorityOperationSaveWebAuthnCredential   AuthorityOperation = "save_webauthn_credential"
	AuthorityOperationUpdateWebAuthnCredential AuthorityOperation = "update_webauthn_credential"
	AuthorityOperationDeleteWebAuthnCredential AuthorityOperation = "delete_webauthn_credential"
)

Authority operation constants identify supported authority-side RPC families.

type AuthorityUserSnapshot 

type AuthorityUserSnapshot struct {
	Attributes              map[string][]string
	Backend                 BackendRefPayload
	MFA                     AuthorityMFAState
	Username                string
	Account                 string
	UniqueUserID            string
	DisplayName             string
	Groups                  []string
	GroupDistinguishedNames []string
}

AuthorityUserSnapshot contains released identity data for gRPC identity responses.

type BackendManagerIdentityServiceDeps 

type BackendManagerIdentityServiceDeps struct {
	AuthService core.AuthApplicationService
	AuthDeps    core.AuthDeps
}

BackendManagerIdentityServiceDeps contains domain dependencies for authority identity operations.

type BackendRefPayload 

type BackendRefPayload struct {
	IssuedAt           time.Time            `json:"issued_at"`
	ExpiresAt          time.Time            `json:"expires_at"`
	LastUsedAt         time.Time            `json:"last_used_at"`
	AllowedOperations  []AuthorityOperation `json:"allowed_operations,omitempty"`
	Type               string               `json:"type"`
	Name               string               `json:"name"`
	Protocol           string               `json:"protocol"`
	Authority          string               `json:"authority"`
	Username           string               `json:"username"`
	Account            string               `json:"account,omitempty"`
	UniqueUserID       string               `json:"unique_user_id,omitempty"`
	DisplayName        string               `json:"display_name,omitempty"`
	ServicePrincipal   string               `json:"service_principal"`
	MTLSClientIdentity string               `json:"mtls_client_identity,omitempty"`
	EdgeClusterID      string               `json:"edge_cluster_id"`
	EdgeInstanceID     string               `json:"edge_instance_id,omitempty"`
	EdgeRequestID      string               `json:"edge_request_id,omitempty"`
	AuthorityRequestID string               `json:"authority_request_id,omitempty"`
	SchemaVersion      int                  `json:"schema_version"`
}

BackendRefPayload is the Redis-backed authority payload behind an opaque backend reference.

type BackendRefStore 

type BackendRefStore interface {
	Issue(ctx context.Context, payload BackendRefPayload) (*commonv1.BackendRef, error)
	Validate(ctx context.Context, ref *commonv1.BackendRef, validation BackendRefValidation) (*BackendRefPayload, error)
}

BackendRefStore issues and validates Redis-backed backend-reference handles.

type BackendRefValidation 

type BackendRefValidation struct {
	Operation          AuthorityOperation
	Username           string
	ServicePrincipal   string
	MTLSClientIdentity string
	EdgeClusterID      string
}

BackendRefValidation contains request-time bindings that must match the stored payload.

type Handler 

type Handler struct {
	authv1.UnimplementedAuthServiceServer
	identityv1.UnimplementedIdentityBackendServiceServer
	// contains filtered or unexported fields
}

Handler implements the authority-side gRPC service contracts.

func New 

func New(service core.AuthApplicationService) *Handler

New constructs the authority handler around the application service.

func NewWithResolver 

func NewWithResolver(service core.AuthApplicationService, resolver localization.MessageResolver) *Handler

NewWithResolver constructs the authority handler with response localization.

func NewWithServices 

func NewWithServices(
	service core.AuthApplicationService,
	resolver localization.MessageResolver,
	identityService AuthorityIdentityService,
	backendRefs BackendRefStore,
) *Handler

NewWithServices constructs the authority handler with all application services.

func (*Handler) Authenticate 

func (h *Handler) Authenticate(ctx context.Context, request *authv1.AuthRequest) (*authv1.AuthResponse, error)

Authenticate maps the gRPC request into the auth application service.

func (*Handler) BeginTOTPRegistration 

func (h *Handler) BeginTOTPRegistration(
	ctx context.Context,
	request *identityv1.BeginTOTPRegistrationRequest,
) (*identityv1.BeginTOTPRegistrationResponse, error)

BeginTOTPRegistration starts a TOTP registration through the authority service.

func (*Handler) DeleteRecoveryCodes 

func (h *Handler) DeleteRecoveryCodes(
	ctx context.Context,
	request *identityv1.DeleteRecoveryCodesRequest,
) (*identityv1.MFAWriteResponse, error)

DeleteRecoveryCodes removes all recovery codes for a user.

func (*Handler) DeleteTOTP 

func (h *Handler) DeleteTOTP(
	ctx context.Context,
	request *identityv1.DeleteTOTPRequest,
) (*identityv1.MFAWriteResponse, error)

DeleteTOTP deletes persisted TOTP state for the selected backend.

func (*Handler) DeleteWebAuthnCredential 

func (h *Handler) DeleteWebAuthnCredential(
	ctx context.Context,
	request *identityv1.DeleteWebAuthnCredentialRequest,
) (*identityv1.MFAWriteResponse, error)

DeleteWebAuthnCredential deletes a WebAuthn credential by identifier.

func (*Handler) FinishTOTPRegistration 

func (h *Handler) FinishTOTPRegistration(
	ctx context.Context,
	request *identityv1.FinishTOTPRegistrationRequest,
) (*identityv1.MFAWriteResponse, error)

FinishTOTPRegistration persists a verified TOTP registration.

func (*Handler) GenerateRecoveryCodes 

func (h *Handler) GenerateRecoveryCodes(
	ctx context.Context,
	request *identityv1.GenerateRecoveryCodesRequest,
) (*identityv1.GenerateRecoveryCodesResponse, error)

GenerateRecoveryCodes creates a fresh recovery-code set.

func (*Handler) GetMFAState 

func (h *Handler) GetMFAState(
	ctx context.Context,
	request *identityv1.GetMFAStateRequest,
) (*identityv1.MFAStateResponse, error)

GetMFAState returns public MFA state for a validated backend reference.

func (*Handler) GetWebAuthnCredentials 

func (h *Handler) GetWebAuthnCredentials(
	ctx context.Context,
	request *identityv1.GetWebAuthnCredentialsRequest,
) (*identityv1.WebAuthnCredentialsResponse, error)

GetWebAuthnCredentials returns public WebAuthn credentials.

func (*Handler) ListAccounts 

func (h *Handler) ListAccounts(
	ctx context.Context,
	request *authv1.ListAccountsRequest,
) (*authv1.ListAccountsResponse, error)

ListAccounts maps the gRPC request into the account-provider application path.

func (*Handler) LookupIdentity 

func (h *Handler) LookupIdentity(
	ctx context.Context,
	request *authv1.LookupIdentityRequest,
) (*authv1.AuthResponse, error)

LookupIdentity maps the gRPC request into the trusted identity lookup application path.

func (*Handler) ResolveUser 

func (h *Handler) ResolveUser(
	ctx context.Context,
	request *identityv1.ResolveUserRequest,
) (*identityv1.UserSnapshotResponse, error)

ResolveUser resolves a user and releases allowed identity data.

func (*Handler) SaveWebAuthnCredential 

func (h *Handler) SaveWebAuthnCredential(
	ctx context.Context,
	request *identityv1.SaveWebAuthnCredentialRequest,
) (*identityv1.MFAWriteResponse, error)

SaveWebAuthnCredential persists a new WebAuthn credential.

func (*Handler) UpdateWebAuthnCredential 

func (h *Handler) UpdateWebAuthnCredential(
	ctx context.Context,
	request *identityv1.UpdateWebAuthnCredentialRequest,
) (*identityv1.MFAWriteResponse, error)

UpdateWebAuthnCredential updates an existing WebAuthn credential.

func (*Handler) UseRecoveryCode 

func (h *Handler) UseRecoveryCode(
	ctx context.Context,
	request *identityv1.UseRecoveryCodeRequest,
) (*identityv1.UseRecoveryCodeResponse, error)

UseRecoveryCode verifies and consumes a recovery code.

func (*Handler) VerifyTOTP 

func (h *Handler) VerifyTOTP(
	ctx context.Context,
	request *identityv1.VerifyTOTPRequest,
) (*identityv1.VerifyTOTPResponse, error)

VerifyTOTP verifies a TOTP code against the selected backend.

type RedisBackendRefStore 

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

RedisBackendRefStore stores opaque authority backend references in Redis.

func NewRedisBackendRefStore 

func NewRedisBackendRefStore(client rediscli.Client, options RedisBackendRefStoreOptions) *RedisBackendRefStore

NewRedisBackendRefStore constructs a Redis-backed authority reference store.

func (*RedisBackendRefStore) Issue 

func (s *RedisBackendRefStore) Issue(ctx context.Context, payload BackendRefPayload) (*commonv1.BackendRef, error)

Issue persists an authority payload and returns its opaque public handle.

func (*RedisBackendRefStore) Validate 

func (s *RedisBackendRefStore) Validate(
	ctx context.Context,
	ref *commonv1.BackendRef,
	validation BackendRefValidation,
) (*BackendRefPayload, error)

Validate resolves and checks an authority reference without trusting caller-visible echo fields.

type RedisBackendRefStoreOptions 

type RedisBackendRefStoreOptions struct {
	KeyPrefix string
	Authority string
	TTL       time.Duration
}

RedisBackendRefStoreOptions configures authority backend-reference persistence.

type ServerDeps 

type ServerDeps struct {
	Cfg             config.File
	CurrentConfig   func() config.File
	Env             config.Environment
	Logger          *slog.Logger
	Redis           rediscli.Client
	AccountCache    *accountcache.Manager
	Channel         backend.Channel
	AuthService     core.AuthApplicationService
	IdentityService AuthorityIdentityService
	BackendRefs     BackendRefStore
	MessageResolver localization.MessageResolver
	OIDCValidator   oidcbearer.TokenValidator
	Listener        net.Listener
}

ServerDeps contains the dependencies required by the gRPC authority server.

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.