From fa2f3f52464ab76989362fedaf216e0202dbeaad Mon Sep 17 00:00:00 2001 From: Min Zhu Date: Fri, 27 Sep 2024 17:15:50 -0400 Subject: [PATCH] add javadoc comment, rename for readability, rename UNKNOWN to DO_NOT_SEND for clarity. --- .../google/auth/CredentialTypeForMetrics.java | 15 ++++++++++- .../java/com/google/auth/Credentials.java | 19 +++++++++++--- .../auth/oauth2/ComputeEngineCredentials.java | 7 +++--- .../auth/oauth2/ImpersonatedCredentials.java | 6 ++--- .../com/google/auth/oauth2/MetricsUtils.java | 25 +++++++++++++++++-- .../oauth2/ServiceAccountCredentials.java | 8 +++--- .../google/auth/oauth2/UserCredentials.java | 4 +-- .../oauth2/ServiceAccountCredentialsTest.java | 4 ++- 8 files changed, 69 insertions(+), 19 deletions(-) diff --git a/credentials/java/com/google/auth/CredentialTypeForMetrics.java b/credentials/java/com/google/auth/CredentialTypeForMetrics.java index 67a9b84f9..648f0ff36 100644 --- a/credentials/java/com/google/auth/CredentialTypeForMetrics.java +++ b/credentials/java/com/google/auth/CredentialTypeForMetrics.java @@ -31,13 +31,26 @@ package com.google.auth; +/** + * Defines the different types of credentials that can be used for metrics. + * + *

Each credential type is associated with a label that is used for reporting purposes. Add new + * enum constant only when corresponding configs established. + * + *

Credentials with type {@code CredentialTypeForMetrics.DO_NOT_SEND} is default value for + * credential implementations that do not set type specifically. It is not expected to send metrics. + * + *

+ * + * @see #getLabel() + */ public enum CredentialTypeForMetrics { USER_CREDENTIALS("u"), SERVICE_ACCOUNT_CREDENTIALS_AT("sa"), SERVICE_ACCOUNT_CREDENTIALS_JWT("jwt"), VM_CREDENTIALS("mds"), IMPERSONATED_CREDENTIALS("imp"), - UNKNOWN("unknown"); + DO_NOT_SEND("do not send type to metrics"); private String label; diff --git a/credentials/java/com/google/auth/Credentials.java b/credentials/java/com/google/auth/Credentials.java index eeed3efbe..6dea60977 100644 --- a/credentials/java/com/google/auth/Credentials.java +++ b/credentials/java/com/google/auth/Credentials.java @@ -45,7 +45,7 @@ public abstract class Credentials implements Serializable { public static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com"; - private CredentialTypeForMetrics credentialTypeForMetrics = CredentialTypeForMetrics.UNKNOWN; + private CredentialTypeForMetrics credentialTypeForMetrics = CredentialTypeForMetrics.DO_NOT_SEND; /** * A constant string name describing the authentication technology. @@ -72,11 +72,24 @@ public String getUniverseDomain() throws IOException { return GOOGLE_DEFAULT_UNIVERSE; } - public CredentialTypeForMetrics getCredentialType() { + /** + * Gets the credential type used for internal metrics header. + * + * @return a enum value for credential type + */ + public CredentialTypeForMetrics getMetricsCredentialType() { return this.credentialTypeForMetrics; } - public void setCredentialType(CredentialTypeForMetrics credentialTypeForMetrics) { + /** + * Sets the credential type for metrics. + * + *

The default is {@code CredentialTypeForMetrics.DO_NOT_SEND}. For a credential that is + * established to track for metrics, this default should be overridden. + * + * @param credentialTypeForMetrics The credential type to be used for metrics. + */ + public void setMetricsCredentialType(CredentialTypeForMetrics credentialTypeForMetrics) { this.credentialTypeForMetrics = credentialTypeForMetrics; } diff --git a/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java b/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java index 0f8cf44cb..33cd2c8d8 100644 --- a/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java @@ -135,7 +135,7 @@ public class ComputeEngineCredentials extends GoogleCredentials */ private ComputeEngineCredentials(ComputeEngineCredentials.Builder builder) { super(builder); - this.setCredentialType(CredentialTypeForMetrics.VM_CREDENTIALS); + this.setMetricsCredentialType(CredentialTypeForMetrics.VM_CREDENTIALS); this.transportFactory = firstNonNull( builder.getHttpTransportFactory(), @@ -351,7 +351,8 @@ private HttpResponse getMetadataResponse(String url, RequestType requestType) th .getHeaders() .set( MetricsUtils.API_CLIENT_HEADER, - MetricsUtils.getGoogleCredentialsMetricsHeader(requestType, getCredentialType())); + MetricsUtils.getGoogleCredentialsMetricsHeader( + requestType, getMetricsCredentialType())); } request.setThrowExceptionOnExecuteError(false); @@ -458,7 +459,7 @@ private static boolean pingComputeEngineMetadata( .set( MetricsUtils.API_CLIENT_HEADER, MetricsUtils.getGoogleCredentialsMetricsHeader( - RequestType.METADATA_SERVER_PIN, CredentialTypeForMetrics.UNKNOWN)); + RequestType.METADATA_SERVER_PIN, CredentialTypeForMetrics.DO_NOT_SEND)); HttpResponse response = request.execute(); try { // Internet providers can return a generic response to all requests, so it is necessary diff --git a/oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java b/oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java index cb4c8f51a..9706c7698 100644 --- a/oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java @@ -454,7 +454,7 @@ public ImpersonatedCredentials createWithCustomCalendar(Calendar calendar) { private ImpersonatedCredentials(Builder builder) { super(builder); - this.setCredentialType(CredentialTypeForMetrics.IMPERSONATED_CREDENTIALS); + this.setMetricsCredentialType(CredentialTypeForMetrics.IMPERSONATED_CREDENTIALS); this.sourceCredentials = builder.getSourceCredentials(); this.targetPrincipal = builder.getTargetPrincipal(); this.delegates = builder.getDelegates(); @@ -516,7 +516,7 @@ public AccessToken refreshAccessToken() throws IOException { .set( MetricsUtils.API_CLIENT_HEADER, MetricsUtils.getGoogleCredentialsMetricsHeader( - RequestType.ACCESS_TOKEN_REQUEST, getCredentialType())); + RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType())); HttpResponse response = null; try { @@ -567,7 +567,7 @@ public IdToken idTokenWithAudience(String targetAudience, ListFor UserCredentials access token or id token requests, no request type is specified, metric + * header string takes format: “gl-java/JAVA_VERSION auth/LIB_VERSION cred-type/u” + * + *

For MDS pin, credentials type should not include in header, metric header string takes + * format: “gl-java/JAVA_VERSION auth/LIB_VERSION auth-request-type/mds” + * + *

For ServiceAccountCredentials, ComputeEngineCredentials and ImpersonatedCredentials access + * token or id token requests, metric header string takes format “gl-java/JAVA_VERSION + * auth/LIB_VERSION auth-request-type/[it/at] cred-type/[mds/sa/imp]” + * + * @param requestType + * @param credentialTypeForMetrics + * @return + */ static String getGoogleCredentialsMetricsHeader( RequestType requestType, CredentialTypeForMetrics credentialTypeForMetrics) { + // format for UserCredentials requests if (requestType == RequestType.UNSPECIFIED) { return String.format( "%s %s/%s", - MetricsUtils.getLanguageAndAuthLibraryVersions(), "cred-type", credentialTypeForMetrics.getLabel()); + MetricsUtils.getLanguageAndAuthLibraryVersions(), + "cred-type", + credentialTypeForMetrics.getLabel()); } - if (credentialTypeForMetrics == CredentialTypeForMetrics.UNKNOWN) { + // format for MDS pin + if (credentialTypeForMetrics == CredentialTypeForMetrics.DO_NOT_SEND) { return String.format( "%s %s/%s", MetricsUtils.getLanguageAndAuthLibraryVersions(), diff --git a/oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java b/oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java index 33c3c90db..8dc5cbf56 100644 --- a/oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java @@ -512,7 +512,7 @@ public AccessToken refreshAccessToken() throws IOException { .set( MetricsUtils.API_CLIENT_HEADER, MetricsUtils.getGoogleCredentialsMetricsHeader( - RequestType.ACCESS_TOKEN_REQUEST, getCredentialType())); + RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType())); if (this.defaultRetriesEnabled) { request.setNumberOfRetries(OAuth2Utils.DEFAULT_NUMBER_OF_RETRIES); } else { @@ -600,7 +600,7 @@ private IdToken getIdTokenOauthEndpoint(String targetAudience) throws IOExceptio .set( MetricsUtils.API_CLIENT_HEADER, MetricsUtils.getGoogleCredentialsMetricsHeader( - RequestType.ID_TOKEN_REQUEST, getCredentialType())); + RequestType.ID_TOKEN_REQUEST, getMetricsCredentialType())); HttpResponse httpResponse = executeRequest(request); @@ -1030,11 +1030,11 @@ private Map> getRequestMetadataForGdu(URI uri) throws IOExc if ((!createScopedRequired() && !useJwtAccessWithScope) || isConfiguredForDomainWideDelegation()) { // assertion token flow - this.setCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_AT); + this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_AT); return super.getRequestMetadata(uri); } // self-signed JWT flow - this.setCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT); + this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT); return getRequestMetadataWithSelfSignedJwt(uri); } diff --git a/oauth2_http/java/com/google/auth/oauth2/UserCredentials.java b/oauth2_http/java/com/google/auth/oauth2/UserCredentials.java index c516bac3d..699981a73 100644 --- a/oauth2_http/java/com/google/auth/oauth2/UserCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/UserCredentials.java @@ -98,7 +98,7 @@ private UserCredentials(Builder builder) { Preconditions.checkState( builder.getAccessToken() != null || builder.refreshToken != null, "Either accessToken or refreshToken must not be null"); - this.setCredentialType(CredentialTypeForMetrics.USER_CREDENTIALS); + this.setMetricsCredentialType(CredentialTypeForMetrics.USER_CREDENTIALS); } /** @@ -273,7 +273,7 @@ private GenericData doRefreshAccessToken() throws IOException { additionalHeaders.set( MetricsUtils.API_CLIENT_HEADER, MetricsUtils.getGoogleCredentialsMetricsHeader( - RequestType.UNSPECIFIED, getCredentialType())); + RequestType.UNSPECIFIED, getMetricsCredentialType())); request.setHeaders(additionalHeaders); request.setParser(new JsonObjectParser(JSON_FACTORY)); HttpResponse response; diff --git a/oauth2_http/javatests/com/google/auth/oauth2/ServiceAccountCredentialsTest.java b/oauth2_http/javatests/com/google/auth/oauth2/ServiceAccountCredentialsTest.java index 8f165856e..2c8accbeb 100644 --- a/oauth2_http/javatests/com/google/auth/oauth2/ServiceAccountCredentialsTest.java +++ b/oauth2_http/javatests/com/google/auth/oauth2/ServiceAccountCredentialsTest.java @@ -1609,7 +1609,9 @@ public void getRequestMetadata_withScopes_selfSignedJWT() throws IOException { // Verify credentialType is correctly set. This is used for token usage metrics. // Self signed jwt flow doesn’t call any token endpoint, thus no token request metrics. - assertEquals(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT, credentials.getCredentialType()); + assertEquals( + CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT, + credentials.getMetricsCredentialType()); } @Test