JAMES-4210 Add custom IMAP SASL extension example

quantranhong1999 · quantranhong1999 · commit cb204cf4ccb6 · 2026-06-05T17:18:04.000+07:00
Add an EXAMPLE-TOKEN SASL mechanism to examples/custom-imap to demonstrate a custom mechanism, provider extension, and auth.exampleToken configuration.

Add dedicated tests for custom SASL advertisement, successful custom auth, invalid-token rejection, and preserving built-in PLAIN authentication.
diff --git a/examples/custom-imap/README.md b/examples/custom-imap/README.md
@@ -14,6 +14,29 @@ Sample configure file: [imapserver.xml](./sample-configuration/imapserver.xml)
 Note that when `imapPackages` is not provided, James will implicit use
 `org.apache.James.modules.protocols.DefaultImapPackage`
 
+# Creating your own IMAP SASL mechanisms
+
+This example also demonstrates how to add a custom IMAP SASL mechanism.
+The `EXAMPLE-TOKEN` mechanism is declared through `auth.saslMechanisms`,
+its authentication service factory provider is declared through
+`auth.saslAuthenticationServiceFactoryProviderExtensions`, while `auth.exampleToken`
+is a custom configuration block owned by the extension:
+
+```xml
+<auth>
+    <saslMechanisms>PlainSaslMechanism,org.apache.james.examples.imap.sasl.ExampleTokenSaslMechanism</saslMechanisms>
+    <saslAuthenticationServiceFactoryProviderExtensions>org.apache.james.examples.imap.sasl.ExampleTokenSaslAuthenticationServiceFactoryProvider</saslAuthenticationServiceFactoryProviderExtensions>
+    <exampleToken>
+        <expectedToken>secret-token</expectedToken>
+        <authorizedUser>bob@domain.tld</authorizedUser>
+    </exampleToken>
+</auth>
+```
+
+James loads the provider through the extension classloader and instantiates it
+with Guice, so the provider can use James services and parse its own
+configuration block.
+
 ## Running the example
 
 Build the project:
@@ -56,4 +79,23 @@ a02 OK LOGIN completed.
 A03 PING
 * PONG
 A03 OK PING completed.
