feat: add impersonate pacakge

[codyoss]

This package is used for creating a impersonated TokenSource. This
TokenSource can then be passed into any client or API that accepts
a client option. This package provides support for three types of
impersonation:

1. A service account impersonating another service account.
2. A service account impersonating another service account as an
   admin user -- a pattern used with domain wide delegation.
3. A service account creating an impersonated ID token.

Fixes: #652
Fixes: #777
Fixes: #731
Updates: #378

[codyoss]

Still doing a little more manual testing for one of the use-cases, but I thought I would get some code out to start the review process as this a decent size PR.

[codyoss]

Note this is being targeted to a release branch where this will be released as a preview.

[codyoss]

cc @salrashid123

[salrashid123]

hi-

is this PR to break and add additional capabilities to the impersonated creds (eg, impersonate user via domain-delegation, etc) by breaking it out to a config and then to a TokenSource it its own right?

i ask since the baseline exisiting implementation allows you to derive the tokensource via option.

thx

---

import (
    "google.golang.org/api/option"
    "google.golang.org/api/transport"
)

func main() {

    ctx := context.Background()
    creds, err := transport.Creds(ctx,
        option.WithScopes("https://www.googleapis.com/auth/cloud-platform"),
        option.ImpersonateCredentials("impersonated-account@fabled-ray-104117.iam.gserviceaccount.com"))
    ts := creds.TokenSource

    tok, err := ts.Token()
    log.Printf("access_token %v", tok.AccessToken)

}

[codyoss]

@salrashid123 This package is meant to be a replacement for that option. The TokenSource generated from here, using ADC and options to configure base credentials, can be passed to any client with option.WithTokenSource.

See example_test.go.

[martinroberts]

Thank you for breaking this out for those of us calling APIs with no client library. And thanks to @salrashid123 for code and advice in the interim.

I notice that your docs focus on impersonation but you also support (domain-wide)delegation. In particular, I have been caught out by the need for the targetPrincipal to have "Service Account Token Creator" (SATC) on itself and think others would benefit from including this detail in the docs.

Let me spell that out: for a pod with workload identity WI1 (base credentials) impersonating service account SA2 (target principal) to act on behalf of user U3 (subject), we need

• W1 has SATC role on SA2
• SA2 has SATC role on SA2 (!)
• SA2 has been granted relevant scopes and rights by the domain admin for U3

[tbpg]

LGTM. Would be great to have users try this out before releasing into a non-prerelease version (i.e. v0.81.0-impersonate-beta before v0.81.0 (I forget the exact syntax)) .

[natalysheinin]

Just tried this and it worked as expected. Thank-you so much for pushing this feature through.

[hanneshayashi]

Works like a charm. Thanks for this!

[salrashid123]

tested

• impersonate->(access_tokens->gcs), 
• impersonate->(id_tokens->IAP), 
• impersonate->(id_tokens->gRPC)->Cloud Run, 

---

its unrelated to impersonated creds here but its never really clear how to use our tokensources with grpc connections...maybe a doc bug to update grpc stuff elsewhere

here's the full test sequence for the bit above with a highlight on the specific grpc struct you need for tokensource

https://gist.github.com/salrashid123/17d36368fc720c09b4acf4a7bdc9f340#file-main-go-L157

---

ref, cloud run+idtoken+grpc

[codyoss]

@salrashid123

never really clear how to use our tokensources with grpc connections
For use with our gRPC based client libraries you can use the option.WithTokenSource. If you are talking about manually dialing what you did in your gist is fine dialing with grpc.WithPerRPCCredentials. You could use the oauth.TokenSource directly instead of using a wrapper if you wanted. We wrap it in our transport code because we add a little bit of extra metadata.

[salrashid123]

yeah, the grpc test was using this library to get an idtoken for a non GCP service api (i.e an api that i run that is grpc that happens to accept a google id_token (and in this case, the idtoken is for an impersonated creds).

but yeah, thanks. the oauth.TokenSource{} also works here.

	conn, err = grpc.Dial(grpcHost+":443",
		grpc.WithTransportCredentials(ce),
		grpc.WithPerRPCCredentials(oauth.TokenSource{
			TokenSource: gRPCidTokenSource,
		}),
	)

[upodroid]

I'm implementing the new impersonate package in hashicorp/terraform#28296 and it looks like the package only allows the initial credentials to be an ADC. Terraform supports static accesstoken(static TokenSource) or json loaded with option.WithCredentialsJSON which this package doesn't support.

https://github.com/hashicorp/terraform/blob/b7fb533bd27d63e582489906a63bf1b25ecd5e49/backend/remote-state/gcs/backend.go#L152

[codyoss]

@upodroid You should be able to pass in any TokenSource by doing something like: impersonate.CredentialsTokenSource(ctx, impersonate.CredentialsConfig{...}, option.WithTokenSource(anyTokenSource)) This will use the provided TokenSource instead of creds found via ADC for the base credentials in the impersonation flow. Does that solve your issue?

[upodroid]

That worked for me, thanks.

[upodroid]

btw, v0.44.0 doesn't include the impersonate package. It would be nice to see it in v0.45.0

[codyoss]

@upodroid Yes, v0.44.0 got cut sooner than originally planned. I hope to get this in the next main release. I will ping this issue and update the release notes accordingly when that happens.