Skip to content

Commit 4e5a0d0

Browse files
authored
docs(auth): clarify quota project behavior on ImpersonatedCredentials (#14597)
Fixes #12604 ### Summary Clarifies the Javadoc on `ImpersonatedCredentials` (`Builder.setQuotaProjectId`, `idTokenWithAudience`, and `create` overloads) regarding how `quotaProjectId` is applied: - The `quotaProjectId` configured on `ImpersonatedCredentials` is sent via the `x-goog-user-project` header on **downstream API requests** authenticated with the impersonated credentials. - Requests to the IAM Credentials API (`generateAccessToken` and `generateIdToken`) used to mint tokens are authenticated using `sourceCredentials`. To specify a quota project (`x-goog-user-project` header) for those IAM Credentials API calls, the quota project ID should be configured on `sourceCredentials`.
1 parent 0c481bd commit 4e5a0d0

1 file changed

Lines changed: 32 additions & 7 deletions

File tree

‎google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -179,9 +179,12 @@ public static ImpersonatedCredentials create(
179179
* the credentials.
180180
* @param transportFactory HTTP transport factory that creates the transport used to get access
181181
* tokens.
182-
* @param quotaProjectId the project used for quota and billing purposes. Should be null unless
183-
* the caller wants to use a project different from the one that owns the impersonated
184-
* credential for billing/quota purposes.
182+
* @param quotaProjectId the project used for quota and billing purposes on downstream requests
183+
* made with the impersonated credentials. Should be null unless the caller wants to use a
184+
* project different from the one that owns the impersonated credential for billing/quota
185+
* purposes. Note that this does not apply to the IAM Credentials API requests used to mint
186+
* tokens ({@code generateAccessToken} or {@code generateIdToken}); to specify a quota project
187+
* for those calls, set the quota project ID on {@code sourceCredentials}.
185188
* @return new credentials
186189
*/
187190
public static ImpersonatedCredentials create(
@@ -223,9 +226,12 @@ public static ImpersonatedCredentials create(
223226
* the credentials.
224227
* @param transportFactory HTTP transport factory that creates the transport used to get access
225228
* tokens.
226-
* @param quotaProjectId the project used for quota and billing purposes. Should be null unless
227-
* the caller wants to use a project different from the one that owns the impersonated
228-
* credential for billing/quota purposes.
229+
* @param quotaProjectId the project used for quota and billing purposes on downstream requests
230+
* made with the impersonated credentials. Should be null unless the caller wants to use a
231+
* project different from the one that owns the impersonated credential for billing/quota
232+
* purposes. Note that this does not apply to the IAM Credentials API requests used to mint
233+
* tokens ({@code generateAccessToken} or {@code generateIdToken}); to specify a quota project
234+
* for those calls, set the quota project ID on {@code sourceCredentials}.
229235
* @param iamEndpointOverride The full IAM endpoint override with the target_principal embedded.
230236
* This is useful when supporting impersonation with regional endpoints.
231237
* @return new credentials
@@ -675,8 +681,14 @@ public AccessToken refreshAccessToken() throws IOException {
675681
/**
676682
* Returns an IdToken for the current Credential.
677683
*
684+
* <p>The {@code generateIdToken} request to the IAM Credentials API is authenticated using {@link
685+
* #getSourceCredentials() sourceCredentials}. To specify a quota project ({@code
686+
* x-goog-user-project} header) for the {@code generateIdToken} call itself, configure the quota
687+
* project ID on {@code sourceCredentials} rather than on this {@code ImpersonatedCredentials}
688+
* instance.
689+
*
678690
* @param targetAudience the audience field for the issued ID token
679-
* @param options credential specific options for for the token. For example, an ID token for an
691+
* @param options credential specific options for the token. For example, an ID token for an
680692
* ImpersonatedCredentials can return the email address within the token claims if
681693
* "ImpersonatedCredentials.INCLUDE_EMAIL" is provided as a list option.<br>
682694
* Only one option value is supported: "ImpersonatedCredentials.INCLUDE_EMAIL" If no options
@@ -867,6 +879,19 @@ public Builder setHttpTransportFactory(@Nullable HttpTransportFactory transportF
867879
return transportFactory;
868880
}
869881

882+
/**
883+
* Sets the quota project ID applied to downstream API requests made with the impersonated
884+
* credentials (sent via the {@code x-goog-user-project} header).
885+
*
886+
* <p>Note: This quota project ID is not sent on the IAM Credentials API calls ({@code
887+
* generateAccessToken} or {@code generateIdToken}) used to mint tokens, because those requests
888+
* are authenticated using {@code sourceCredentials}. To specify a quota project for the IAM
889+
* Credentials API requests, set the quota project ID on {@code sourceCredentials} instead.
890+
*
891+
* @param quotaProjectId the project ID used for quota and billing purposes on downstream
892+
* requests
893+
* @return the builder
894+
*/
870895
@Override
871896
@CanIgnoreReturnValue
872897
public Builder setQuotaProjectId(@Nullable String quotaProjectId) {

0 commit comments

Comments
 (0)