blob: f49a45223c17484cae86280a68213852a87577ce [file] [log] [blame]
// Copyright 2016 The LUCI Authors.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
package auth
import (
// globalCacheNamespace is global cache namespace to use for storing tokens.
const globalCacheNamespace = "__luciauth__"
// tokenCacheConfig contains configuration of a token cache for a single token
// kind.
type tokenCacheConfig struct {
// Kind defines the token kind. Will be used as part of the global cache key.
Kind string
// Version defines format of the data. Will be used as part of the global
// cache key.
// If you change a type behind interface{} in Token field, you MUST bump the
// version. It will also "invalidate" all existing cached entries (they will
// just become inaccessible and eventually will be evicted from the cache).
Version int
// ProcessLRUCache is a handle to a process LRU cache that holds the tokens.
ProcessLRUCache caching.LRUHandle
// ExpiryRandomizationThreshold defines a threshold for item expiration after
// which the randomized early expiration kick in.
// See layered.WithRandomizedExpiration for more details.
ExpiryRandomizationThreshold time.Duration
// tokenCache knows how to store tokens of some particular kind.
// Must be initialized during init-time via newTokenCache.
type tokenCache struct {
cfg tokenCacheConfig
lc layered.Cache
// newTokenCache configures tokenCache based on given parameters.
func newTokenCache(cfg tokenCacheConfig) *tokenCache {
return &tokenCache{
cfg: cfg,
lc: layered.Cache{
ProcessLRUCache: cfg.ProcessLRUCache,
GlobalNamespace: globalCacheNamespace,
Marshal: json.Marshal, // marshals *cachedToken
Unmarshal: func(blob []byte) (interface{}, error) {
out := &cachedToken{}
err := json.Unmarshal(blob, out)
return out, err
// cachedToken is stored in the token cache.
type cachedToken struct {
// Key is cache key, must be unique (no other restrictions).
Key string `json:"key,omitempty"`
// Created is when the token was created, required.
Created time.Time `json:"created,omitempty"`
// Expire is when the token expires, required.
Expiry time.Time `json:"expiry,omitempty"`
// TODO(fmatenaar): Remove this after migrating projects to scoped accounts.
// ProjectScopeFallback indicates a project scoped token migration fallback case.
ProjectScopeFallback bool `json:"fallback,omitempty"`
// OAuth2Token is set when caching an OAuth2 tokens, otherwise empty.
OAuth2Token string `json:"oauth2_token,omitempty"`
// DelegationToken is set when caching a delegation token, otherwise empty.
DelegationToken string `json:"delegation_token,omitempty"`
// IDToken is set when caching ID tokens, otherwise empty.
IDToken string `json:"id_token,omitempty"`
type fetchOrMintTokenOp struct {
CacheKey string
MinTTL time.Duration
Mint func(context.Context) (tok *cachedToken, err error, label string)
MintTimeout time.Duration
// fetchOrMintToken implements high level logic of using a token cache.
// It's basis or MintAccessTokenForServiceAccount and MintDelegationToken
// implementations.
// Returns a token, an error and a label to use for monitoring metric (its value
// depends on how exactly the operation was performed or how it failed).
func (tc *tokenCache) fetchOrMintToken(ctx context.Context, op *fetchOrMintTokenOp) (tok *cachedToken, err error, label string) {
defer func() {
if err != nil {
logging.WithError(err).Warningf(ctx, "Failed to get the token")
// Derive a short unique cache key that also depends on Kind and Version.
// op.CacheKey is allowed to be of any length, but global cache keys must be
// short-ish.
digest := sha256.Sum256([]byte(op.CacheKey))
cacheKey := fmt.Sprintf("%s/%d/%s",
tc.cfg.Kind, tc.cfg.Version, base64.RawURLEncoding.EncodeToString(digest[:]))
label = "SUCCESS_CACHE_HIT" // will be replaced on cache miss or on error
// Pull our token from the cache or create a new one (construct options first
// for better readability).
opts := []layered.Option{
fetched, err :=, cacheKey, func() (val interface{}, ttl time.Duration, err error) {
logging.Debugf(ctx, "Minting the new token")
// Minting a new token involves RPCs to remote services that should be fast.
// Abort the attempt if it gets stuck for longer than N sec, it's unlikely
// it'll succeed. Note that we setup the new context only on slow code path
// (on cache miss), since it involves some overhead we don't want to pay on
// the fast path. We assume memcache RPCs don't get stuck for a long time
// (unlike URL Fetch calls to GAE).
ctx, cancel := clock.WithTimeout(ctx, op.MintTimeout)
defer cancel()
// Note: we set 'label' from the outer scope here.
var tok *cachedToken
if tok, err, label = op.Mint(ctx); err != nil {
if label == "" {
return nil, 0, err
tok.Key = op.CacheKey // the original key before hashing
return tok, clock.Until(ctx, tok.Expiry), nil
}, opts...)
switch tok, _ = fetched.(*cachedToken); {
case errors.Unwrap(err) == context.DeadlineExceeded:
return nil, err, "ERROR_DEADLINE"
case err == layered.ErrCantSatisfyMinTTL:
// This happens if op.Mint failed to produce a token that lives longer
// than MinTTL.
case err != nil:
return nil, err, label
case tok.Key != op.CacheKey:
// A paranoid check we've got the token we wanted. This is very-very-very
// unlikely to happen in practice, SHA256 collisions are rare. So it's fine
// to handle it sloppily and just return an error (still better than
// accidentally using wrong token).
err = fmt.Errorf("SHA256 collision in the token cache: %q vs %q", tok.Key, op.CacheKey)
return nil, err, "ERROR_HASH_COLLISION"
return tok, nil, label