sts

README

STS (secure token service) client and server code

Extracted from Istio repository and cleaned up. The intent is to include it directly in the krun/hbone, to avoid requiring pilot-agent for proxyless gRPC and 'uProxy' hbone mode.

STS is defined in RFC6750. Istio client is in stsclient.go (used for MeshCA) and tokenexchangeplugin.go.

Golang gRPC has credentials/sts/sts.go - unfortunately the API requires the token to be saved to a path

OAuth2 package includes downscope.NewTokenSource that wraps STS.

Stackdriver uses a similar STS exchange, implemented in Envoy, with STS server in istio-agent, using:

 {
        "stackdriver_grpc_service": {
        "google_grpc": {
          "stat_prefix": "oc_stackdriver_tracer",
          "channel_credentials": {
            "ssl_credentials": {
              "root_certs": {
                "filename": "/etc/ssl/certs/ca-certificates.crt"
              }
            }
          },
          "call_credentials": {
            "sts_service": {
              "token_exchange_service_uri": "http://localhost:{{ .stsPort }}/token",
              "subject_token_path": "/var/run/secrets/tokens/istio-token",
              "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
              "scope": "https://www.googleapis.com/auth/cloud-platform",
            }
          }
        },
        "initial_metadata": [
          {
            "key": "x-goog-user-project",
            "value": "{{ .gcp_project_id }}"
          }
        ]
      },
}

Generate access/ID token

generateAccessToken

Requires 'iam.serviceAccounts.getAccessToken' permission or roles/iam.serviceAccountTokenCreator

Initial credentials

Identity is bootstrapped from existing platform credentials.

Sources:

• GOOGLE_APPLICATION_CREDENTIALS
• $HOME/.config/gcloud/application_default_credentials.json
• metadata server
• $HOME/.kube/config
• in-cluster token/CA addr/cert

The identity returned by initial credentials can be:

• a User - who might be admin on k8s.
• a GSA - with specific permissions assigned for the application.
• a KSA

The trust domain is derived from the projectID - for gke://CONFIG_PROJECT, and for explicit clusters the projectId of the cluster.

Google credentials are found using golang.org/x/oauth2/google FindDefaultCredentialsWithParams().

Documentation

Index

• Variables
• func TokenPayload(jwt string) string
• type Duration
• type STS
  • func NewSTS(kr *mesh.KRun) (*STS, error)
  • func (s *STS) GetRequestMetadata(ctx context.Context, aud ...string) (map[string]string, error)
  • func (s *STS) RequireTransportSecurity() bool
  • func (s *STS) ServeStsRequests(w http.ResponseWriter, req *http.Request)
  • func (s *STS) Token() (*oauth2.Token, error)
  • func (s *STS) TokenAccess(ctx context.Context, federatedToken string, audience string) (string, error)
  • func (s *STS) TokenFederated(ctx context.Context, k8sSAjwt string) (string, error)
• type StsErrorResponse
• type StsRequestParameters
• type StsResponseParameters
• type TokenCache
  • func NewTokenCache(kr *mesh.KRun, sts *STS) *TokenCache
  • func (c *TokenCache) Token(ctx context.Context, host string) (string, error)

Variables

var (
	// SecureTokenEndpoint is the Endpoint the STS client calls to.
	SecureTokenEndpoint = "https://sts.googleapis.com/v1/token"

	Scope = "https://www.googleapis.com/auth/cloud-platform"

	// Server side
	// TokenPath is url path for handling STS requests.
	TokenPath = "/token"
	// StsStatusPath is the path for dumping STS status.
	StsStatusPath = "/stsStatus"
	// URLEncodedForm is the encoding type specified in a STS request.
	URLEncodedForm = "application/x-www-form-urlencoded"
	// TokenExchangeGrantType is the required value for "grant_type" parameter in a STS request.
	TokenExchangeGrantType = "urn:ietf:params:oauth:grant-type:token-exchange"
	// SubjectTokenType is the required token type in a STS request.
	SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"

	Debug = false
)

From nodeagent/plugin/providers/google/stsclient In Istio, the code is used if "GoogleCA" is set as CA_PROVIDER or CA_ADDR has the right prefix

Functions

func TokenPayload

func TokenPayload(jwt string) string

TokenPayload returns the decoded token. Used for logging/debugging token content, without printing the signature.

Types

type Duration

type Duration struct {
	// Signed seconds of the span of time. Must be from -315,576,000,000
	// to +315,576,000,000 inclusive. Note: these bounds are computed from:
	// 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
	Seconds int64 `json:"seconds"`
}

From tokenexchangeplugin.go

type STS

type STS struct {

	// Google service account to impersonate and return tokens for.
	// The KSA returned from K8S must have the IAM permissions
	GSA string

	// Use mesh data plane SA.
	MDPSA          bool
	UseAccessToken bool
	// contains filtered or unexported fields
}

