SyncServer: require new server-specific auth options for JWT auth #252

greenrobot-team · greenrobot-team · commit eeb7fe9c44b4 · 2025-03-04T08:23:03.000+01:00
Remove SyncServerBuilder.authenticatorCredentials(SyncCredentials[]),
can just call the existing builder method multiple times or use the
Sync.server helper that accepts multiple credentials.
diff --git a/objectbox-java/src/main/java/io/objectbox/sync/Sync.java b/objectbox-java/src/main/java/io/objectbox/sync/Sync.java
@@ -16,8 +16,6 @@
 
 package io.objectbox.sync;
 
-import javax.annotation.Nullable;
-
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
 import io.objectbox.sync.server.SyncServer;
@@ -85,18 +83,18 @@ public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials[
      * {@code ws://0.0.0.0:9999}.
      * @param authenticatorCredentials An authentication method available to Sync clients and peers. Additional
      * authenticator credentials can be supplied using the returned builder. For the embedded server, currently only
-     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported. When only JWT
-     * authentication should be possible, pass {@code null}.
+     * {@link SyncCredentials#sharedSecret}, any JWT method like {@link SyncCredentials#jwtIdTokenServer()} as well as
+     * {@link SyncCredentials#none} are supported.
      */
-    public static SyncServerBuilder server(BoxStore boxStore, String url, @Nullable SyncCredentials authenticatorCredentials) {
+    public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials authenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, authenticatorCredentials);
     }
 
     /**
      * Like {@link #server(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods
      * for clients and peers.
      */
-    public static SyncServerBuilder server(BoxStore boxStore, String url, @Nullable SyncCredentials[] multipleAuthenticatorCredentials) {
+    public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials[] multipleAuthenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, multipleAuthenticatorCredentials);
     }
 
@@ -115,8 +113,8 @@ public static SyncServerBuilder server(BoxStore boxStore, String url, @Nullable
      * {@code ws://0.0.0.0:9999}.
      * @param authenticatorCredentials An authentication method available to Sync clients and peers. The client of the
      * hybrid is pre-configured with them. Additional credentials can be supplied using the client and server builder of
-     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret} and
-     * {@link SyncCredentials#none} are supported.
+     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret}, any JWT
+     * method like {@link SyncCredentials#jwtIdTokenServer()} as well as {@link SyncCredentials#none} are supported.
      * @return An instance of {@link SyncHybridBuilder}.
      */
     public static SyncHybridBuilder hybrid(BoxStoreBuilder storeBuilder, String url,
diff --git a/objectbox-java/src/main/java/io/objectbox/sync/SyncCredentials.java b/objectbox-java/src/main/java/io/objectbox/sync/SyncCredentials.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -49,47 +49,111 @@ public static SyncCredentials google(String idToken) {
     }
 
     /**
-     * ObjectBox admin users (username/password)
+     * ObjectBox Admin user (username and password).
      */
     public static SyncCredentials obxAdminUser(String user, String password) {
         return new SyncCredentialsUserPassword(CredentialsType.OBX_ADMIN_USER, user, password);
     }
 
     /**
-     * Generic credential type suitable for ObjectBox admin (and possibly others in the future)
+     * Generic credentials type suitable for ObjectBox Admin (and possibly others in the future).
      */
     public static SyncCredentials userAndPassword(String user, String password) {
         return new SyncCredentialsUserPassword(CredentialsType.USER_PASSWORD, user, password);
     }
 
     /**
-     * JSON Web Token (JWT): an ID token that typically provides identity information about the authenticated user.
+     * Authenticate with a JSON Web Token (JWT) that is an ID token.
+     * <p>
+     * An ID token typically provides identity information about the authenticated user.
+     * <p>
+     * Use this and the other JWT methods that accept a token to configure JWT auth for a Sync client or server peer.
+     * To configure Sync server auth options, use the server variants, like {@link #jwtIdTokenServer()}, instead.
+     * <p>
+     * See the <a href="https://sync.objectbox.io/sync-server-configuration/jwt-authentication">JWT authentication documentation</a>
+     * for details.
      */
     public static SyncCredentials jwtIdToken(String jwtIdToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_ID_TOKEN, jwtIdToken);
     }
 
     /**
-     * JSON Web Token (JWT): an access token that is used to access resources.
+     * Authenticate with a JSON Web Token (JWT) that is an access token.
+     * <p>
+     * An access token is used to access resources.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtAccessToken(String jwtAccessToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_ACCESS_TOKEN, jwtAccessToken);
     }
 
     /**
-     * JSON Web Token (JWT): a refresh token that is used to obtain a new access token.
+     * Authenticate with a JSON Web Token (JWT) that is a refresh token.
+     * <p>
+     * A refresh token is used to obtain a new access token.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtRefreshToken(String jwtRefreshToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_REFRESH_TOKEN, jwtRefreshToken);
     }
 
     /**
-     * JSON Web Token (JWT): a token that is neither an ID, access, nor refresh token.
+     * Authenticate with a JSON Web Token (JWT) that is neither an ID, access, nor refresh token.
+     * <p>
+     * See {@link #jwtIdToken(String)} for some common remarks.
      */
     public static SyncCredentials jwtCustomToken(String jwtCustomToken) {
         return new SyncCredentialsToken(CredentialsType.JWT_CUSTOM_TOKEN, jwtCustomToken);
     }
 
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is an ID token.
+     * <p>
+     * An ID token typically provides identity information about the authenticated user.
+     * <p>
+     * Use this and the other JWT server credentials types to configure a Sync server.
+     * For Sync clients, use the ones that accept a token, like {@link #jwtIdToken(String)}, instead.
+     * <p>
+     * See the <a href="https://sync.objectbox.io/sync-server-configuration/jwt-authentication">JWT authentication documentation</a>
+     * for details.
+     */
+    public static SyncCredentials jwtIdTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_ID_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is an access token.
+     * <p>
+     * An access token is used to access resources.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtAccessTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_ACCESS_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is a refresh token.
+     * <p>
+     * A refresh token is used to obtain a new access token.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtRefreshTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_REFRESH_TOKEN);
+    }
+
+    /**
+     * Enable authentication using a JSON Web Token (JWT) that is neither an ID, access, nor refresh token.
+     * <p>
+     * See {@link #jwtIdTokenServer()} for some common remarks.
+     */
+    public static SyncCredentials jwtCustomTokenServer() {
+        return new SyncCredentialsToken(CredentialsType.JWT_CUSTOM_TOKEN);
+    }
+
     /**
      * No authentication, unsecured. Use only for development and testing purposes.
      */
diff --git a/objectbox-java/src/main/java/io/objectbox/sync/SyncCredentialsToken.java b/objectbox-java/src/main/java/io/objectbox/sync/SyncCredentialsToken.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,6 +51,10 @@ public final class SyncCredentialsToken extends SyncCredentials {
         this(type, token.getBytes(StandardCharsets.UTF_8));
     }
 
+    public boolean hasToken() {
+        return token != null;
+    }
+
     @Nullable
     public byte[] getTokenBytes() {
         if (cleared) {
diff --git a/objectbox-java/src/main/java/io/objectbox/sync/server/SyncServerBuilder.java b/objectbox-java/src/main/java/io/objectbox/sync/server/SyncServerBuilder.java
@@ -72,17 +72,18 @@ private static void checkFeatureSyncServerAvailable() {
      * Use {@link Sync#server(BoxStore, String, SyncCredentials)} instead.
      */
     @Internal
-    public SyncServerBuilder(BoxStore boxStore, String url, @Nullable SyncCredentials authenticatorCredentials) {
+    public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials authenticatorCredentials) {
         checkNotNull(boxStore, "BoxStore is required.");
         checkNotNull(url, "Sync server URL is required.");
+        checkNotNull(authenticatorCredentials, "Authenticator credentials are required.");
         checkFeatureSyncServerAvailable();
         this.boxStore = boxStore;
         try {
             this.url = new URI(url);
         } catch (URISyntaxException e) {
             throw new IllegalArgumentException("Sync server URL is invalid: " + url, e);
         }
-        authenticatorCredentialsOrNull(authenticatorCredentials);
+        authenticatorCredentials(authenticatorCredentials);
     }
 
     /**
@@ -100,7 +101,9 @@ public SyncServerBuilder(BoxStore boxStore, String url, SyncCredentials[] multip
         } catch (URISyntaxException e) {
             throw new IllegalArgumentException("Sync server URL is invalid: " + url, e);
         }
-        authenticatorCredentials(multipleAuthenticatorCredentials);
+        for (SyncCredentials credentials : multipleAuthenticatorCredentials) {
+            authenticatorCredentials(credentials);
+        }
     }
 
     /**
@@ -115,48 +118,39 @@ public SyncServerBuilder certificatePath(String certificatePath) {
         return this;
     }
 
-    private SyncServerBuilder authenticatorCredentialsOrNull(@Nullable SyncCredentials authenticatorCredentials) {
-        if (authenticatorCredentials == null) {
-            return this; // Do nothing
-        }
-        if (!(authenticatorCredentials instanceof SyncCredentialsToken)) {
-            throw new IllegalArgumentException("Sync credentials of type " + authenticatorCredentials.getType()
-                    + " are not supported");
-        }
-        credentials.add((SyncCredentialsToken) authenticatorCredentials);
-        return this;
-    }
-
     /**
      * Adds additional authenticator credentials to authenticate clients or peers with.
      * <p>
-     * For the embedded server, currently only {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none}
-     * are supported.
+     * For the embedded server, currently only {@link SyncCredentials#sharedSecret}, any JWT method like
+     * {@link SyncCredentials#jwtIdTokenServer()} as well as {@link SyncCredentials#none} are supported.
      */
     public SyncServerBuilder authenticatorCredentials(SyncCredentials authenticatorCredentials) {
         checkNotNull(authenticatorCredentials, "Authenticator credentials must not be null.");
-        return authenticatorCredentialsOrNull(authenticatorCredentials);
-    }
-
-    /**
-     * Adds additional authenticator credentials to authenticate clients or peers with.
-     * <p>
-     * For the embedded server, currently only {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none}
-     * are supported.
-     */
-    public SyncServerBuilder authenticatorCredentials(SyncCredentials[] multipleAuthenticatorCredentials) {
-        checkNotNull(multipleAuthenticatorCredentials, "Authenticator credentials must not be null.");
-        for (SyncCredentials credentials : multipleAuthenticatorCredentials) {
-            authenticatorCredentials(credentials);
+        if (!(authenticatorCredentials instanceof SyncCredentialsToken)) {
+            throw new IllegalArgumentException("Sync credentials of type " + authenticatorCredentials.getType()
+                    + " are not supported");
         }
+        SyncCredentialsToken tokenCredential = (SyncCredentialsToken) authenticatorCredentials;
+        SyncCredentials.CredentialsType type = tokenCredential.getType();
+        switch (type) {
+            case JWT_ID_TOKEN:
+            case JWT_ACCESS_TOKEN:
+            case JWT_REFRESH_TOKEN:
+            case JWT_CUSTOM_TOKEN:
+                if (tokenCredential.hasToken()) {
+                    throw new IllegalArgumentException("Must not supply a token for a credential of type "
+                            + authenticatorCredentials.getType());
+                }
+        }
+        credentials.add(tokenCredential);
         return this;
     }
 
     /**
      * Sets a listener to observe fine granular changes happening during sync.
      * <p>
-     * This listener can also be {@link SyncServer#setSyncChangeListener(SyncChangeListener) set or removed}
-     * on the Sync server directly.
+     * This listener can also be {@link SyncServer#setSyncChangeListener(SyncChangeListener) set or removed} on the Sync
+     * server directly.
      */
     public SyncServerBuilder changeListener(SyncChangeListener changeListener) {
         this.changeListener = changeListener;
@@ -282,6 +276,10 @@ public SyncServerBuilder workerThreads(int workerThreads) {
      * Sets the public key used to verify JWT tokens.
      * <p>
      * The public key should be in the PEM format.
+     * <p>
+     * However, typically the key is supplied using a JWKS file served from a {@link #jwtPublicKeyUrl(String)}.
+     * <p>
+     * See {@link #jwtPublicKeyUrl(String)} for a common configuration to enable JWT auth.
      */
     public SyncServerBuilder jwtPublicKey(String publicKey) {
         this.jwtPublicKey = publicKey;
@@ -290,6 +288,19 @@ public SyncServerBuilder jwtPublicKey(String publicKey) {
 
     /**
      * Sets the JWKS (Json Web Key Sets) URL to fetch the current public key used to verify JWT tokens.
+     * <p>
+     * A working JWT configuration can look like this:
+     * <pre>{@code
+     * SyncCredentials auth = SyncCredentials.jwtIdTokenServer();
+     * SyncServer server = Sync.server(store, url, auth)
+     *         .jwtPublicKeyUrl("https://example.com/public-key")
+     *         .jwtClaimAud("<audience>")
+     *         .jwtClaimIss("<issuer>")
+     *         .build();
+     * }</pre>
+     *
+     * See the <a href="https://sync.objectbox.io/sync-server-configuration/jwt-authentication">JWT authentication documentation</a>
+     * for details.
      */
     public SyncServerBuilder jwtPublicKeyUrl(String publicKeyUrl) {
         this.jwtPublicKeyUrl = publicKeyUrl;
@@ -298,6 +309,8 @@ public SyncServerBuilder jwtPublicKeyUrl(String publicKeyUrl) {
 
     /**
      * Sets the JWT claim "iss" (issuer) used to verify JWT tokens.
+     *
+     * @see #jwtPublicKeyUrl(String)
      */
     public SyncServerBuilder jwtClaimIss(String claimIss) {
         this.jwtClaimIss = claimIss;
@@ -306,6 +319,8 @@ public SyncServerBuilder jwtClaimIss(String claimIss) {
 
     /**
      * Sets the JWT claim "aud" (audience) used to verify JWT tokens.
+     *
+     * @see #jwtPublicKeyUrl(String)
      */
     public SyncServerBuilder jwtClaimAud(String claimAud) {
         this.jwtClaimAud = claimAud;
@@ -322,7 +337,8 @@ private boolean hasJwtConfig() {
      * Note: this clears all previously set authenticator credentials.
      */
     public SyncServer build() {
-        if (!hasJwtConfig() && credentials.isEmpty()) {
+        // Note: even when only using JWT auth, must supply one of the credentials of JWT type
+        if (credentials.isEmpty()) {
             throw new IllegalStateException("At least one authenticator is required.");
         }
         if (hasJwtConfig()) {
@@ -374,10 +390,7 @@ byte[] buildSyncServerOptions() {
         if (clusterId != null) {
             clusterIdOffset = fbb.createString(clusterId);
         }
-        int authenticationMethodsOffset = 0;
-        if (!credentials.isEmpty()) {
-            authenticationMethodsOffset = buildAuthenticationMethods(fbb);
-        }
+        int authenticationMethodsOffset = buildAuthenticationMethods(fbb);
         int clusterPeersVectorOffset = buildClusterPeers(fbb);
         int jwtConfigOffset = 0;
         if (hasJwtConfig()) {
@@ -396,9 +409,7 @@ byte[] buildSyncServerOptions() {
         // After collecting all offsets, create options
         SyncServerOptions.startSyncServerOptions(fbb);
         SyncServerOptions.addUrl(fbb, urlOffset);
-        if (authenticationMethodsOffset != 0) {
-            SyncServerOptions.addAuthenticationMethods(fbb, authenticationMethodsOffset);
-        }
+        SyncServerOptions.addAuthenticationMethods(fbb, authenticationMethodsOffset);
         if (syncFlags != 0) {
             SyncServerOptions.addSyncFlags(fbb, syncFlags);
         }
