google/externalaccount: moves externalaccount package out of internal and exports it

go/programmable-auth-design for context. Adds support for user defined
 supplier methods to return subject tokens and AWS security credentials.

Change-Id: I7bc41f8c5202ae933fce516632f5049bbeb3d378
GitHub-Last-Rev: ac519b2
GitHub-Pull-Request: #690
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/550835
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Leo Siracusa <leosiracusa@google.com>
Reviewed-by: Chris Smith <chrisdsmith@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Cody Oss <codyoss@google.com>

Author: aeitzman

google/doc.go

@@ -22,91 +22,9 @@
 // the other by JWTConfigFromJSON. The returned Config can be used to obtain a TokenSource or
 // create an http.Client.
 //
-// # Workload Identity Federation
+// # Workload and Workforce Identity Federation
 //
-// Using workload identity federation, your application can access Google Cloud
-// resources from Amazon Web Services (AWS), Microsoft Azure or any identity
-// provider that supports OpenID Connect (OIDC) or SAML 2.0.
-// Traditionally, applications running outside Google Cloud have used service
-// account keys to access Google Cloud resources. Using identity federation,
-// you can allow your workload to impersonate a service account.
-// This lets you access Google Cloud resources directly, eliminating the
-// maintenance and security burden associated with service account keys.
-//
-// Follow the detailed instructions on how to configure Workload Identity Federation
-// in various platforms:
-//
-//	Amazon Web Services (AWS): https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws
-//	Microsoft Azure: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#azure
-//	OIDC identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc
-//	SAML 2.0 identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#saml
-//
-// For OIDC and SAML providers, the library can retrieve tokens in three ways:
-// from a local file location (file-sourced credentials), from a server
-// (URL-sourced credentials), or from a local executable (executable-sourced
-// credentials).
-// For file-sourced credentials, a background process needs to be continuously
-// refreshing the file location with a new OIDC/SAML token prior to expiration.
-// For tokens with one hour lifetimes, the token needs to be updated in the file
-// every hour. The token can be stored directly as plain text or in JSON format.
-// For URL-sourced credentials, a local server needs to host a GET endpoint to
-// return the OIDC/SAML token. The response can be in plain text or JSON.
-// Additional required request headers can also be specified.
-// For executable-sourced credentials, an application needs to be available to
-// output the OIDC/SAML token and other information in a JSON format.
-// For more information on how these work (and how to implement
-// executable-sourced credentials), please check out:
-// https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_credential_configuration
-//
-// Note that this library does not perform any validation on the token_url, token_info_url,
-// or service_account_impersonation_url fields of the credential configuration.
-// It is not recommended to use a credential configuration that you did not generate with
-// the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain.
-//
-// # Workforce Identity Federation
-//
-// Workforce identity federation lets you use an external identity provider (IdP) to
-// authenticate and authorize a workforce—a group of users, such as employees, partners,
-// and contractors—using IAM, so that the users can access Google Cloud services.
-// Workforce identity federation extends Google Cloud's identity capabilities to support
-// syncless, attribute-based single sign on.
-//
-// With workforce identity federation, your workforce can access Google Cloud resources
-// using an external identity provider (IdP) that supports OpenID Connect (OIDC) or
-// SAML 2.0 such as Azure Active Directory (Azure AD), Active Directory Federation
-// Services (AD FS), Okta, and others.
-//
-// Follow the detailed instructions on how to configure Workload Identity Federation
-// in various platforms:
-//
-//	Azure AD: https://cloud.google.com/iam/docs/workforce-sign-in-azure-ad
-//	Okta: https://cloud.google.com/iam/docs/workforce-sign-in-okta
-//	OIDC identity provider: https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#oidc
-//	SAML 2.0 identity provider: https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#saml
-//
-// For workforce identity federation, the library can retrieve tokens in three ways:
-// from a local file location (file-sourced credentials), from a server
-// (URL-sourced credentials), or from a local executable (executable-sourced
-// credentials).
-// For file-sourced credentials, a background process needs to be continuously
-// refreshing the file location with a new OIDC/SAML token prior to expiration.
-// For tokens with one hour lifetimes, the token needs to be updated in the file
-// every hour. The token can be stored directly as plain text or in JSON format.
-// For URL-sourced credentials, a local server needs to host a GET endpoint to
-// return the OIDC/SAML token. The response can be in plain text or JSON.
-// Additional required request headers can also be specified.
-// For executable-sourced credentials, an application needs to be available to
-// output the OIDC/SAML token and other information in a JSON format.
-// For more information on how these work (and how to implement
-// executable-sourced credentials), please check out:
-// https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#generate_a_configuration_file_for_non-interactive_sign-in
-//
-// # Security considerations
-//
-// Note that this library does not perform any validation on the token_url, token_info_url,
-// or service_account_impersonation_url fields of the credential configuration.
-// It is not recommended to use a credential configuration that you did not generate with
-// the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain.
+// For information on how to use Workload and Workforce Identity Federation, see [golang.org/x/oauth2/google/externalaccount].
 //
 // # Credentials
 //

