Simplify the environment variables needed for credential bootstrapping

polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisCredentialsBootstrap.java

@@ -0,0 +1,110 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.polaris.core.persistence;
+
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Splitter;
+import jakarta.annotation.Nullable;
+import java.util.AbstractMap.SimpleEntry;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Optional;
+import org.apache.polaris.core.entity.PolarisPrincipalSecrets;
+
+/**
+ * A utility to parse and provide credentials for Polaris realms and principals during a bootstrap
+ * phase.
+ */
+public class PolarisCredentialsBootstrap {
+
+  /**
+   * Parse credentials from the system property {@code polaris.bootstrap.credentials} or the
+   * environment variable {@code POLARIS_BOOTSTRAP_CREDENTIALS}, whichever is set.
+   *
+   * <p>See {@link #fromString(String)} for the expected format.
+   */
+  public static PolarisCredentialsBootstrap fromEnvironment() {
+    return fromString(
+        System.getProperty(
+            "polaris.bootstrap.credentials", System.getenv().get("POLARIS_BOOTSTRAP_CREDENTIALS")));
+  }
+
+  /**
+   * Parse a string of credentials in the format:
+   *
+   * <pre>
+   * realm1,user1a,client1a,secret1a;realm1,user1b,client1b,secret1b;realm2,user2a,client2a,secret2a;...
+   * </pre>
+   */
+  public static PolarisCredentialsBootstrap fromString(@Nullable String credentialsString) {
+    Map<String, Map<String, Map.Entry<String, String>>> credentials = new HashMap<>();
+    if (credentialsString != null && !credentialsString.isBlank()) {
+      Splitter.on(';')
+          .trimResults()
+          .splitToList(credentialsString)
+          .forEach(
+              quadruple -> {
+                if (!quadruple.isBlank()) {
+                  List<String> parts = Splitter.on(',').trimResults().splitToList(quadruple);
+                  if (parts.size() != 4) {
+                    throw new IllegalArgumentException("Invalid credentials format: " + quadruple);
+                  }
+                  String realmName = parts.get(0);
+                  String principalName = parts.get(1);
+                  String clientId = parts.get(2);
+                  String clientSecret = parts.get(3);
+                  credentials
+                      .computeIfAbsent(realmName, k -> new HashMap<>())
+                      .merge(
+                          principalName,
+                          new SimpleEntry<>(clientId, clientSecret),
+                          (a, b) -> {
+                            throw new IllegalArgumentException(
+                                "Duplicate principal: " + principalName);
+                          });
+                }
+              });
+    }
+    return new PolarisCredentialsBootstrap(credentials);
+  }
+
+  @VisibleForTesting final Map<String, Map<String, Map.Entry<String, String>>> credentials;
+
+  private PolarisCredentialsBootstrap(Map<String, Map<String, Entry<String, String>>> credentials) {
+    this.credentials = credentials;
+  }
+
+  /**
+   * Get the secrets for the specified principal in the specified realm, if available among the
+   * credentials that were supplied for bootstrap.
+   */
+  public Optional<PolarisPrincipalSecrets> getSecrets(
+      String realmName, long principalId, String principalName) {
+    return Optional.ofNullable(credentials.get(realmName))
+        .flatMap(principals -> Optional.ofNullable(principals.get(principalName)))
+        .map(
+            credentials -> {
+              String clientId = credentials.getKey();
+              String secret = credentials.getValue();
+              return new PolarisPrincipalSecrets(principalId, clientId, secret, secret);
+            });
+  }
+}

polaris-core/src/main/java/org/apache/polaris/core/persistence/PrincipalSecretsGenerator.java

@@ -19,27 +19,20 @@
 package org.apache.polaris.core.persistence;
 
 import jakarta.annotation.Nonnull;