+A04 LOGOUT
+```
+
+Test the custom SASL mechanism:
+
+```bash
+telnet localhost 143
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+* OK JAMES IMAP4rev1 Server james.local is ready.
+A01 CAPABILITY
+* CAPABILITY IMAP4rev1 AUTH=PLAIN SASL-IR AUTH=EXAMPLE-TOKEN PING
+A01 OK CAPABILITY completed.
+A02 AUTHENTICATE EXAMPLE-TOKEN c2VjcmV0LXRva2Vu
+A02 OK AUTHENTICATE completed.
+A03 PING
+* PONG
+A03 OK PING completed.
 ```
diff --git a/examples/custom-imap/pom.xml b/examples/custom-imap/pom.xml
@@ -67,6 +67,12 @@
       <version>${james.baseVersion}</version>
       <scope>provided</scope>
     </dependency>
+    <dependency>
+      <groupId>${james.protocols.groupId}</groupId>
+      <artifactId>protocols-api</artifactId>
+      <version>${james.baseVersion}</version>
+      <scope>provided</scope>
+    </dependency>
     <dependency>
       <groupId>com.google.inject</groupId>
       <artifactId>guice</artifactId>
diff --git a/examples/custom-imap/sample-configuration/imapserver.xml b/examples/custom-imap/sample-configuration/imapserver.xml
@@ -33,6 +33,14 @@ under the License.
         <connectionLimitPerIP>0</connectionLimitPerIP>
         <plainAuthDisallowed>false</plainAuthDisallowed>
         <gracefulShutdown>false</gracefulShutdown>
+        <auth>
+            <saslMechanisms>PlainSaslMechanism,org.apache.james.examples.imap.sasl.ExampleTokenSaslMechanism</saslMechanisms>
+            <saslAuthenticationServiceFactoryProviderExtensions>org.apache.james.examples.imap.sasl.ExampleTokenSaslAuthenticationServiceFactoryProvider</saslAuthenticationServiceFactoryProviderExtensions>
+            <exampleToken>
+                <expectedToken>secret-token</expectedToken>
+                <authorizedUser>bob@domain.tld</authorizedUser>
+            </exampleToken>
+        </auth>
         <imapPackages>org.apache.james.modules.protocols.DefaultImapPackage</imapPackages>
         <imapPackages>org.apache.james.examples.imap.PingImapPackages</imapPackages>
     </imapserver>
diff --git a/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationService.java b/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationService.java
@@ -0,0 +1,48 @@
+/****************************************************************
+ * 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.james.examples.imap.sasl;
+
+import org.apache.james.imap.processor.sasl.ImapSaslSessionContext;
+import org.apache.james.mailbox.MailboxManager;
+import org.apache.james.mailbox.MailboxSession;
+import org.apache.james.protocols.api.sasl.SaslAuthenticationResult;
+import org.apache.james.protocols.api.sasl.SaslIdentity;
+
+public class ExampleTokenSaslAuthenticationService {
+    private final MailboxManager mailboxManager;
+    private final ImapSaslSessionContext context;
+    private final ExampleTokenSaslConfiguration configuration;
+
+    public ExampleTokenSaslAuthenticationService(MailboxManager mailboxManager, ImapSaslSessionContext context, ExampleTokenSaslConfiguration configuration) {
+        this.mailboxManager = mailboxManager;
+        this.context = context;
+        this.configuration = configuration;
+    }
+
+    public SaslAuthenticationResult authenticate(String token) {
+        if (!configuration.expectedToken().equals(token)) {
+            return new SaslAuthenticationResult.Failure("EXAMPLE-TOKEN authentication failed.");
+        }
+
+        MailboxSession mailboxSession = mailboxManager.createSystemSession(configuration.authorizedUser());
+        context.authenticationSucceeded(mailboxSession);
+        return new SaslAuthenticationResult.Success(new SaslIdentity(configuration.authorizedUser(), configuration.authorizedUser()));
+    }
+}
diff --git a/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationServiceFactory.java b/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationServiceFactory.java
@@ -0,0 +1,56 @@
+/****************************************************************
+ * 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.james.examples.imap.sasl;
+
+import java.util.Optional;
+
+import org.apache.james.imap.processor.sasl.ImapSaslSessionContext;
+import org.apache.james.mailbox.MailboxManager;
+import org.apache.james.protocols.api.sasl.SaslAuthenticationServiceFactory;
+import org.apache.james.protocols.api.sasl.SaslProtocol;
+import org.apache.james.protocols.api.sasl.SaslSessionContext;
+
+public class ExampleTokenSaslAuthenticationServiceFactory implements SaslAuthenticationServiceFactory<ExampleTokenSaslAuthenticationService> {
+    private final MailboxManager mailboxManager;
+    private final ExampleTokenSaslConfiguration configuration;
+
+    public ExampleTokenSaslAuthenticationServiceFactory(MailboxManager mailboxManager, ExampleTokenSaslConfiguration configuration) {
+        this.mailboxManager = mailboxManager;
+        this.configuration = configuration;
+    }
+
+    @Override
+    public SaslProtocol protocol() {
+        return SaslProtocol.IMAP;
+    }
+
+    @Override
+    public Class<ExampleTokenSaslAuthenticationService> serviceType() {
+        return ExampleTokenSaslAuthenticationService.class;
+    }
+
+    @Override
+    public Optional<ExampleTokenSaslAuthenticationService> create(SaslSessionContext context) {
+        if (context instanceof ImapSaslSessionContext imapContext) {
+            return Optional.of(new ExampleTokenSaslAuthenticationService(mailboxManager, imapContext, configuration));
+        }
+        return Optional.empty();
+    }
+}
diff --git a/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationServiceFactoryProvider.java b/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslAuthenticationServiceFactoryProvider.java
@@ -0,0 +1,44 @@
+/****************************************************************
+ * 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.james.examples.imap.sasl;
+
+import org.apache.commons.configuration2.HierarchicalConfiguration;
+import org.apache.commons.configuration2.ex.ConfigurationException;
+import org.apache.commons.configuration2.tree.ImmutableNode;
+import org.apache.james.mailbox.MailboxManager;
+import org.apache.james.modules.protocols.ImapSaslAuthenticationServiceFactoryProvider;
+import org.apache.james.protocols.api.sasl.SaslAuthenticationServiceFactory;
+
+import com.google.common.collect.ImmutableList;
+import com.google.inject.Inject;
+
+public class ExampleTokenSaslAuthenticationServiceFactoryProvider implements ImapSaslAuthenticationServiceFactoryProvider {
+    private final MailboxManager mailboxManager;
+
+    @Inject
+    public ExampleTokenSaslAuthenticationServiceFactoryProvider(MailboxManager mailboxManager) {
+        this.mailboxManager = mailboxManager;
+    }
+
+    @Override
+    public ImmutableList<SaslAuthenticationServiceFactory<?>> provide(HierarchicalConfiguration<ImmutableNode> configuration) throws ConfigurationException {
+        return ImmutableList.of(new ExampleTokenSaslAuthenticationServiceFactory(mailboxManager, ExampleTokenSaslConfiguration.from(configuration)));
+    }
+}
diff --git a/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslConfiguration.java b/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslConfiguration.java
@@ -0,0 +1,43 @@
+/****************************************************************
+ * 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.james.examples.imap.sasl;
+
+import org.apache.commons.configuration2.HierarchicalConfiguration;
+import org.apache.commons.configuration2.ex.ConfigurationException;
+import org.apache.commons.configuration2.tree.ImmutableNode;
+import org.apache.james.core.Username;
+
+public record ExampleTokenSaslConfiguration(String expectedToken, Username authorizedUser) {
+    private static final String EXPECTED_TOKEN_PROPERTY = "auth.exampleToken.expectedToken";
+    private static final String AUTHORIZED_USER_PROPERTY = "auth.exampleToken.authorizedUser";
+
+    public static ExampleTokenSaslConfiguration from(HierarchicalConfiguration<ImmutableNode> configuration) throws ConfigurationException {
+        if (!configuration.containsKey(EXPECTED_TOKEN_PROPERTY)) {
+            throw new ConfigurationException(EXPECTED_TOKEN_PROPERTY + " is mandatory");
+        }
+        if (!configuration.containsKey(AUTHORIZED_USER_PROPERTY)) {
+            throw new ConfigurationException(AUTHORIZED_USER_PROPERTY + " is mandatory");
+        }
+
+        return new ExampleTokenSaslConfiguration(
+            configuration.getString(EXPECTED_TOKEN_PROPERTY),
+            Username.of(configuration.getString(AUTHORIZED_USER_PROPERTY)));
+    }
+}
diff --git a/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslMechanism.java b/examples/custom-imap/src/main/java/org/apache/james/examples/imap/sasl/ExampleTokenSaslMechanism.java
@@ -0,0 +1,108 @@
+/****************************************************************
+ * 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.james.examples.imap.sasl;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Optional;
+import java.util.Set;
+
+import org.apache.james.protocols.api.sasl.SaslAuthenticationResult;
+import org.apache.james.protocols.api.sasl.SaslExchange;
+import org.apache.james.protocols.api.sasl.SaslInitialRequest;
+import org.apache.james.protocols.api.sasl.SaslMechanism;
+import org.apache.james.protocols.api.sasl.SaslProtocol;
+import org.apache.james.protocols.api.sasl.SaslSessionContext;
+import org.apache.james.protocols.api.sasl.SaslStep;
+
+public class ExampleTokenSaslMechanism implements SaslMechanism {
+    public static final String NAME = "EXAMPLE-TOKEN";
+
+    @Override
+    public String name() {
+        return NAME;
+    }
+
+    @Override
+    public boolean supports(SaslProtocol protocol) {
+        return protocol == SaslProtocol.IMAP;
+    }
+
+    @Override
+    public Set<Class<?>> requiredServices(SaslProtocol protocol) {
+        if (supports(protocol)) {
+            return Set.of(ExampleTokenSaslAuthenticationService.class);
+        }
+        return Set.of();
+    }
+
+    @Override
+    public boolean isAvailable(SaslSessionContext context) {
+        return context.service(ExampleTokenSaslAuthenticationService.class).isPresent();
+    }
+
+    @Override
+    public SaslExchange start(SaslInitialRequest request, SaslSessionContext context) {
+        return new ExampleTokenSaslExchange(request.initialResponse(), context);
+    }
+
+    private static class ExampleTokenSaslExchange implements SaslExchange {
+        private final Optional<byte[]> initialResponse;
+        private final SaslSessionContext context;
+
+        private ExampleTokenSaslExchange(Optional<byte[]> initialResponse, SaslSessionContext context) {
+            this.initialResponse = initialResponse;
+            this.context = context;
+        }
+
+        @Override
+        public SaslStep firstStep() {
+            return initialResponse
+                .map(this::authenticate)
+                .orElseGet(() -> new SaslStep.Challenge(Optional.empty()));
+        }
+
+        @Override
+        public SaslStep onResponse(byte[] clientResponse) {
+            return authenticate(clientResponse);
+        }
+
+        @Override
+        public void abort() {
+        }
+
+        @Override
+        public void close() {
+        }
+
+        private SaslStep authenticate(byte[] clientResponse) {
+            return context.service(ExampleTokenSaslAuthenticationService.class)
+                .map(service -> service.authenticate(new String(clientResponse, StandardCharsets.UTF_8)))
+                .map(this::toStep)
+                .orElseGet(() -> new SaslStep.Failure("EXAMPLE-TOKEN authentication is not available."));
+        }
+
+        private SaslStep toStep(SaslAuthenticationResult result) {
+            if (result instanceof SaslAuthenticationResult.Success success) {
+                return new SaslStep.Success(success.identity(), Optional.empty());
+            }
+            return new SaslStep.Failure(((SaslAuthenticationResult.Failure) result).reason());
+        }
+    }
+}
diff --git a/examples/custom-imap/src/main/resources/imapserver.xml b/examples/custom-imap/src/main/resources/imapserver.xml
diff --git a/examples/custom-imap/src/test/java/org/apache/james/examples/imap/CustomSaslMechanismTest.java b/examples/custom-imap/src/test/java/org/apache/james/examples/imap/CustomSaslMechanismTest.java
