JAVA-2953: Promote ProgrammaticPlainTextAuthProvider to the public API and add credentials hot-reload (#1564)

Author: adutra

changelog/README.md

@@ -4,6 +4,8 @@
 
 ### 4.13.0 (in progress)
 
+- [improvement] JAVA-2953: Promote ProgrammaticPlainTextAuthProvider to the public API and add
+  credentials hot-reload
 - [improvement] JAVA-2951: Accept multiple node state listeners, schema change listeners and request trackers
 
 Merged from 4.12.x:

core/src/main/java/com/datastax/dse/driver/internal/core/auth/DseProgrammaticPlainTextAuthProvider.java

@@ -36,7 +36,8 @@
  * Common infrastructure for plain text auth providers.
  *
  * <p>This can be reused to write an implementation that retrieves the credentials from another
- * source than the configuration.
+ * source than the configuration. The driver offers one built-in implementation: {@link
+ * ProgrammaticPlainTextAuthProvider}.
  */
 @ThreadSafe
 public abstract class PlainTextAuthProviderBase implements AuthProvider {
@@ -58,6 +59,9 @@ protected PlainTextAuthProviderBase(@NonNull String logPrefix) {
    * Retrieves the credentials from the underlying source.
    *
    * <p>This is invoked every time the driver opens a new connection.
+   *
+   * @param endPoint The endpoint being contacted.
+   * @param serverAuthenticator The authenticator class sent by the endpoint.
    */
   @NonNull
   protected abstract Credentials getCredentials(

core/src/main/java/com/datastax/oss/driver/api/core/auth/PlainTextAuthProviderBase.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.core.auth;
+
+import com.datastax.oss.driver.api.core.metadata.EndPoint;
+import com.datastax.oss.driver.api.core.session.SessionBuilder;
+import com.datastax.oss.driver.internal.core.util.Strings;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import java.util.Objects;
+import net.jcip.annotations.ThreadSafe;
+
+/**
+ * A simple plaintext {@link AuthProvider} that receives the credentials programmatically instead of
+ * pulling them from the configuration.
+ *
+ * <p>To use this class, create an instance with the appropriate credentials to use and pass it to
+ * your session builder:
+ *
+ * <pre>
+ * AuthProvider authProvider = new ProgrammaticPlainTextAuthProvider("...", "...");
+ * CqlSession session =
+ *     CqlSession.builder()
+ *         .addContactEndPoints(...)
+ *         .withAuthProvider(authProvider)
+ *         .build();
+ * </pre>
+ *
+ * <p>It also offers the possibility of changing the credentials at runtime. The new credentials
+ * will be used for all connections initiated after the change.
+ *
+ * <p>Implementation Note: this implementation is not particularly suited for highly-sensitive
+ * applications: it stores the credentials to use as private fields, and even if the fields are char
+ * arrays rather than strings to make it difficult to dump their contents, they are never cleared
+ * until the provider itself is garbage-collected, which typically only happens when the session is
+ * closed.
+ *
+ * @see SessionBuilder#withAuthProvider(AuthProvider)
+ * @see SessionBuilder#withAuthCredentials(String, String)
+ * @see SessionBuilder#withAuthCredentials(String, String, String)
+ */
+@ThreadSafe
+public class ProgrammaticPlainTextAuthProvider extends PlainTextAuthProviderBase {
+
+  private volatile char[] username;
+  private volatile char[] password;
+  private volatile char[] authorizationId;
+
+  /** Builds an instance for simple username/password authentication. */
+  public ProgrammaticPlainTextAuthProvider(@NonNull String username, @NonNull String password) {
+    this(username, password, "");
+  }
+
+  /**
+   * Builds an instance for username/password authentication, and proxy authentication with the
+   * given authorizationId.
+   *
+   * <p>This feature is only available with Datastax Enterprise. If the target server is Apache
+   * Cassandra, use {@link #ProgrammaticPlainTextAuthProvider(String, String)} instead, or set the
+   * authorizationId to an empty string.
+   */
+  public ProgrammaticPlainTextAuthProvider(
+      @NonNull String username, @NonNull String password, @NonNull String authorizationId) {
+    // This will typically be built before the session so we don't know the log prefix yet. Pass an
+    // empty string, it's only used in one log message.
+    super("");
+    this.username = Strings.requireNotEmpty(username, "username").toCharArray();
+    this.password = Strings.requireNotEmpty(password, "password").toCharArray();
+    this.authorizationId =
+        Objects.requireNonNull(authorizationId, "authorizationId cannot be null").toCharArray();
+  }
+
+  /**
+   * Changes the username.
+   *
+   * <p>The new credentials will be used for all connections initiated after this method was called.
+   *
+   * @param username the new name.
+   */
+  public void setUsername(@NonNull String username) {
+    this.username = Strings.requireNotEmpty(username, "username").toCharArray();
+  }
+
+  /**
+   * Changes the password.
+   *
+   * <p>The new credentials will be used for all connections initiated after this method was called.
+   *
+   * @param password the new password.
+   */
+  public void setPassword(@NonNull String password) {
+    this.password = Strings.requireNotEmpty(password, "password").toCharArray();
+  }
+
+  /**
+   * Changes the authorization id.
+   *
+   * <p>The new credentials will be used for all connections initiated after this method was called.
+   *
+   * <p>This feature is only available with Datastax Enterprise. If the target server is Apache
+   * Cassandra, this method should not be used.
+   *
+   * @param authorizationId the new authorization id.
+   */
+  public void setAuthorizationId(@NonNull String authorizationId) {
+    this.authorizationId =
+        Objects.requireNonNull(authorizationId, "authorizationId cannot be null").toCharArray();
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * <p>This implementation disregards the endpoint being connected to as well as the authenticator
+   * class sent by the server, and always returns the same credentials.
+   */
+  @NonNull
+  @Override
+  protected Credentials getCredentials(
+      @NonNull EndPoint endPoint, @NonNull String serverAuthenticator) {
+    return new Credentials(username.clone(), password.clone(), authorizationId.clone());
+  }
+}

core/src/main/java/com/datastax/oss/driver/api/core/auth/ProgrammaticPlainTextAuthProvider.java

@@ -19,6 +19,7 @@
 import com.datastax.oss.driver.api.core.CqlSession;
 import com.datastax.oss.driver.api.core.auth.AuthProvider;
 import com.datastax.oss.driver.api.core.auth.PlainTextAuthProviderBase;
+import com.datastax.oss.driver.api.core.auth.ProgrammaticPlainTextAuthProvider;
 import com.datastax.oss.driver.api.core.config.DefaultDriverOption;
 import com.datastax.oss.driver.api.core.config.DriverConfig;
 import com.datastax.oss.driver.api.core.config.DriverConfigLoader;
@@ -37,7 +38,6 @@
 import com.datastax.oss.driver.api.core.type.codec.registry.MutableCodecRegistry;
 import com.datastax.oss.driver.api.core.uuid.Uuids;
 import com.datastax.oss.driver.internal.core.ContactPoints;
-import com.datastax.oss.driver.internal.core.auth.ProgrammaticPlainTextAuthProvider;
 import com.datastax.oss.driver.internal.core.config.cloud.CloudConfig;
 import com.datastax.oss.driver.internal.core.config.cloud.CloudConfigFactory;
 import com.datastax.oss.driver.internal.core.config.typesafe.DefaultDriverConfigLoader;

core/src/main/java/com/datastax/oss/driver/api/core/session/SessionBuilder.java

@@ -46,7 +46,11 @@
  * }
  * </pre>
  *
- * See {@code reference.conf} (in the manual or core driver JAR) for more details.
+ * The authentication provider cannot be changed at runtime; however, the credentials can be changed
+ * at runtime: the new ones will be used for new connection attempts once the configuration gets
+ * {@linkplain com.datastax.oss.driver.api.core.config.DriverConfigLoader#reload() reloaded}.
+ *
+ * <p>See {@code reference.conf} (in the manual or core driver JAR) for more details.
  */
 @ThreadSafe
 public class PlainTextAuthProvider extends PlainTextAuthProviderBase {

core/src/main/java/com/datastax/oss/driver/internal/core/auth/PlainTextAuthProvider.java

@@ -18,6 +18,7 @@
 import com.datastax.oss.driver.shaded.guava.common.annotations.VisibleForTesting;
 import com.datastax.oss.driver.shaded.guava.common.collect.ImmutableSet;
 import java.util.Locale;
+import java.util.Objects;
 
 public class Strings {
 
@@ -255,6 +256,21 @@ public static boolean isLongLiteral(String str) {
     return true;
   }
 
+  /**
+   * Checks whether the given text is not null and not empty.
+   *
+   * @param text The text to check.
+   * @param name The name of the argument.
+   * @return The text (for method chaining).
+   */
+  public static String requireNotEmpty(String text, String name) {
+    Objects.requireNonNull(text, name + " cannot be null");
+    if (text.isEmpty()) {
+      throw new IllegalArgumentException(name + " cannot be empty");
+    }
+    return text;
+  }
+
   private Strings() {}
 
   private static final ImmutableSet<String> RESERVED_KEYWORDS =