STS provides token exchanges. Implements grpc and golang.org/x/oauth2.TokenSource The source of trust is the K8S token with TrustDomain audience, it is exchanged with access or ID tokens.

func NewSTS

func NewSTS(kr *mesh.KRun) (*STS, error)

func (*STS) GetRequestMetadata

func (s *STS) GetRequestMetadata(ctx context.Context, aud ...string) (map[string]string, error)

GetRequestMetadata implements credentials.PerRPCCredentials This can be used for both ID tokens or access tokens - if the 'aud' containts googleapis.com, access tokens are returned.

func (*STS) RequireTransportSecurity

func (s *STS) RequireTransportSecurity() bool

func (*STS) ServeStsRequests

func (s *STS) ServeStsRequests(w http.ResponseWriter, req *http.Request)

ServeStsRequests handles STS requests and sends exchanged token in responses.

func (*STS) Token

func (s *STS) Token() (*oauth2.Token, error)

Implements oauth2.TokenSource - returning access tokens May return federated token or service account tokens

func (*STS) TokenAccess

func (s *STS) TokenAccess(ctx context.Context, federatedToken string, audience string) (string, error)

Exchange a federated token equivalent with the k8s JWT with the ASM p4SA. TODO: can be used with any GSA, if the permission to call generateAccessToken is granted. This is a good way to get access tokens for a GSA using the KSA, similar with TokenRequest in the other direction.

May return an ID token with aud or access token.

func (*STS) TokenFederated

func (s *STS) TokenFederated(ctx context.Context, k8sSAjwt string) (string, error)

TokenFederated exchanges the K8S JWT with a federated token (former ExchangeToken)

type StsErrorResponse

type StsErrorResponse struct {
	// REQUIRED. A single ASCII Error code.
	Error string `json:"error"`
	// OPTIONAL. Human-readable ASCII [USASCII] text providing additional information.
	ErrorDescription string `json:"error_description"`
	// OPTIONAL. A URI identifying a human-readable web page with information
	// about the Error.
	ErrorURI string `json:"error_uri"`
}

StsErrorResponse stores all Error parameters sent as JSON in a STS Error response. The Error parameters are defined in https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-2.2.2.

type StsRequestParameters

type StsRequestParameters struct {
	// REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- exchange"
	// indicates that a token exchange is being performed.
	GrantType string
	// OPTIONAL. Indicates the location of the target service or resource where
	// the client intends to use the requested security token.
	Resource string
	// OPTIONAL. The logical name of the target service where the client intends
	// to use the requested security token.
	Audience string
	// OPTIONAL. A list of space-delimited, case-sensitive strings, that allow
	// the client to specify the desired Scope of the requested security token in the
	// context of the service or Resource where the token will be used.
	Scope string
	// OPTIONAL. An identifier, for the type of the requested security token.
	RequestedTokenType string
	// REQUIRED. A security token that represents the identity of the party on
	// behalf of whom the request is being made.
	SubjectToken string
	// REQUIRED. An identifier, that indicates the type of the security token in
	// the "subject_token" parameter.
	SubjectTokenType string
	// OPTIONAL. A security token that represents the identity of the acting party.
	ActorToken string
	// An identifier, that indicates the type of the security token in the
	// "actor_token" parameter.
	ActorTokenType string
}

StsRequestParameters stores all STS request attributes defined in https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-2.1

type StsResponseParameters

type StsResponseParameters struct {
	// REQUIRED. The security token issued by the authorization server
	// in response to the token exchange request.
	AccessToken string `json:"access_token"`
	// REQUIRED. An identifier, representation of the issued security token.
	IssuedTokenType string `json:"issued_token_type"`
	// REQUIRED. A case-insensitive value specifying the method of using the access
	// token issued. It provides the client with information about how to utilize the
	// access token to access protected resources.
	TokenType string `json:"token_type"`
	// RECOMMENDED. The validity lifetime, in seconds, of the token issued by the
	// authorization server.
	ExpiresIn int64 `json:"expires_in"`
	// OPTIONAL, if the Scope of the issued security token is identical to the
	// Scope requested by the client; otherwise, REQUIRED.
	Scope string `json:"scope"`
	// OPTIONAL. A refresh token will typically not be issued when the exchange is
	// of one temporary credential (the subject_token) for a different temporary
	// credential (the issued token) for use in some other context.
	RefreshToken string `json:"refresh_token"`
}

StsResponseParameters stores all attributes sent as JSON in a successful STS response. These attributes are defined in https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-2.2.1

type TokenCache

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

func NewTokenCache

func NewTokenCache(kr *mesh.KRun, sts *STS) *TokenCache

func (*TokenCache) Token

func (c *TokenCache) Token(ctx context.Context, host string) (string, error)