adcplus

README

adcplus

This package implements oauth2.TokenSource and signer which respects ADC with impersonation.

• Automatically uses CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT environment variable as an impersonation target and a delegation chain.
  • It respects same variable and syntax of gcloud.
    • https://cloud.google.com/sdk/gcloud/reference/topic/configurations?hl=en#impersonate_service_account
    • https://cloud.google.com/sdk/docs/properties?hl=en#setting_properties_via_environment_variables
• Can override the impersonation target, the delegate chain and the source credential through functional options.

Disclaimer

This package is EXPERIMENTAL.

• No responsibility.
• May be broken.
• Will do breaking changes.

Underlying method

• Currently, external_account(STS) is not mentioned in AIP-4110 because it is removed when approval but it is supported in golang.org/x/oauth2/google and it is documented. I treat it as one of ADC credential.
• "Credentials API" is Service Account Credentials API (projects.serviceAccounts.signBlob, projects.serviceAccounts.signJwt)
  • Need Service Account Token Creator role(roles/iam.serviceAccountTokenCreator)

signer.SmartSigner

credential/impersonate	yes	no
authorized_user	Credentials API	Not Supported
service_account	Credentials API	Sign by JSON key
external_account	Credentials API	Credentials API as itself
compute_metadata	Credentials API	Credentials API as itself
App Engine 1st gen(only if WithExperimentalAppEngineSigner(true))	Credentials API	appengine.SignBytes()

tokensource.SmartAccessTokenSource

credential/impersonate	yes	no
authorized_user	Credentials API	ADC(refresh token flow)
service_account	Credentials API	ADC(jwt-bearer token flow)
external_account	Credentials API	ADC(STS)
compute_metadata	Credentials API	ADC(token endpoint)

tokensource.SmartIDTokenSource

credential/impersonate	yes	no
authorized_user	Credentials API	Not Supported
service_account	Credentials API	ADC(jwt-bearer flow)
external_account	Credentials API	Not Supported(TODO: retrieve using STS)
compute_metadata	Credentials API	ADC(identity endpoint)

TODO

• Support Self-signed JWT(AIP-4111) for service_account in SmartAccessTokenSource.
  • It may be better to wait Self-signed JWT with scopes is supported in JWTAccessTokenSourceFromJSON
• Support to override underlying TokenSource.
  • WithTokenSource()
• Support external_account in tokensource.SmartIDTokenSource.
• Re-implement underlying TokenSource to avoid ReuseTokenSource in default.
• Add tests.
• Replace signJwtHelper with a reliable implementation.

Documentation

Index

• type Option
  • func WithCredentialsFile(filename string) Option
  • func WithCredentialsJSON(j []byte) Option
  • func WithDelegates(delegates ...string) Option
  • func WithExperimentalAppEngineSigner(enable bool) Option
  • func WithScopes(scopes ...string) Option
  • func WithTargetPrincipal(targetPrincipal string) Option

Types

type Option

type Option func(*config.AdcPlusConfig) error

func WithCredentialsFile

func WithCredentialsFile(filename string) Option

WithCredentialsFile returns Option which specifies the path of credentials. If filename is empty string, it will be ignored.

func WithCredentialsJSON

func WithCredentialsJSON(j []byte) Option

WithCredentialsJSON returns Option which specifies the content of credentials. If j is nil or empty slice, it will be ignored.

func WithDelegates

func WithDelegates(delegates ...string) Option

WithDelegates returns Option which specifies the delegate chain for impersonation.

func WithExperimentalAppEngineSigner

func WithExperimentalAppEngineSigner(enable bool) Option

WithExperimentalAppEngineSigner returns Option which specifies to use appengine.SignBytes by Signer. Caution: It makes the signer to require an App Engine context. If you don't know this meaning, don't set this option.

func WithScopes

func WithScopes(scopes ...string) Option

WithScopes returns Option which specifies the scopes of the access token.

func WithTargetPrincipal

func WithTargetPrincipal(targetPrincipal string) Option

WithTargetPrincipal returns Option which specifies the target principal for impersonation.