fix: rename credentialId to better show which one it is (keycloak, device) (#92)

Signed-off-by: Dominik Schlosser <dominik.schlosser@gmail.com>

Author: dominikschlosser

docs/flow-details.md

@@ -2,6 +2,20 @@
 
 This document provides detailed technical information about each phase of the enrollment and login flows.
 
+## Credential ID Concepts
+
+Each Push MFA credential has **two distinct IDs**:
+
+| ID | Where | Purpose |
+|----|-------|---------|
+| **Device credential ID** (`deviceCredentialId`) | Set by the device during enrollment; stored in `PushCredentialData`; carried in tokens as `credId`, events as `push_mfa_credential_id`, and push notifications | The mobile app uses this to match incoming pushes to its local credential store. Appears in all external-facing protocols. |
+| **Keycloak credential ID** (`keycloakCredentialId`) | UUID assigned by Keycloak when the `CredentialModel` is persisted; stored on `PushChallenge` | Used internally by the server to load the correct `CredentialModel` from storage. The app never sees this value. |
+
+**Why challenges only store the Keycloak credential ID:** The server picks which credential to use for a challenge and records its Keycloak UUID so it can reload the `CredentialModel` later. The device credential ID is redundant on the challenge because:
+- The app already knows its own device credential ID (it chose it during enrollment).
+- The app receives the device credential ID via the `credId` claim in the confirm token.
+- The server accesses the device credential ID through `PushCredentialData` after loading the `CredentialModel` by its Keycloak UUID.
+
 ## Enrollment Flow
 
 1. **Enrollment challenge (RequiredAction):** Keycloak renders a QR code that encodes the realm-signed `enrollmentToken` (the default theme emits `my-secure://enroll?token=<enrollmentToken>`, but you can change the URI scheme/payload in your own theme or override the server-side prefix via `--spi-required-action-push-mfa-register-app-uri-prefix=...`). The token is a JWT signed with the realm key and contains user id (`sub`), username, `enrollmentId`, and a Base64URL nonce.

docs/spi-reference.md

@@ -13,11 +13,12 @@ public final class MyPushSender implements PushNotificationSender {
                      RealmModel realm,
                      UserModel user,
                      String confirmToken,
-                     String credentialId,
+                     String deviceCredentialId,
                      String challengeId,
                      String pushProviderId,
                      String clientId) {
         // Serialize confirmToken into the mobile push message and deliver it via FCM/APNs/etc.
+        // deviceCredentialId is the device-chosen credential ID (not the Keycloak-internal UUID).
     }
 }
 ```
@@ -57,10 +58,10 @@ The extension provides an event SPI that allows you to react to push MFA lifecyc
 | `ChallengeAcceptedEvent` | User approved the challenge on their device | `challengeId`, `challengeType`, `userId`, `deviceId` |
 | `ChallengeDeniedEvent` | User denied the challenge on their device | `challengeId`, `challengeType`, `userId`, `deviceId` |
 | `ChallengeResponseInvalidEvent` | Response validation failed (bad signature, wrong PIN, etc.) | `challengeId`, `userId`, `reason` |
-| `EnrollmentCompletedEvent` | Device enrollment finished successfully | `challengeId`, `userId`, `credentialId`, `deviceId`, `deviceType` |
-| `KeyRotatedEvent` | Device key was successfully rotated | `userId`, `credentialId`, `deviceId` |
-| `KeyRotationDeniedEvent` | Key rotation request failed validation | `userId`, `credentialId`, `reason` |
-| `DpopAuthenticationFailedEvent` | DPoP authentication failed for device API request | `userId`, `credentialId`, `reason`, `httpMethod`, `requestPath` |
+| `EnrollmentCompletedEvent` | Device enrollment finished successfully | `challengeId`, `userId`, `deviceCredentialId`, `deviceId`, `deviceType` |
+| `KeyRotatedEvent` | Device key was successfully rotated | `userId`, `deviceCredentialId`, `deviceId` |
+| `KeyRotationDeniedEvent` | Key rotation request failed validation | `userId`, `deviceCredentialId`, `reason` |
+| `DpopAuthenticationFailedEvent` | DPoP authentication failed for device API request | `userId`, `deviceCredentialId`, `reason`, `httpMethod`, `requestPath` |
 
 All events include `realmId`, `userId` (may be null for early auth failures), and `timestamp`.
 
@@ -134,7 +135,7 @@ public void onEvent(Event event) {
 | `EVENT_TYPE` | `push_mfa_event_type` |
 | `CHALLENGE_ID` | `push_mfa_challenge_id` |
 | `CHALLENGE_TYPE` | `push_mfa_challenge_type` |
-| `CREDENTIAL_ID` | `push_mfa_credential_id` |
+| `DEVICE_CREDENTIAL_ID` | `push_mfa_credential_id` |
 | `DEVICE_ID` | `push_mfa_device_id` |
 | `DEVICE_TYPE` | `push_mfa_device_type` |
 | `USER_VERIFICATION` | `push_mfa_user_verification` |

src/main/java/de/arbeitsagentur/keycloak/push/auth/ChallengeIssuer.java

@@ -192,7 +192,7 @@ protected void fireChallengeCreatedEvent(
                         pushChallenge.getUserId(),
                         pushChallenge.getId(),
                         pushChallenge.getType(),
-                        credentialData.getCredentialId(),
+                        credentialData.getDeviceCredentialId(),
                         pushChallenge.getClientId(),
                         pushChallenge.getUserVerificationMode(),
                         pushChallenge.getExpiresAt(),
@@ -219,7 +219,7 @@ protected String buildConfirmToken(
         return PushConfirmTokenBuilder.build(
                 context.getSession(),
                 context.getRealm(),
-                credentialData.getCredentialId(),
+                credentialData.getDeviceCredentialId(),
                 pushChallenge.getId(),
                 pushChallenge.getExpiresAt(),
                 context.getUriInfo().getBaseUri());
@@ -234,7 +234,7 @@ protected void logChallengeCreation(PushCredentialData credentialData) {
                 "Push message prepared {version=%d,type=%d,credentialId=%s}",
                 PushMfaConstants.PUSH_MESSAGE_VERSION,
                 PushMfaConstants.PUSH_MESSAGE_TYPE,
-                credentialData.getCredentialId());
+                credentialData.getDeviceCredentialId());
     }
 
     /**
@@ -253,7 +253,7 @@ protected void sendPushNotification(
                 context.getUser(),
                 clientId,
                 confirmToken,
-                credentialData.getCredentialId(),
+                credentialData.getDeviceCredentialId(),
                 pushChallenge.getId(),
                 credentialData.getPushProviderType(),
                 credentialData.getPushProviderId());

src/main/java/de/arbeitsagentur/keycloak/push/auth/ChallengeUrlBuilder.java

@@ -74,7 +74,7 @@ public static String buildSameDeviceToken(
         return PushConfirmTokenBuilder.build(
                 context.getSession(),
                 context.getRealm(),
-                credentialData.getCredentialId(),
+                credentialData.getDeviceCredentialId(),
                 challenge.getId(),
                 challenge.getExpiresAt(),
                 context.getUriInfo().getBaseUri(),

src/main/java/de/arbeitsagentur/keycloak/push/auth/PushMfaAuthenticator.java

@@ -333,11 +333,11 @@ protected void issueAndShowChallenge(
     protected void showWaitingFormForExisting(AuthenticationFlowContext context, PushChallenge ch) {
         CredentialModel cred = resolveCredentialForChallenge(context.getUser(), ch);
         PushCredentialData data = cred != null ? PushCredentialService.readCredentialData(cred) : null;
-        String confirmToken = (data != null && data.getCredentialId() != null)
+        String confirmToken = (data != null && data.getDeviceCredentialId() != null)
                 ? PushConfirmTokenBuilder.build(
                         context.getSession(),
                         context.getRealm(),
-                        data.getCredentialId(),
+                        data.getDeviceCredentialId(),
                         ch.getId(),
                         ch.getExpiresAt(),
                         context.getUriInfo().getBaseUri())
@@ -368,7 +368,7 @@ protected Response createForm(
         form.setAttribute("challengeId", ch != null ? ch.getId() : null)
                 .setAttribute("pushUsername", context.getUser().getUsername())
                 .setAttribute("pushConfirmToken", token)
-                .setAttribute("pushCredentialId", data != null ? data.getCredentialId() : null)
+                .setAttribute("pushCredentialId", data != null ? data.getDeviceCredentialId() : null)
                 .setAttribute("pushMessageVersion", String.valueOf(PushMfaConstants.PUSH_MESSAGE_VERSION))
                 .setAttribute("pushMessageType", String.valueOf(PushMfaConstants.PUSH_MESSAGE_TYPE))
                 .setAttribute("appUniversalLink", appLink)
@@ -481,7 +481,7 @@ protected CredentialAndData resolveCredential(UserModel user) {
         }
         CredentialModel cred = credentials.get(0);
         PushCredentialData data = PushCredentialService.readCredentialData(cred);
-        if (data == null || data.getCredentialId() == null) {
+        if (data == null || data.getDeviceCredentialId() == null) {
             return null;
         }
         return new CredentialAndData(cred, data);
@@ -492,8 +492,8 @@ protected CredentialAndData resolveCredential(UserModel user) {
      * Override to customize credential resolution for existing challenges.
      */
     protected CredentialModel resolveCredentialForChallenge(UserModel user, PushChallenge ch) {
-        if (ch.getCredentialId() != null) {
-            CredentialModel byId = PushCredentialService.getCredentialById(user, ch.getCredentialId());
+        if (ch.getKeycloakCredentialId() != null) {
+            CredentialModel byId = PushCredentialService.getCredentialById(user, ch.getKeycloakCredentialId());
             if (byId != null) {
                 return byId;
             }

src/main/java/de/arbeitsagentur/keycloak/push/challenge/PushChallenge.java

@@ -38,7 +38,16 @@ public enum UserVerificationMode {
     private final String realmId;
     private final String userId;
     private final byte[] nonce;
-    private final String credentialId;
+    /**
+     * The Keycloak-internal credential UUID ({@code CredentialModel.getId()}).
+     *
+     * <p>The server selects which credential to use for a challenge and stores this ID so it can
+     * reload the {@code CredentialModel} later. The mobile app never sees this value; it receives
+     * the device credential ID ({@code PushCredentialData.getDeviceCredentialId()}) via the
+     * {@code credId} claim in the confirm token.
+     */
+    private final String keycloakCredentialId;
+
     private final String clientId;
     private final String watchSecret;
     private final String rootSessionId;
@@ -56,7 +65,7 @@ public PushChallenge(
             String realmId,
             String userId,
             byte[] nonce,
-            String credentialId,
+            String keycloakCredentialId,
             String clientId,
             String watchSecret,
             String rootSessionId,
@@ -70,7 +79,7 @@ public PushChallenge(
                 realmId,
                 userId,
                 nonce,
-                credentialId,
+                keycloakCredentialId,
                 clientId,
                 watchSecret,
                 rootSessionId,
@@ -89,7 +98,7 @@ public PushChallenge(
             String realmId,
             String userId,
             byte[] nonce,
-            String credentialId,
+            String keycloakCredentialId,
             String clientId,
             String watchSecret,
             String rootSessionId,
@@ -105,7 +114,7 @@ public PushChallenge(
         this.realmId = Objects.requireNonNull(realmId);
         this.userId = Objects.requireNonNull(userId);
         this.nonce = Arrays.copyOf(Objects.requireNonNull(nonce), nonce.length);
-        this.credentialId = credentialId;
+        this.keycloakCredentialId = keycloakCredentialId;
         this.clientId = clientId;
         this.watchSecret = watchSecret;
         this.rootSessionId = rootSessionId;
@@ -136,8 +145,8 @@ public byte[] getNonce() {
         return Arrays.copyOf(nonce, nonce.length);
     }
 
-    public String getCredentialId() {
-        return credentialId;
+    public String getKeycloakCredentialId() {
+        return keycloakCredentialId;
     }
 
     public String getClientId() {

src/main/java/de/arbeitsagentur/keycloak/push/challenge/PushChallengeStore.java

@@ -56,7 +56,7 @@ public PushChallenge create(
             byte[] nonceBytes,
             PushChallenge.Type type,
             Duration ttl,
-            String credentialId,
+            String keycloakCredentialId,
             String clientId,
             String watchSecret,
             String rootSessionId) {
@@ -66,7 +66,7 @@ public PushChallenge create(
                 nonceBytes,
                 type,
                 ttl,
-                credentialId,
+                keycloakCredentialId,
                 clientId,
                 watchSecret,
                 rootSessionId,
@@ -81,7 +81,7 @@ public PushChallenge create(
             byte[] nonceBytes,
             PushChallenge.Type type,
             Duration ttl,
-            String credentialId,
+            String keycloakCredentialId,
             String clientId,
             String watchSecret,
             String rootSessionId,
@@ -100,8 +100,8 @@ public PushChallenge create(
         data.put("type", type.name());
         data.put("status", PushChallengeStatus.PENDING.name());
         data.put("createdAt", now.toString());
-        if (credentialId != null) {
-            data.put("credentialId", credentialId);
+        if (keycloakCredentialId != null) {
+            data.put("credentialId", keycloakCredentialId);
         }
         if (clientId != null) {
             data.put("clientId", clientId);
@@ -134,7 +134,7 @@ public PushChallenge create(
                 realmId,
                 userId,
                 nonceBytes,
-                credentialId,
+                keycloakCredentialId,
                 clientId,
                 watchSecret,
                 rootSessionId,

src/main/java/de/arbeitsagentur/keycloak/push/credential/PushCredentialData.java

@@ -21,14 +21,34 @@
 import de.arbeitsagentur.keycloak.push.util.PushMfaConstants;
 import org.keycloak.utils.StringUtil;
 
+/**
+ * Credential data stored with each Push MFA credential.
+ *
+ * <p>This class holds the device-provided data that was submitted during enrollment, including the
+ * device's public key (JWK), push provider details, and the device credential ID.
+ *
+ * <p><strong>Credential ID distinction:</strong> Each Push MFA credential has two IDs:
+ * <ul>
+ *   <li>{@code deviceCredentialId} (this class) - chosen by the device during enrollment and used
+ *       in tokens, events, and push notifications. The mobile app uses this ID to match incoming
+ *       push messages to its local credentials.</li>
+ *   <li>{@code keycloakCredentialId} (on {@link de.arbeitsagentur.keycloak.push.challenge.PushChallenge})
+ *       - the UUID assigned by Keycloak's credential storage. Used internally to load the
+ *       {@code CredentialModel} from the store. The server picks which credential to use for a
+ *       challenge and stores this ID; the app never needs to know it.</li>
+ * </ul>
+ *
+ * <p>The JSON property name {@code "credentialId"} is kept for backward compatibility with
+ * existing stored credentials.
+ */
 public class PushCredentialData {
 
     private final String publicKeyJwk;
     private final long createdAt;
     private final String deviceType;
     private final String pushProviderId;
     private final String pushProviderType;
-    private final String credentialId;
+    private final String deviceCredentialId;
     private final String deviceId;
 
     @JsonCreator
@@ -38,15 +58,15 @@ public PushCredentialData(
             @JsonProperty("deviceType") String deviceType,
             @JsonProperty("pushProviderId") String pushProviderId,
             @JsonProperty("pushProviderType") String pushProviderType,
-            @JsonProperty("credentialId") String credentialId,
+            @JsonProperty("credentialId") String deviceCredentialId,
             @JsonProperty("deviceId") String deviceId) {
         this.publicKeyJwk = publicKeyJwk;
         this.createdAt = createdAt;
         this.deviceType = deviceType;
         this.pushProviderId = pushProviderId;
         this.pushProviderType =
                 StringUtil.isBlank(pushProviderType) ? PushMfaConstants.DEFAULT_PUSH_PROVIDER_TYPE : pushProviderType;
-        this.credentialId = credentialId;
+        this.deviceCredentialId = deviceCredentialId;
         this.deviceId = deviceId;
     }
 
@@ -70,8 +90,15 @@ public String getPushProviderType() {
         return pushProviderType;
     }
 
-    public String getCredentialId() {
-        return credentialId;
+    /**
+     * Returns the device-chosen credential ID, set during enrollment.
+     *
+     * <p>This is NOT the Keycloak-internal credential UUID. See the class-level Javadoc for the
+     * distinction between the two credential IDs.
+     */
+    @JsonProperty("credentialId")
+    public String getDeviceCredentialId() {
+        return deviceCredentialId;
     }
 
     public String getDeviceId() {

src/main/java/de/arbeitsagentur/keycloak/push/credential/PushCredentialProvider.java

@@ -51,8 +51,8 @@ public CredentialModel createCredential(RealmModel realm, UserModel user, Creden
     }
 
     @Override
-    public boolean deleteCredential(RealmModel realm, UserModel user, String credentialId) {
-        return user.credentialManager().removeStoredCredentialById(credentialId);
+    public boolean deleteCredential(RealmModel realm, UserModel user, String keycloakCredentialId) {
+        return user.credentialManager().removeStoredCredentialById(keycloakCredentialId);
     }
 
     @Override

src/main/java/de/arbeitsagentur/keycloak/push/credential/PushCredentialService.java

@@ -54,11 +54,11 @@ public static void updateCredential(UserModel user, CredentialModel credential,
         user.credentialManager().updateStoredCredential(credential);
     }
 
-    public static CredentialModel getCredentialById(UserModel user, String credentialId) {
-        if (StringUtil.isBlank(credentialId)) {
+    public static CredentialModel getCredentialById(UserModel user, String keycloakCredentialId) {
+        if (StringUtil.isBlank(keycloakCredentialId)) {
             return null;
         }
-        CredentialModel model = user.credentialManager().getStoredCredentialById(credentialId);
+        CredentialModel model = user.credentialManager().getStoredCredentialById(keycloakCredentialId);
         if (model == null || !PushMfaConstants.CREDENTIAL_TYPE.equals(model.getType())) {
             return null;
         }