Files
porto/Documentation/api/gserver_credentials.md
2026-10-01 10:34:57 -05:00

6.1 KiB

credentials

import "github.com/effective-security/porto/gserver/credentials"

Package credentials implements gRPC transport and per-RPC credentials for porto clients and servers.

NewBundle wraps a *tls.Config into a grpccredentials.Bundle whose PerRPCCredentials attaches an "authorization" metadata entry to every RPC. The token can be set statically with Bundle.UpdateAuthToken, refreshed on expiry through a CallerIdentity provider (Bundle.WithCallerIdentity, used for AWS STS presigned tokens), and for "DPoP" tokens a proof header is signed per call when a dpop.Signer is supplied with Bundle.WithDPoP. DPoP proofs bind POST to https://<authority><full method path>, using grpc-go's HTTPS credential audience and the RequestInfo in the RPC context. Missing or invalid audience/method information returns an error. The setters are safe to call while RPCs run, and concurrent RPCs that find the token expired share one provider call.

b := credentials.NewBundle(credentials.Config{TLSConfig: tlsCfg})
b.UpdateAuthToken(credentials.Token{TokenType: "Bearer", AccessToken: jwt})
conn, err := grpc.NewClient(target,
	grpc.WithTransportCredentials(b.TransportCredentials()),
	grpc.WithPerRPCCredentials(b.PerRPCCredentials()))

NewOauthAccess is a simpler PerRPCCredentials that sends a fixed, already formatted authorization value and requires a PrivacyAndIntegrity transport.

Index

Constants

TimeFormatISO8601 is the compact ISO 8601 layout ("yyyyMMddTHHmmssZ") used by AWS SigV4 presigned URLs and by TimeISO8601.

const TimeFormatISO8601 = "20060102T150405Z"

Variables

var (

    // TokenFieldNameGRPC is the gRPC metadata key carrying the access token.
    TokenFieldNameGRPC = "authorization"

    // CacheTTL is the default lifetime assigned to tokens from a
    // CallerIdentity that report no expiry, and the roles package AWS cache TTL.
    CacheTTL = 5 * time.Minute
)

func NewOauthAccess

func NewOauthAccess(token string) credentials.PerRPCCredentials

NewOauthAccess returns PerRPCCredentials that send token verbatim as the authorization metadata value (include the scheme, e.g. "Bearer x"). RPCs fail unless the connection provides PrivacyAndIntegrity security.

func TimeISO8601

func TimeISO8601(t time.Time) string

TimeISO8601 formats t using TimeFormatISO8601.

type Bundle

Bundle is a grpccredentials.Bundle whose PerRPCCredentials sends the configured token. The setters are safe to call concurrently with RPCs. See https://pkg.go.dev/google.golang.org/grpc/credentials.

type Bundle interface {
    grpccredentials.Bundle
    // UpdateAuthToken replaces the token sent with subsequent RPCs.
    UpdateAuthToken(token Token)
    // WithDPoP sets the signer used to add a "dpop" proof to RPCs whose
    // token type is "DPoP".
    WithDPoP(signer dpop.Signer)
    // WithCallerIdentity sets the provider used to obtain a new token when
    // the current one has expired. A token refresh already running is
    // discarded, and RPCs waiting for it ask the new provider.
    WithCallerIdentity(provider CallerIdentity)
}

func NewBundle

func NewBundle(cfg Config) Bundle

NewBundle constructs a Bundle whose transport credentials wrap cfg.TLSConfig and whose per-RPC credentials require transport security. NewWithMode is not supported and returns an error.

type CallerIdentity

CallerIdentity obtains a fresh access token on demand; it is consulted by the per-RPC credentials whenever the current token has expired. Concurrent RPCs that find the token expired share one GetCallerIdentity call, made with the context of the RPC that started it.

type CallerIdentity interface {
    // GetCallerIdentity returns a new token. If Expires is nil the token is
    // cached for CacheTTL.
    GetCallerIdentity(ctx context.Context) (*Token, error)
}

type Config

Config defines gRPC credential configuration.

type Config struct {
    // TLSConfig is the client or server TLS configuration wrapped by NewBundle.
    TLSConfig *tls.Config
}

type Token

Token is an access token sent as "<TokenType> <AccessToken>" in the authorization metadata.

type Token struct {
    // TokenType is the scheme, e.g. "Bearer", "DPoP" or "AWS4".
    TokenType string
    // AccessToken is the raw token value.
    AccessToken string
    // Expires is expiration time of the token
    Expires *time.Time
}

func (Token) Expired

func (t Token) Expired() bool

Expired reports whether the token is empty or expires within one minute. A token without Expires never expires.

Generated by gomarkdoc