kroxylicious-api+runtime: Add SASL subject builder (kroxylicious#2898)

* kroxylicious-api+runtime: Add SASL subject builder

* Subjects can arise as a result of SASL authentication.
* We add a plugin interface, SaslSubjectBuilderService, following the established convention.
* Because the Principal subtypes are open, the builder provide a plugin point for adding principals to the Subject which are unknown to the kroxylicious-api or -runtime modules.
* We also want to allow the possilibity of using information looked up from external systems such as LDAP/ActiveDirectory or an OAuth token introspection endpoint. Thus the builder has an asynchronous return type.
* The runtime adds a DefaultSubjectBuilder implementation which can be used for SASL-based Subject building.

Signed-off-by: Tom Bentley <[email protected]>

Author: tombentley

kroxylicious-api/src/main/java/io/kroxylicious/proxy/authentication/PrincipalFactory.java

@@ -0,0 +1,11 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.authentication;
+
+public interface PrincipalFactory<P extends Principal> {
+    P newPrincipal(String name);
+}

kroxylicious-api/src/main/java/io/kroxylicious/proxy/authentication/SaslSubjectBuilder.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package io.kroxylicious.proxy.authentication;
+
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+import io.kroxylicious.proxy.tls.ClientTlsContext;
+
+/**
+ * <p>Builds a {@link Subject} based on information available from a successful SASL authentication.</p>
+ *
+ * <p>A {@code SaslSubjectBuilder} instance is constructed by a {@link SaslSubjectBuilderService}.</p>
+ *
+ * <p>A SASL-authenticating {@link io.kroxylicious.proxy.filter.Filter Filter}
+ * <em>may</em> use a {@code SaslSubjectBuilder} in order to construct the
+ * {@link Subject} with which it calls
+ * {@link io.kroxylicious.proxy.filter.FilterContext#clientSaslAuthenticationSuccess(String, Subject)
+ * FilterContext.clientSaslAuthenticationSuccess(String, Subject)}.
+ * As such, {@code SaslSubjectBuilder} is an opt-in way of decoupling the building of Subjects
+ * from the mechanism of SASL authentication.
+ * SASL-authenticating filters are not obliged to use this abstraction.</p>
+ */
+public interface SaslSubjectBuilder {
+
+    /**
+     * Returns an asynchronous result which completes with the {@code Subject} built
+     * from the
+     * @param context
+     * @return
+     */
+    CompletionStage<Subject> buildSaslSubject(SaslSubjectBuilder.Context context);
+
+    /**
+     * The context that's passed to {@link #buildSaslSubject(Context)}.
+     */
+    interface Context {
+        /**
+         * @return The TLS context for the client connection, or empty if the client connection is not TLS.
+         */
+        Optional<ClientTlsContext> clientTlsContext();
+
+        /**
+         * @return The SASL context for the client connection.
+         */
+        ClientSaslContext clientSaslContext();
+    }
+}

kroxylicious-api/src/main/java/io/kroxylicious/proxy/authentication/SaslSubjectBuilderService.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.authentication;
+
+public interface SaslSubjectBuilderService<C> extends AutoCloseable {
+    void initialize(C config);
+
+    SaslSubjectBuilder build();
+
+    default void close() {
+    }
+}

kroxylicious-api/src/main/java/io/kroxylicious/proxy/authentication/UserFactory.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.authentication;
+
+public class UserFactory implements PrincipalFactory<User> {
+    @Override
+    public User newPrincipal(String name) {
+        return new User(name);
+    }
+}

kroxylicious-api/src/main/resources/META-INF/services/io.kroxylicious.proxy.authentication.PrincipalFactory

@@ -0,0 +1,7 @@
+#
+# Copyright Kroxylicious Authors.
+#
+# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+#
+
+io.kroxylicious.proxy.authentication.UserFactory

kroxylicious-runtime/pom.xml

@@ -39,6 +39,10 @@
             <groupId>io.kroxylicious</groupId>
             <artifactId>kroxylicious-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.google.re2j</groupId>
+            <artifactId>re2j</artifactId>
+        </dependency>
 
         <!-- project dependencies - test -->
         <dependency>

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/subject/DefaultSaslSubjectBuilderService.java

@@ -0,0 +1,177 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.subject;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.ServiceLoader;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import io.kroxylicious.proxy.authentication.PrincipalFactory;
+import io.kroxylicious.proxy.authentication.SaslSubjectBuilder;
+import io.kroxylicious.proxy.authentication.SaslSubjectBuilderService;
+import io.kroxylicious.proxy.plugin.Plugin;
+import io.kroxylicious.proxy.plugin.Plugins;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.Nullable;
+
+@Plugin(configType = DefaultSaslSubjectBuilderService.Config.class)
+public class DefaultSaslSubjectBuilderService implements SaslSubjectBuilderService<DefaultSaslSubjectBuilderService.Config> {
+
+    public static final String SASL_AUTHORIZED_ID = "saslAuthorizedId";
+    public static final String ELSE_IDENTITY = "identity";
+    public static final String ELSE_ANONYMOUS = "anonymous";
+
+    /*
+     * subjectBuilder:
+     * - type: DefaultSubjectBuilder
+     * config:
+     * addPrincipals:
+     * - from: clientTlsSubject # a singleton or optional
+     * map:
+     * - sedLike: #CN=(.*?),.*#$1#
+     * - else: identity
+     * principalFactory: UserFactory
+     * - from: clientTlsSubject
+     * map:
+     * - sedLike: #.*,OU=(.*?).*#$1#
+     * - else: anonymous
+     * principalFactory: RoleFactory
+     * - from: LdapMemerOf # multi valued
+     * map:
+     * - sedLike: #.*,OU=(.*?).*#$1#
+     * - else: anonymous
+     */
+    public record Config(List<PrincipalAdderConf> addPrincipals) {
+
+    }
+
+    /**
+     * Configuration for a principal adder, which is responsible for contributing zero or more principals to the subject.
+     * @param from Names a function for extracting a string value from a {@link SaslSubjectBuilder.Context}.
+     * @param map An optional list of mappings to apply to the `from`-extracted string.
+     * @param principalFactory The name of a {@link PrincipalFactory} implementation class.
+     */
+    public record PrincipalAdderConf(@JsonProperty(required = true) String from,
+                                     @Nullable List<Map> map,
+                                     @JsonProperty(required = true) String principalFactory) {
+        public PrincipalAdderConf {
+            // call methods for validation side-effect
+            buildExtractor(from);
+            buildMappingRules(map);
+            buildPrincipalFactory(principalFactory);
+        }
+    }
+
+    record Map(@Nullable String replaceMatch,
+               @JsonProperty("else") @Nullable String else_) {
+        Map {
+            if (replaceMatch != null) {
+                if (else_ != null) {
+                    throw new IllegalArgumentException("`replaceMatch` and `else` are mutually exclusive.");
+                }
+                new ReplaceMatchMappingRule(replaceMatch);
+            }
+            else if (else_ == null) {
+                throw new IllegalArgumentException("Exactly one of `replaceMatch` and `else` are required.");
+            }
+            else if (!else_.equals(ELSE_IDENTITY)
+                    && !else_.equals(ELSE_ANONYMOUS)) {
+                throw new IllegalArgumentException("`else` can only take the value 'identity' or 'anonymous'.");
+            }
+        }
+    }
+
+    List<PrincipalAdder> adders;
+
+    @Override
+    public void initialize(Config config) {
+        adders = Plugins.requireConfig(this, config).addPrincipals().stream()
+                .map(addConf -> new PrincipalAdder(buildExtractor(addConf.from()),
+                        buildMappingRules(addConf.map()),
+                        buildPrincipalFactory(addConf.principalFactory())))
+                .toList();
+    }
+
+    private static PrincipalFactory<?> buildPrincipalFactory(String principalFactory) {
+        return ServiceLoader.load(PrincipalFactory.class).stream()
+                .filter(provider -> provider.type().getName().equals(principalFactory))
+                .findFirst()
+                .orElseThrow(() -> new IllegalArgumentException("`principalFactory` '%s' not found.".formatted(principalFactory)))
+                .get();
+    }
+
+    @NonNull
+    private static List<MappingRule> buildMappingRules(List<Map> maps) {
+        if (maps == null || maps.isEmpty()) {
+            return List.of(new IdentityMappingRule());
+        }
+        int firstElseIndex = -1;
+        int numElses = 0;
+        for (int i = 0; i < maps.size(); i++) {
+            Map m = maps.get(i);
+
+            if (m.else_() != null) {
+                numElses++;
+                if (firstElseIndex == -1) {
+                    firstElseIndex = i;
+                }
+            }
+        }
+        if (numElses > 1) {
+            throw new IllegalArgumentException("An `else` mapping may only occur at most once, as the last element of `map`.");
+        }
+        else if (firstElseIndex != -1 && firstElseIndex < maps.size() - 1) {
+            throw new IllegalArgumentException("An `else` mapping may only occur as the last element of `map`.");
+        }
+        return maps.stream().map(DefaultSaslSubjectBuilderService::buildMappingRule).toList();
+    }
+
+    @NonNull
+    private static MappingRule buildMappingRule(Map map) {
+        if (map.replaceMatch() != null) {
+            return new ReplaceMatchMappingRule(map.replaceMatch());
+        }
+        else if (ELSE_IDENTITY.equals(map.else_())) {
+            return new IdentityMappingRule();
+        }
+        else if (ELSE_ANONYMOUS.equals(map.else_())) {
+            return s -> Optional.empty();
+        }
+        else {
+            throw new IllegalArgumentException("Unknown `else` map '%s', supported values are: '%s', '%s'."
+                    .formatted(map.else_(), ELSE_IDENTITY, ELSE_ANONYMOUS));
+        }
+    }
+
+    @NonNull
+    private static Function<Object, Stream<String>> buildExtractor(String from) {
+        return switch (from) {
+            case SASL_AUTHORIZED_ID -> context -> Stream.of(((SaslSubjectBuilder.Context) context).clientSaslContext().authorizationId());
+            default -> throw new IllegalArgumentException("Unknown `from` '%s', supported values are: %s."
+                    .formatted(from,
+                            Stream.of(SASL_AUTHORIZED_ID).map(s -> '\'' + s + '\'')
+                                    .collect(Collectors.joining(", "))));
+        };
+    }
+
+    @Override
+    public SaslSubjectBuilder build() {
+        return new DefaultSubjectBuilder(adders);
+    }
+
+    @Override
+    public void close() {
+        // We have no closeable resources
+    }
+
+}

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/subject/DefaultSubjectBuilder.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.subject;
+
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.stream.Collectors;
+
+import io.kroxylicious.proxy.authentication.Principal;
+import io.kroxylicious.proxy.authentication.SaslSubjectBuilder;
+import io.kroxylicious.proxy.authentication.Subject;
+
+public class DefaultSubjectBuilder implements SaslSubjectBuilder {
+    private final List<PrincipalAdder> adders;
+
+    public DefaultSubjectBuilder(List<PrincipalAdder> adders) {
+        this.adders = adders;
+    }
+
+    @Override
+    public CompletionStage<Subject> buildSaslSubject(SaslSubjectBuilder.Context context) {
+        try {
+            Set<Principal> collect = adders.stream()
+                    .flatMap(lal -> lal.createPrincipals(context))
+                    .collect(Collectors.toSet());
+            return CompletableFuture.completedStage(new Subject(collect));
+        }
+        catch (Exception e) {
+            return CompletableFuture.failedStage(e);
+        }
+    }
+}

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/subject/IdentityMappingRule.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.subject;
+
+import java.util.Optional;
+
+public class IdentityMappingRule implements MappingRule {
+    @Override
+    public Optional<String> apply(String s) {
+        return Optional.of(s);
+    }
+}

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/subject/MappingRule.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.subject;
+
+import java.util.Optional;
+import java.util.function.Function;
+
+public interface MappingRule extends Function<String, Optional<String>> {
+
+}