Struct ProgrammaticBuilder

pub struct ProgrammaticBuilder { /* private fields */ }

A builder for external account Credentials that uses a user provided subject token provider.

This builder is designed for advanced use cases where the subject token is provided directly by the application through a custom implementation of the SubjectTokenProvider trait.

Example

let provider = Arc::new(MyTokenProvider);

let credentials = ProgrammaticBuilder::new(provider)
    .with_audience("//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/my-pool/providers/my-provider".to_string())
    .with_subject_token_type("urn:ietf:params:oauth:token-type:jwt".to_string())
    .with_token_url("https://sts.googleapis.com/v1beta/token".to_string())
    .with_quota_project_id("my-quota-project")
    .with_scopes(vec!["https://www.googleapis.com/auth/devstorage.read_only".to_string()])
    .build()
    .unwrap();

Implementations

impl ProgrammaticBuilder

pub fn new(subject_token_provider: Arc<dyn SubjectTokenProvider>) -> Self

Creates a new builder that uses the provided SubjectTokenProvider to fetch the third-party subject token.

Example

let provider = Arc::new(MyTokenProvider);
let builder = ProgrammaticBuilder::new(provider);

pub fn with_quota_project_id<S: Into<String>>(self, quota_project_id: S) -> Self

Sets the optional quota project for this credentials.

In some services, you can use a service account in one project for authentication and authorization, and charge the usage to a different project. This requires that the service account has serviceusage.services.use permissions on the quota project.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_quota_project_id("my-quota-project");

pub fn with_scopes<I, S>(self, scopes: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Overrides the optional scopes for this credentials. If this method is not called, a default scope will be used.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_scopes(vec!["scope1", "scope2"]);

pub fn with_audience<S: Into<String>>(self, audience: S) -> Self

Sets the required audience for the token exchange.

This is the resource name for the workload identity pool and the provider identifier in that pool.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_audience("my-audience");

pub fn with_subject_token_type<S: Into<String>>( self, subject_token_type: S, ) -> Self

Sets the required subject token type.

This is the STS subject token type based on the OAuth 2.0 token exchange spec.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_subject_token_type("my-token-type");

pub fn with_token_url<S: Into<String>>(self, token_url: S) -> Self

Sets the optional token URL for the STS token exchange. If not provided, https://sts.googleapis.com/v1/token is used.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_token_url("http://my-token-url.com");

pub fn with_client_id<S: Into<String>>(self, client_id: S) -> Self

Sets the optional client ID for client authentication.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_client_id("my-client-id");

pub fn with_client_secret<S: Into<String>>(self, client_secret: S) -> Self

Sets the optional client secret for client authentication.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_client_secret("my-client-secret");

pub fn with_target_principal<S: Into<String>>(self, target_principal: S) -> Self

Sets the optional target principal.

Target principal is the email of the service account to impersonate.

Example

let builder = ProgrammaticBuilder::new(provider)
    .with_target_principal("test-principal");

pub fn with_retry_policy<V: Into<RetryPolicyArg>>(self, v: V) -> Self

Configure the retry policy for fetching tokens.

The retry policy controls how to handle retries, and sets limits on the number of attempts or the total time spent retrying.

use gax::retry_policy::{AlwaysRetry, RetryPolicyExt};
let provider = Arc::new(MyTokenProvider);
let credentials = ProgrammaticBuilder::new(provider)
    .with_audience("test-audience")
    .with_subject_token_type("test-token-type")
    .with_retry_policy(AlwaysRetry.with_attempt_limit(3))
    .build();

pub fn with_backoff_policy<V: Into<BackoffPolicyArg>>(self, v: V) -> Self

Configure the retry backoff policy.

The backoff policy controls how long to wait in between retry attempts.

use gax::exponential_backoff::ExponentialBackoff;
let provider = Arc::new(MyTokenProvider);
let policy = ExponentialBackoff::default();
let credentials = ProgrammaticBuilder::new(provider)
    .with_audience("test-audience")
    .with_subject_token_type("test-token-type")
    .with_backoff_policy(policy)
    .build();

pub fn with_retry_throttler<V: Into<RetryThrottlerArg>>(self, v: V) -> Self

Configure the retry throttler.

Advanced applications may want to configure a retry throttler to Address Cascading Failures and when Handling Overload conditions. The authentication library throttles its retry loop, using a policy to control the throttling algorithm. Use this method to fine tune or customize the default retry throttler.

use gax::retry_throttler::AdaptiveThrottler;
let provider = Arc::new(MyTokenProvider);
let credentials = ProgrammaticBuilder::new(provider)
    .with_audience("test-audience")
    .with_subject_token_type("test-token-type")
    .with_retry_throttler(AdaptiveThrottler::default())
    .build();

pub fn build(self) -> Result<Credentials, Error>

Returns a Credentials instance with the configured settings.

Errors

Returns a BuilderError if any of the required fields (such as audience or subject_token_type) have not been set.