Documentation
¶
Overview ¶
Package tokenauth lets server-sdk-go service clients run without an API secret: each request is authorized with a short-lived token minted elsewhere (the Public API, under user-session auth) carrying exactly the grants that call needs.
The SDK signs a token for every call from its key/secret, choosing grants per method (e.g. RoomList for ListRooms, SIP admin for SIP calls). Clients built with Placeholder credentials still do that, but the secret is a well-known placeholder; the twirp hook from ClientOptions decodes the placeholder token to recover the requested grants, swaps in a minted token with the same grants, and sends that instead. The SDK's own grant mapping stays the single source of truth, so no per-method table lives here.
Index ¶
- Constants
- func CheckGrants(token string, want *auth.ClaimGrants) error
- func ConnectToRoom(ctx context.Context, src *CachingTokenSource, url string, ...) (*lksdk.Room, error)
- func IsPlaceholder(apiKey string) bool
- func JoinRoom(ctx context.Context, room *lksdk.Room, src *CachingTokenSource, url string, ...) error
- func ParticipantGrants(info lksdk.ConnectInfo) *auth.ClaimGrants
- func Sign(ctx context.Context, src *CachingTokenSource, apiKey, apiSecret string, ...) (string, error)
- type CachingTokenSource
- func (s *CachingTokenSource) ClientOptions() []twirp.ClientOption
- func (s *CachingTokenSource) Exchange(ctx context.Context, placeholderToken string, ttl time.Duration) (string, error)
- func (s *CachingTokenSource) Fetch(ctx context.Context, grants *auth.ClaimGrants, ttl time.Duration) (string, time.Time, error)
- func (s *CachingTokenSource) Transport(base http.RoundTripper) http.RoundTripper
- type TokenSource
Constants ¶
const ( // PlaceholderAPIKey and PlaceholderAPISecret are passed to SDK client // constructors in place of real credentials. Tokens signed with them are // never sent: the hook replaces them before the request leaves. PlaceholderAPIKey = "lk-minted-placeholder" PlaceholderAPISecret = "lk-minted-placeholder-secret-not-a-real-credential" // DefaultTTL is the lifetime requested for tokens authorizing SDK calls. DefaultTTL = 10 * time.Minute )
Variables ¶
This section is empty.
Functions ¶
func CheckGrants ¶
func CheckGrants(token string, want *auth.ClaimGrants) error
CheckGrants reports an error if a minted token lacks any claim that was requested. The Public API drops claims it doesn't know (e.g. a grant newer than the server), which would otherwise surface later as a confusing permission error from LiveKit. The token's signature isn't checked; only the issuer could, and the caller is the one asking.
func ConnectToRoom ¶
func ConnectToRoom(ctx context.Context, src *CachingTokenSource, url string, info lksdk.ConnectInfo, callback *lksdk.RoomCallback, opts ...lksdk.ConnectOption) (*lksdk.Room, error)
ConnectToRoom is lksdk.ConnectToRoom with JoinRoom's token handling.
func IsPlaceholder ¶
IsPlaceholder reports whether apiKey is the placeholder, i.e. the client's credentials can't sign anything locally (participant tokens, webhooks, …).
func JoinRoom ¶
func JoinRoom(ctx context.Context, room *lksdk.Room, src *CachingTokenSource, url string, info lksdk.ConnectInfo, opts ...lksdk.ConnectOption) error
JoinRoom is room.Join, fetching the participant token from src when src is non-nil (info's credentials are then ignored).
func ParticipantGrants ¶
func ParticipantGrants(info lksdk.ConnectInfo) *auth.ClaimGrants
ParticipantGrants returns the grants lksdk signs into the participant token when joining with info (see lksdk.Room.Join).
func Sign ¶
func Sign(ctx context.Context, src *CachingTokenSource, apiKey, apiSecret string, grants *auth.ClaimGrants, ttl time.Duration) (string, error)
Sign returns a JWT carrying grants, valid for about ttl. With src nil it is signed with apiKey and apiSecret (ttl 0 means the AccessToken default); otherwise it is fetched from src (ttl 0 means the source's default).
Types ¶
type CachingTokenSource ¶
type CachingTokenSource struct {
// contains filtered or unexported fields
}
CachingTokenSource wraps a TokenSource and caches its tokens by grants and ttl, so a command making many calls with the same grants (e.g. paging ListRooms) fetches once. Safe for concurrent use.
func NewCachingTokenSource ¶
func NewCachingTokenSource(source TokenSource) *CachingTokenSource
NewCachingTokenSource returns a CachingTokenSource fetching from source.
func (*CachingTokenSource) ClientOptions ¶
func (s *CachingTokenSource) ClientOptions() []twirp.ClientOption
ClientOptions returns twirp options that authorize every request through s. Use them with an SDK client constructed from the Placeholder credentials.
func (*CachingTokenSource) Exchange ¶
func (s *CachingTokenSource) Exchange(ctx context.Context, placeholderToken string, ttl time.Duration) (string, error)
Exchange returns a token fetched from s with the grants of placeholderToken, a token that library code built and signed with the placeholder credentials (e.g. protocol's egress.BuildEgressToken), valid for about ttl.
func (*CachingTokenSource) Fetch ¶
func (s *CachingTokenSource) Fetch(ctx context.Context, grants *auth.ClaimGrants, ttl time.Duration) (string, time.Time, error)
Fetch returns a cached token for grants and ttl while it is still comfortably valid, and fetches a new one otherwise.
func (*CachingTokenSource) Transport ¶
func (s *CachingTokenSource) Transport(base http.RoundTripper) http.RoundTripper
Transport returns an http.RoundTripper for clients that sign their own HTTP requests outside twirp hooks (e.g. cloudagents' log and build streams). It swaps each request's placeholder-signed bearer token for a fetched one with the same grants, then sends it through base (http.DefaultTransport when nil). Requests without an Authorization header pass through untouched.
type TokenSource ¶
type TokenSource interface {
Fetch(ctx context.Context, grants *auth.ClaimGrants, ttl time.Duration) (token string, expiresAt time.Time, err error)
}
TokenSource fetches a token for a project carrying grants, valid for about ttl (or the source's default when ttl is 0). It returns the token and its expiry.
Source Files