feat: multi universe support, adding universe_domain field (#1282)

* feat: adding universe_domain field

* fix: move universe_domain to very base Credential, tests cleanup

* feat: refactor ExternalAccount to use base class universe domain, update tests

* fix: deprecating a duplicate universeDomain field

* fix: docs update for Credentials.java

* getUniverseDomain throws IOExcpetion, more tests

---------

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>

credentials/java/com/google/auth/Credentials.java

@@ -43,6 +43,8 @@ public abstract class Credentials implements Serializable {
 
   private static final long serialVersionUID = 808575179767517313L;
 
+  public static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
+
   /**
    * A constant string name describing the authentication technology.
    *
@@ -54,6 +56,20 @@ public abstract class Credentials implements Serializable {
    */
   public abstract String getAuthenticationType();
 
+  /**
+   * Gets the universe domain for the credential in a blocking manner, refreshing tokens if
+   * required.
+   *
+   * @return a universe domain value in the format some-domain.xyz. By default, returns the Google
+   *     universe domain googleapis.com.
+   * @throws IOException extending classes might have to do remote calls to determine the universe
+   *     domain. The exception must implement {@link Retryable} and {@code isRetryable()} will
+   *     return true if the operation may be retried.
+   */
+  public String getUniverseDomain() throws IOException {
+    return GOOGLE_DEFAULT_UNIVERSE;
+  }
+
   /**
    * Get the current request metadata, refreshing tokens if required.
    *

oauth2_http/java/com/google/auth/oauth2/ExternalAccountAuthorizedUserCredentials.java

@@ -245,6 +245,7 @@ public static Builder newBuilder() {
   public int hashCode() {
     return Objects.hash(
         super.hashCode(),
+        getAccessToken(),
         clientId,
         clientSecret,
         refreshToken,
@@ -281,6 +282,7 @@ public boolean equals(Object obj) {
     ExternalAccountAuthorizedUserCredentials credentials =
         (ExternalAccountAuthorizedUserCredentials) obj;
     return super.equals(credentials)
+        && Objects.equals(this.getAccessToken(), credentials.getAccessToken())
         && Objects.equals(this.clientId, credentials.clientId)
         && Objects.equals(this.clientSecret, credentials.clientSecret)
         && Objects.equals(this.refreshToken, credentials.refreshToken)

oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java

@@ -95,7 +95,6 @@ abstract static class CredentialSource implements java.io.Serializable {
   @Nullable private final String serviceAccountImpersonationUrl;
   @Nullable private final String clientId;
   @Nullable private final String clientSecret;
-  @Nullable private final String universeDomain;
 
   // This is used for Workforce Pools. It is passed to the Security Token Service during token
   // exchange in the `options` param and will be embedded in the token by the Security Token
@@ -215,7 +214,6 @@ protected ExternalAccountCredentials(
     this.environmentProvider =
         environmentProvider == null ? SystemEnvironmentProvider.getInstance() : environmentProvider;
     this.workforcePoolUserProject = null;
-    this.universeDomain = null;
     this.serviceAccountImpersonationOptions =
         new ServiceAccountImpersonationOptions(new HashMap<String, Object>());
 
@@ -269,8 +267,6 @@ protected ExternalAccountCredentials(ExternalAccountCredentials.Builder builder)
           "The workforce_pool_user_project parameter should only be provided for a Workforce Pool configuration.");
     }
 
-    this.universeDomain = builder.universeDomain;
-
     validateTokenUrl(tokenUrl);
     if (serviceAccountImpersonationUrl != null) {
       validateServiceAccountImpersonationInfoUrl(serviceAccountImpersonationUrl);
@@ -593,11 +589,6 @@ public String getWorkforcePoolUserProject() {
     return workforcePoolUserProject;
   }
 
-  @Nullable
-  String getUniverseDomain() {
-    return universeDomain;
-  }
-
   @Nullable
   public ServiceAccountImpersonationOptions getServiceAccountImpersonationOptions() {
     return serviceAccountImpersonationOptions;
@@ -734,7 +725,12 @@ public abstract static class Builder extends GoogleCredentials.Builder {
     @Nullable protected Collection<String> scopes;
     @Nullable protected String workforcePoolUserProject;
     @Nullable protected ServiceAccountImpersonationOptions serviceAccountImpersonationOptions;
-    @Nullable protected String universeDomain;
+
+    /* The field is not being used and value not set. Superseded by the same field in the
+    {@link GoogleCredential.Builder}.
+    */
+    @Nullable @Deprecated protected String universeDomain;
+
     @Nullable protected ExternalAccountMetricsHandler metricsHandler;
 
     protected Builder() {}
@@ -754,7 +750,6 @@ protected Builder(ExternalAccountCredentials credentials) {
       this.environmentProvider = credentials.environmentProvider;
       this.workforcePoolUserProject = credentials.workforcePoolUserProject;
       this.serviceAccountImpersonationOptions = credentials.serviceAccountImpersonationOptions;
-      this.universeDomain = credentials.universeDomain;
       this.metricsHandler = credentials.metricsHandler;
     }
 
@@ -928,8 +923,9 @@ public Builder setServiceAccountImpersonationOptions(Map<String, Object> options
      * @return this {@code Builder} object
      */
     @CanIgnoreReturnValue
+    @Override
     public Builder setUniverseDomain(String universeDomain) {
-      this.universeDomain = universeDomain;
+      super.setUniverseDomain(universeDomain);
       return this;
     }
 

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

@@ -35,7 +35,10 @@
 import com.google.api.client.json.JsonFactory;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.Preconditions;
+import com.google.auth.Credentials;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.collect.ImmutableList;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.io.IOException;
@@ -47,6 +50,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import javax.annotation.Nullable;
 
 /** Base type for credentials for authorizing calls to Google APIs using OAuth2. */
@@ -59,6 +63,8 @@ public class GoogleCredentials extends OAuth2Credentials implements QuotaProject
   static final String SERVICE_ACCOUNT_FILE_TYPE = "service_account";
   static final String GDCH_SERVICE_ACCOUNT_FILE_TYPE = "gdch_service_account";
 
+  private final String universeDomain;
+
   protected final String quotaProjectId;
 
   private static final DefaultCredentialsProvider defaultCredentialsProvider =
@@ -71,7 +77,10 @@ public class GoogleCredentials extends OAuth2Credentials implements QuotaProject
    * @return the credentials instance
    */
   public static GoogleCredentials create(AccessToken accessToken) {
-    return GoogleCredentials.newBuilder().setAccessToken(accessToken).build();
+    return GoogleCredentials.newBuilder()
+        .setAccessToken(accessToken)
+        .setUniverseDomain(Credentials.GOOGLE_DEFAULT_UNIVERSE)
+        .build();
   }
 
   /**
@@ -170,6 +179,7 @@ public static GoogleCredentials fromStream(
     if (fileType == null) {
       throw new IOException("Error reading credentials from stream, 'type' field not specified.");
     }
+
     if (USER_FILE_TYPE.equals(fileType)) {
       return UserCredentials.fromJson(fileContents, transportFactory);
     }
@@ -186,14 +196,20 @@ public static GoogleCredentials fromStream(
         fileType)) {
       return ExternalAccountAuthorizedUserCredentials.fromJson(fileContents, transportFactory);
     }
-    if ("impersonated_service_account".equals(fileType)) {
+    if (ImpersonatedCredentials.IMPERSONATED_CREDENTIALS_FILE_TYPE.equals(fileType)) {
       return ImpersonatedCredentials.fromJson(fileContents, transportFactory);
     }
     throw new IOException(
         String.format(
             "Error reading credentials from stream, 'type' value '%s' not recognized."
-                + " Expecting '%s' or '%s'.",
-            fileType, USER_FILE_TYPE, SERVICE_ACCOUNT_FILE_TYPE));
+                + " Valid values are '%s', '%s', '%s', '%s', '%s', '%s'.",
+            fileType,
+            USER_FILE_TYPE,
+            SERVICE_ACCOUNT_FILE_TYPE,
+            GDCH_SERVICE_ACCOUNT_FILE_TYPE,
+            ExternalAccountCredentials.EXTERNAL_ACCOUNT_FILE_TYPE,
+            ExternalAccountAuthorizedUserCredentials.EXTERNAL_ACCOUNT_AUTHORIZED_USER_FILE_TYPE,
+            ImpersonatedCredentials.IMPERSONATED_CREDENTIALS_FILE_TYPE));
   }
 
   /**
@@ -206,6 +222,27 @@ public GoogleCredentials createWithQuotaProject(String quotaProject) {
     return this.toBuilder().setQuotaProjectId(quotaProject).build();
   }
 
+  /**
+   * Gets the universe domain for the credential.
+   *
+   * @return An explicit universe domain if it was explicitly provided, invokes the super
+   *     implementation otherwise
+   */
+  @Override
+  public String getUniverseDomain() throws IOException {
+    return this.universeDomain;
+  }
+
+  /**
+   * Checks if universe domain equals to {@link Credentials#GOOGLE_DEFAULT_UNIVERSE}.
+   *
+   * @return true if universeDomain equals to {@link Credentials#GOOGLE_DEFAULT_UNIVERSE}, false
+   *     otherwise
+   */
+  boolean isDefaultUniverseDomain() {
+    return this.universeDomain.equals(Credentials.GOOGLE_DEFAULT_UNIVERSE);
+  }
+
   /**
    * Adds quota project ID to requestMetadata if present.
    *
@@ -237,33 +274,97 @@ protected GoogleCredentials() {
     this(new Builder());
   }
 
+  /**
+   * Constructor with an explicit access token and quotaProjectId.
+   *
+   * <p>Deprecated, please use the {@link GoogleCredentials#GoogleCredentials(Builder)} constructor
+   * whenever possible.
+   *
+   * @param accessToken initial or temporary access token
+   * @param quotaProjectId a quotaProjectId, a project id to be used for billing purposes
+   */
+  @Deprecated
   protected GoogleCredentials(AccessToken accessToken, String quotaProjectId) {
     super(accessToken);
     this.quotaProjectId = quotaProjectId;
+    this.universeDomain = Credentials.GOOGLE_DEFAULT_UNIVERSE;
   }
 
   /**
    * Constructor with explicit access token.
    *
    * @param accessToken initial or temporary access token
    */
+  @Deprecated
   public GoogleCredentials(AccessToken accessToken) {
     this(accessToken, null);
   }
 
+  /**
+   * Constructor that relies on a {@link GoogleCredential.Builder} to provide all the necessary
+   * field values for initialization.
+   *
+   * @param builder an instance of a builder
+   */
   protected GoogleCredentials(Builder builder) {
-    this(builder.getAccessToken(), builder.getQuotaProjectId());
+    super(builder.getAccessToken());
+    this.quotaProjectId = builder.getQuotaProjectId();
+
+    if (builder.universeDomain == null || builder.universeDomain.trim().isEmpty()) {
+      this.universeDomain = Credentials.GOOGLE_DEFAULT_UNIVERSE;
+    } else {
+      this.universeDomain = builder.getUniverseDomain();
+    }
   }
 
   /**
-   * Constructor with explicit access token and refresh times
+   * Constructor with explicit access token and refresh margins.
+   *
+   * <p>Deprecated, please use the {@link GoogleCredentials#GoogleCredentials(Builder)} constructor
+   * whenever possible.
    *
    * @param accessToken initial or temporary access token
    */
+  @Deprecated
   protected GoogleCredentials(
       AccessToken accessToken, Duration refreshMargin, Duration expirationMargin) {
     super(accessToken, refreshMargin, expirationMargin);
     this.quotaProjectId = null;
+    this.universeDomain = Credentials.GOOGLE_DEFAULT_UNIVERSE;
+  }
+
+  /**
+   * A helper for overriding the toString() method. This allows inheritance of super class fields.
+   * Extending classes can override this implementation and call super implementation and add more
+   * fields. Same cannot be done with overriding the toString() directly.
+   *
+   * @return an instance of the ToStringHelper that has public fields added
+   */
+  protected ToStringHelper toStringHelper() {
+    return MoreObjects.toStringHelper(this)
+        .omitNullValues()
+        .add("quotaProjectId", this.quotaProjectId)
+        .add("universeDomain", this.universeDomain);
+  }
+
+  @Override
+  public String toString() {
+    return toStringHelper().toString();
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    if (!(obj instanceof GoogleCredentials)) {
+      return false;
+    }
+    GoogleCredentials other = (GoogleCredentials) obj;
+    return Objects.equals(this.quotaProjectId, other.quotaProjectId)
+        && Objects.equals(this.universeDomain, other.universeDomain);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(this.quotaProjectId, this.universeDomain);
   }
 
   public static Builder newBuilder() {
@@ -348,12 +449,20 @@ public GoogleCredentials createDelegated(String user) {
 
   public static class Builder extends OAuth2Credentials.Builder {
     @Nullable protected String quotaProjectId;
+    @Nullable protected String universeDomain;
 
     protected Builder() {}
 
     protected Builder(GoogleCredentials credentials) {
       setAccessToken(credentials.getAccessToken());
       this.quotaProjectId = credentials.quotaProjectId;
+      this.universeDomain = credentials.universeDomain;
+    }
+
+    protected Builder(GoogleCredentials.Builder builder) {
+      setAccessToken(builder.getAccessToken());
+      this.quotaProjectId = builder.quotaProjectId;
+      this.universeDomain = builder.universeDomain;
     }
 
     public GoogleCredentials build() {
@@ -366,10 +475,19 @@ public Builder setQuotaProjectId(String quotaProjectId) {
       return this;
     }
 
+    public Builder setUniverseDomain(String universeDomain) {
+      this.universeDomain = universeDomain;
+      return this;
+    }
+
     public String getQuotaProjectId() {
       return this.quotaProjectId;
     }
 
+    public String getUniverseDomain() {
+      return this.universeDomain;
+    }
+
     @Override
     @CanIgnoreReturnValue
     public Builder setAccessToken(AccessToken token) {

oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java

@@ -93,6 +93,8 @@
 public class ImpersonatedCredentials extends GoogleCredentials
     implements ServiceAccountSigner, IdTokenProvider {
 
+  static final String IMPERSONATED_CREDENTIALS_FILE_TYPE = "impersonated_service_account";
+
   private static final long serialVersionUID = -2133257318957488431L;
   private static final String RFC3339 = "yyyy-MM-dd'T'HH:mm:ssX";
   private static final int TWELVE_HOURS_IN_SECONDS = 43200;