google/internal/externalaccount/aws.go google/externalaccount/aws.go

@@ -26,22 +26,28 @@ import (
 	"golang.org/x/oauth2"
 )
 
-type awsSecurityCredentials struct {
-	AccessKeyID     string `json:"AccessKeyID"`
+// AwsSecurityCredentials models AWS security credentials.
+type AwsSecurityCredentials struct {
+	// AccessKeyId is the AWS Access Key ID - Required.
+	AccessKeyID string `json:"AccessKeyID"`
+	// SecretAccessKey is the AWS Secret Access Key - Required.
 	SecretAccessKey string `json:"SecretAccessKey"`
-	SecurityToken   string `json:"Token"`
+	// SessionToken is the AWS Session token. This should be provided for temporary AWS security credentials - Optional.
+	SessionToken string `json:"Token"`
 }
 
 // awsRequestSigner is a utility class to sign http requests using a AWS V4 signature.
 type awsRequestSigner struct {
 	RegionName             string
-	AwsSecurityCredentials awsSecurityCredentials
+	AwsSecurityCredentials *AwsSecurityCredentials
 }
 
 // getenv aliases os.Getenv for testing
 var getenv = os.Getenv
 
 const (
+	defaultRegionalCredentialVerificationUrl = "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
+
 	// AWS Signature Version 4 signing algorithm identifier.
 	awsAlgorithm = "AWS4-HMAC-SHA256"
 
@@ -197,8 +203,8 @@ func (rs *awsRequestSigner) SignRequest(req *http.Request) error {
 
 	signedRequest.Header.Add("host", requestHost(req))
 
-	if rs.AwsSecurityCredentials.SecurityToken != "" {
-		signedRequest.Header.Add(awsSecurityTokenHeader, rs.AwsSecurityCredentials.SecurityToken)
+	if rs.AwsSecurityCredentials.SessionToken != "" {
+		signedRequest.Header.Add(awsSecurityTokenHeader, rs.AwsSecurityCredentials.SessionToken)
 	}
 
 	if signedRequest.Header.Get("date") == "" {
@@ -251,16 +257,18 @@ func (rs *awsRequestSigner) generateAuthentication(req *http.Request, timestamp
 }
 
 type awsCredentialSource struct {
-	EnvironmentID               string
-	RegionURL                   string
-	RegionalCredVerificationURL string
-	CredVerificationURL         string
-	IMDSv2SessionTokenURL       string
-	TargetResource              string
-	requestSigner               *awsRequestSigner
-	region                      string
-	ctx                         context.Context
-	client                      *http.Client
+	environmentID                  string
+	regionURL                      string
+	regionalCredVerificationURL    string
+	credVerificationURL            string
+	imdsv2SessionTokenURL          string
+	targetResource                 string
+	requestSigner                  *awsRequestSigner
+	region                         string
+	ctx                            context.Context
+	client                         *http.Client
+	awsSecurityCredentialsSupplier AwsSecurityCredentialsSupplier
+	supplierOptions                SupplierOptions
 }
 
 type awsRequestHeader struct {
@@ -292,18 +300,25 @@ func canRetrieveSecurityCredentialFromEnvironment() bool {
 	return getenv(awsAccessKeyId) != "" && getenv(awsSecretAccessKey) != ""
 }
 
-func shouldUseMetadataServer() bool {
-	return !canRetrieveRegionFromEnvironment() || !canRetrieveSecurityCredentialFromEnvironment()
+func (cs awsCredentialSource) shouldUseMetadataServer() bool {
+	return cs.awsSecurityCredentialsSupplier == nil && (!canRetrieveRegionFromEnvironment() || !canRetrieveSecurityCredentialFromEnvironment())
 }
 
 func (cs awsCredentialSource) credentialSourceType() string {
+	if cs.awsSecurityCredentialsSupplier != nil {
+		return "programmatic"
+	}
 	return "aws"
 }
 
 func (cs awsCredentialSource) subjectToken() (string, error) {
+	// Set Defaults
+	if cs.regionalCredVerificationURL == "" {
+		cs.regionalCredVerificationURL = defaultRegionalCredentialVerificationUrl
+	}
 	if cs.requestSigner == nil {
 		headers := make(map[string]string)
-		if shouldUseMetadataServer() {
+		if cs.shouldUseMetadataServer() {
 			awsSessionToken, err := cs.getAWSSessionToken()
 			if err != nil {
 				return "", err
@@ -318,8 +333,8 @@ func (cs awsCredentialSource) subjectToken() (string, error) {
 		if err != nil {
 			return "", err
 		}
-
-		if cs.region, err = cs.getRegion(headers); err != nil {
+		cs.region, err = cs.getRegion(headers)
+		if err != nil {
 			return "", err
 		}
 
@@ -331,16 +346,16 @@ func (cs awsCredentialSource) subjectToken() (string, error) {
 
 	// Generate the signed request to AWS STS GetCallerIdentity API.
 	// Use the required regional endpoint. Otherwise, the request will fail.
-	req, err := http.NewRequest("POST", strings.Replace(cs.RegionalCredVerificationURL, "{region}", cs.region, 1), nil)
+	req, err := http.NewRequest("POST", strings.Replace(cs.regionalCredVerificationURL, "{region}", cs.region, 1), nil)
 	if err != nil {
 		return "", err
 	}
 	// The full, canonical resource name of the workload identity pool
 	// provider, with or without the HTTPS prefix.
 	// Including this header as part of the signature is recommended to
 	// ensure data integrity.
-	if cs.TargetResource != "" {
-		req.Header.Add("x-goog-cloud-target-resource", cs.TargetResource)
+	if cs.targetResource != "" {
+		req.Header.Add("x-goog-cloud-target-resource", cs.targetResource)
 	}
 	cs.requestSigner.SignRequest(req)
 
@@ -387,11 +402,11 @@ func (cs awsCredentialSource) subjectToken() (string, error) {
 }
 
 func (cs *awsCredentialSource) getAWSSessionToken() (string, error) {
-	if cs.IMDSv2SessionTokenURL == "" {
+	if cs.imdsv2SessionTokenURL == "" {
 		return "", nil
 	}
 
-	req, err := http.NewRequest("PUT", cs.IMDSv2SessionTokenURL, nil)
+	req, err := http.NewRequest("PUT", cs.imdsv2SessionTokenURL, nil)
 	if err != nil {
 		return "", err
 	}
@@ -410,25 +425,29 @@ func (cs *awsCredentialSource) getAWSSessionToken() (string, error) {
 	}
 
 	if resp.StatusCode != 200 {
-		return "", fmt.Errorf("oauth2/google: unable to retrieve AWS session token - %s", string(respBody))
+		return "", fmt.Errorf("oauth2/google/externalaccount: unable to retrieve AWS session token - %s", string(respBody))
 	}
 
 	return string(respBody), nil
 }
 
 func (cs *awsCredentialSource) getRegion(headers map[string]string) (string, error) {
+	if cs.awsSecurityCredentialsSupplier != nil {
+		return cs.awsSecurityCredentialsSupplier.AwsRegion(cs.ctx, cs.supplierOptions)
+	}
 	if canRetrieveRegionFromEnvironment() {
 		if envAwsRegion := getenv(awsRegion); envAwsRegion != "" {
+			cs.region = envAwsRegion
 			return envAwsRegion, nil
 		}
 		return getenv("AWS_DEFAULT_REGION"), nil
 	}
 
-	if cs.RegionURL == "" {
-		return "", errors.New("oauth2/google: unable to determine AWS region")
+	if cs.regionURL == "" {
+		return "", errors.New("oauth2/google/externalaccount: unable to determine AWS region")
 	}
 
-	req, err := http.NewRequest("GET", cs.RegionURL, nil)
+	req, err := http.NewRequest("GET", cs.regionURL, nil)
 	if err != nil {
 		return "", err
 	}
@@ -449,7 +468,7 @@ func (cs *awsCredentialSource) getRegion(headers map[string]string) (string, err
 	}
 
 	if resp.StatusCode != 200 {
-		return "", fmt.Errorf("oauth2/google: unable to retrieve AWS region - %s", string(respBody))
+		return "", fmt.Errorf("oauth2/google/externalaccount: unable to retrieve AWS region - %s", string(respBody))
 	}
 
 	// This endpoint will return the region in format: us-east-2b.
@@ -461,12 +480,15 @@ func (cs *awsCredentialSource) getRegion(headers map[string]string) (string, err
 	return string(respBody[:respBodyEnd]), nil
 }
 
-func (cs *awsCredentialSource) getSecurityCredentials(headers map[string]string) (result awsSecurityCredentials, err error) {
+func (cs *awsCredentialSource) getSecurityCredentials(headers map[string]string) (result *AwsSecurityCredentials, err error) {
+	if cs.awsSecurityCredentialsSupplier != nil {
+		return cs.awsSecurityCredentialsSupplier.AwsSecurityCredentials(cs.ctx, cs.supplierOptions)
+	}
 	if canRetrieveSecurityCredentialFromEnvironment() {
-		return awsSecurityCredentials{
+		return &AwsSecurityCredentials{
 			AccessKeyID:     getenv(awsAccessKeyId),
 			SecretAccessKey: getenv(awsSecretAccessKey),
-			SecurityToken:   getenv(awsSessionToken),
+			SessionToken:    getenv(awsSessionToken),
 		}, nil
 	}
 
@@ -481,20 +503,20 @@ func (cs *awsCredentialSource) getSecurityCredentials(headers map[string]string)
 	}
 
 	if credentials.AccessKeyID == "" {
-		return result, errors.New("oauth2/google: missing AccessKeyId credential")
+		return result, errors.New("oauth2/google/externalaccount: missing AccessKeyId credential")
 	}
 
 	if credentials.SecretAccessKey == "" {
-		return result, errors.New("oauth2/google: missing SecretAccessKey credential")
+		return result, errors.New("oauth2/google/externalaccount: missing SecretAccessKey credential")
 	}
 
-	return credentials, nil
+	return &credentials, nil
 }
 
-func (cs *awsCredentialSource) getMetadataSecurityCredentials(roleName string, headers map[string]string) (awsSecurityCredentials, error) {
-	var result awsSecurityCredentials
+func (cs *awsCredentialSource) getMetadataSecurityCredentials(roleName string, headers map[string]string) (AwsSecurityCredentials, error) {
+	var result AwsSecurityCredentials
 
-	req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", cs.CredVerificationURL, roleName), nil)
+	req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", cs.credVerificationURL, roleName), nil)
 	if err != nil {
 		return result, err
 	}
@@ -516,19 +538,19 @@ func (cs *awsCredentialSource) getMetadataSecurityCredentials(roleName string, h
 	}
 
 	if resp.StatusCode != 200 {
-		return result, fmt.Errorf("oauth2/google: unable to retrieve AWS security credentials - %s", string(respBody))
+		return result, fmt.Errorf("oauth2/google/externalaccount: unable to retrieve AWS security credentials - %s", string(respBody))
 	}
 
 	err = json.Unmarshal(respBody, &result)
 	return result, err
 }
 
 func (cs *awsCredentialSource) getMetadataRoleName(headers map[string]string) (string, error) {
-	if cs.CredVerificationURL == "" {
-		return "", errors.New("oauth2/google: unable to determine the AWS metadata server security credentials endpoint")
+	if cs.credVerificationURL == "" {
+		return "", errors.New("oauth2/google/externalaccount: unable to determine the AWS metadata server security credentials endpoint")
 	}
 
-	req, err := http.NewRequest("GET", cs.CredVerificationURL, nil)
+	req, err := http.NewRequest("GET", cs.credVerificationURL, nil)
 	if err != nil {
 		return "", err
 	}
@@ -549,7 +571,7 @@ func (cs *awsCredentialSource) getMetadataRoleName(headers map[string]string) (s
 	}
 
 	if resp.StatusCode != 200 {
-		return "", fmt.Errorf("oauth2/google: unable to retrieve AWS role name - %s", string(respBody))
+		return "", fmt.Errorf("oauth2/google/externalaccount: unable to retrieve AWS role name - %s", string(respBody))
 	}
 
 	return string(respBody), nil