-import java.util.Locale;
-import java.util.function.Function;
+import jakarta.annotation.Nullable;
+import java.util.Optional;
 import org.apache.polaris.core.entity.PolarisPrincipalSecrets;
 
 /**
  * An interface for generating principal secrets. It enables detaching the secret generation logic
  * from services that actually manage principal objects (create, remove, rotate secrets, etc.)
  *
  * <p>The implementation statically available from {@link #bootstrap(String)} allows one-time client
- * ID and secret overrides via environment variables, which can be useful for bootstrapping new
- * realms.
+ * ID and secret overrides via system properties or environment variables, which can be useful for
+ * bootstrapping new realms.
  *
- * <p>The environment variable name follow this pattern:
- *
- * <ul>
- *   <li>{@code POLARIS_BOOTSTRAP_<REALM-NAME>_<PRINCIPAL-NAME>_CLIENT_ID}
- *   <li>{@code POLARIS_BOOTSTRAP_<REALM-NAME>_<PRINCIPAL-NAME>_CLIENT_SECRET}
- * </ul>
- *
- * For example: {@code POLARIS_BOOTSTRAP_DEFAULT-REALM_ROOT_CLIENT_ID} and {@code
- * POLARIS_BOOTSTRAP_DEFAULT-REALM_ROOT_CLIENT_SECRET}.
+ * <p>See {@link PolarisCredentialsBootstrap} for more information on the expected environment
+ * variable name, and the format of the bootstrap credentials.
  */
 @FunctionalInterface
 public interface PrincipalSecretsGenerator {
@@ -63,23 +56,14 @@ public interface PrincipalSecretsGenerator {
   PolarisPrincipalSecrets produceSecrets(@Nonnull String principalName, long principalId);
 
   static PrincipalSecretsGenerator bootstrap(String realmName) {
-    return bootstrap(realmName, System.getenv()::get);
+    return bootstrap(realmName, PolarisCredentialsBootstrap.fromEnvironment());
   }
 
-  static PrincipalSecretsGenerator bootstrap(String realmName, Function<String, String> config) {
-    return (principalName, principalId) -> {
-      String propId = String.format("POLARIS_BOOTSTRAP_%s_%s_CLIENT_ID", realmName, principalName);
-      String propSecret =
-          String.format("POLARIS_BOOTSTRAP_%s_%s_CLIENT_SECRET", realmName, principalName);
-
-      String clientId = config.apply(propId.toUpperCase(Locale.ROOT));
-      String secret = config.apply(propSecret.toUpperCase(Locale.ROOT));
-      // use config values at most once (do not interfere with secret rotation)
-      if (clientId != null && secret != null) {
-        return new PolarisPrincipalSecrets(principalId, clientId, secret, secret);
-      } else {
-        return RANDOM_SECRETS.produceSecrets(principalName, principalId);
-      }
-    };
+  static PrincipalSecretsGenerator bootstrap(
+      String realmName, @Nullable PolarisCredentialsBootstrap credentialsSupplier) {
+    return (principalName, principalId) ->
+        Optional.ofNullable(credentialsSupplier)
+            .flatMap(credentials -> credentials.getSecrets(realmName, principalId, principalName))
+            .orElseGet(() -> RANDOM_SECRETS.produceSecrets(principalName, principalId));
   }
 }

polaris-core/src/test/java/org/apache/polaris/core/persistence/PolarisCredentialsBootstrapTest.java

@@ -0,0 +1,106 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.polaris.core.persistence;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Comparator;
+import org.apache.polaris.core.entity.PolarisPrincipalSecrets;
+import org.junit.jupiter.api.Test;
+
+class PolarisCredentialsBootstrapTest {
+
+  private final Comparator<PolarisPrincipalSecrets> comparator =
+      (a, b) ->
+          a.getPrincipalId() == b.getPrincipalId()
+                  && a.getPrincipalClientId().equals(b.getPrincipalClientId())
+                  && a.getMainSecret().equals(b.getMainSecret())
+                  && a.getSecondarySecret().equals(b.getSecondarySecret())
+              ? 0
+              : 1;
+
+  @Test
+  void nullString() {
+    PolarisCredentialsBootstrap credentials = PolarisCredentialsBootstrap.fromString(null);
+    assertThat(credentials.credentials).isEmpty();
+  }
+
+  @Test
+  void emptyString() {
+    PolarisCredentialsBootstrap credentials = PolarisCredentialsBootstrap.fromString("");
+    assertThat(credentials.credentials).isEmpty();
+  }
+
+  @Test
+  void blankString() {
+    PolarisCredentialsBootstrap credentials = PolarisCredentialsBootstrap.fromString("  ");
+    assertThat(credentials.credentials).isEmpty();
+  }
+
+  @Test
+  void invalidString() {
+    assertThatThrownBy(() -> PolarisCredentialsBootstrap.fromString("test"))
+        .hasMessage("Invalid credentials format: test");
+  }
+
+  @Test
+  void duplicatePrincipal() {
+    assertThatThrownBy(
+            () ->
+                PolarisCredentialsBootstrap.fromString(
+                    "realm1,user1a,client1a,secret1a;realm1,user1a,client1b,secret1b"))
+        .hasMessage("Duplicate principal: user1a");
+  }
+
+  @Test
+  void getSecretsValidString() {
+    PolarisCredentialsBootstrap credentials =
+        PolarisCredentialsBootstrap.fromString(
+            " ; realm1 , user1a , client1a , secret1a ; realm1 , user1b , client1b , secret1b ; realm2 , user2a , client2a , secret2a ; ");
+    assertThat(credentials.getSecrets("realm1", 123, "nonexistent")).isEmpty();
+    assertThat(credentials.getSecrets("nonexistent", 123, "user1a")).isEmpty();
+    assertThat(credentials.getSecrets("realm1", 123, "user1a"))
+        .usingValueComparator(comparator)
+        .contains(new PolarisPrincipalSecrets(123, "client1a", "secret1a", "secret1a"));
+    assertThat(credentials.getSecrets("realm1", 123, "user1b"))
+        .usingValueComparator(comparator)
+        .contains(new PolarisPrincipalSecrets(123, "client1b", "secret1b", "secret1b"));
+    assertThat(credentials.getSecrets("realm2", 123, "user2a"))
+        .usingValueComparator(comparator)
+        .contains(new PolarisPrincipalSecrets(123, "client2a", "secret2a", "secret2a"));
+  }
+
+  @Test
+  void getSecretsValidSystemProperty() {
+    PolarisCredentialsBootstrap credentials = PolarisCredentialsBootstrap.fromEnvironment();
+    assertThat(credentials.credentials).isEmpty();
+    try {
+      System.setProperty("polaris.bootstrap.credentials", "realm1,user1a,client1a,secret1a");
+      credentials = PolarisCredentialsBootstrap.fromEnvironment();
+      assertThat(credentials.getSecrets("realm1", 123, "nonexistent")).isEmpty();
+      assertThat(credentials.getSecrets("nonexistent", 123, "user1a")).isEmpty();
+      assertThat(credentials.getSecrets("realm1", 123, "user1a"))
+          .usingValueComparator(comparator)
+          .contains(new PolarisPrincipalSecrets(123, "client1a", "secret1a", "secret1a"));
+    } finally {
+      System.clearProperty("polaris.bootstrap.credentials");
+    }
+  }
+}

polaris-core/src/test/java/org/apache/polaris/core/persistence/PrincipalSecretsGeneratorTest.java

@@ -21,15 +21,14 @@
 import static org.apache.polaris.core.persistence.PrincipalSecretsGenerator.bootstrap;
 import static org.assertj.core.api.Assertions.assertThat;
 
-import java.util.Map;
 import org.apache.polaris.core.entity.PolarisPrincipalSecrets;
 import org.junit.jupiter.api.Test;
 
 class PrincipalSecretsGeneratorTest {
 
   @Test
   void testRandomSecrets() {
-    PolarisPrincipalSecrets s = bootstrap("test", (name) -> null).produceSecrets("name1", 123);
+    PolarisPrincipalSecrets s = bootstrap("test", null).produceSecrets("name1", 123);
     assertThat(s).isNotNull();
     assertThat(s.getPrincipalId()).isEqualTo(123);
     assertThat(s.getPrincipalClientId()).isNotNull();
@@ -41,13 +40,7 @@ void testRandomSecrets() {
   void testSecretOverride() {
     PrincipalSecretsGenerator gen =
         bootstrap(
-            "test-Realm",
-            Map.of(
-                    "POLARIS_BOOTSTRAP_TEST-REALM_USER1_CLIENT_ID",
-                    "client1",
-                    "POLARIS_BOOTSTRAP_TEST-REALM_USER1_CLIENT_SECRET",
-                    "sec2")
-                ::get);
+            "test-Realm", PolarisCredentialsBootstrap.fromString("test-Realm,user1,client1,sec2"));
     PolarisPrincipalSecrets s = gen.produceSecrets("user1", 123);
     assertThat(s).isNotNull();
     assertThat(s.getPrincipalId()).isEqualTo(123);

site/content/in-dev/unreleased/configuring-polaris-for-production.md

@@ -72,17 +72,24 @@ To use EclipseLink for metastore management, specify the configuration `metaStor
 
 Before using Polaris when using a metastore manager other than `in-memory`, you must **bootstrap** the metastore manager. This is a manual operation that must be performed **only once** in order to prepare the metastore manager to integrate with Polaris. When the metastore manager is bootstrapped, any existing Polaris entities in the metastore manager may be **purged**.
 
-By default, Polaris will create randomised `CLIENT_ID` and `CLIENT_SECRET` for the `root` principal and store their hashes in the metastore backend. In order to provide your own credentials for `root` principal (so you can request tokens via `api/catalog/v1/oauth/tokens`), set the following envrionment variables for realm name `my_realm`:
+By default, Polaris will create randomised `CLIENT_ID` and `CLIENT_SECRET` for the `root` principal and store their hashes in the metastore backend. In order to provide your own credentials for `root` principal (so you can request tokens via `api/catalog/v1/oauth/tokens`), set the `POLARIS_BOOTSTRAP_CREDENTIALS` environment variable as follows:
 
 ```
-export POLARIS_BOOTSTRAP_MY_REALM_ROOT_CLIENT_ID=my-client-id
-export POLARIS_BOOTSTRAP_MY_REALM_ROOT_CLIENT_SECRET=my-client-secret
+export POLARIS_BOOTSTRAP_CREDENTIALS=my_realm,root,my-client-id,my-client-secret
 ```
 
-**IMPORTANT**: In case you use `default-realm` for metastore backend database, you won't be able to use `export` command. Use this instead:
+The format of the environment variable is `realm,principal,client_id,client_secret`. You can provide multiple credentials separated by `;`. For example, to provide credentials for two realms `my_realm` and `my_realm2`:
 
-```bash
-env POLARIS_BOOTSTRAP_DEFAULT-REALM_ROOT_CLIENT_ID=my-client-id POLARIS_BOOTSTRAP_DEFAULT-REALM_ROOT_CLIENT_SECRET=my-client-secret <bootstrap command> 
+```
+export POLARIS_BOOTSTRAP_CREDENTIALS=my_realm,root,my-client-id,my-client-secret;my_realm2,root,my-client-id2,my-client-secret2
+```
+
+You can also provide credentials for other users too. 
+
+It is also possible to use system properties to provide the credentials:
+
+```
+java -Dpolaris.bootstrap.credentials=my_realm,root,my-client-id,my-client-secret -jar /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml
 ```
 
 Now, to bootstrap Polaris, run: