ForgeRock Android SDK 4.8.6 Release (#523)

* SDKS-4658: Set code verifier to null for Apple Sign-In

The `codeVerifier` is explicitly set to `null` in the `AuthorizationRequest.Builder` for the Apple Sign-In handler.

* SDKS-4714: Use empty request body in self-service session endpoint (#510)

* SDKS-4714: Use empty request body in self-service session endpoint

Remove the `EMPTY` constant from OkHttp's `RequestBody` and has been replaced with `"".toRequestBody()`.

* Update Session.kt

Signed-off-by: Andy Witrisna <andy.witrisna@forgerock.com>

---------

Signed-off-by: Andy Witrisna <andy.witrisna@forgerock.com>

* Add migration support for Ping SDK with DefaultStorageClient (#511)

* Increase sleep time in FRUserMockTest to ensure token expiration (#513)

The `Thread.sleep` duration in `FRUserMockTest.kt` is increased from 1000ms to 2000ms to allow sufficient time for tokens to expire before testing the refresh token flow.

* ForgeRock Android SDK 4.8.4 Release preparation (#512)

* Updated  for the ForgeRock 4.8.4 release
* Fixed various e2e test cases.

* SDKS-4947 Updating README with maintenance information (#515)

* Updating README with maintenance information

* Rename contribution file name

* SDKS-5037 - Upgrade bcpkix-jdk18on from 1.81 to 1.84 to address CVE-2026-5588 (#516)

* ForgeRock Android SDK 4.8.5 Release preparation (#517)

* Removed Sonatype OSS Index Scan from the CI (this service has been discontinued)

* Updated version number for the ForgeRock 4.8.5 release

* Fix mend tasks to fail the pipeline if critical or high vulnerabilities are found

* SDKS-5096: Enhance WebAuthn registration by adding optional device name (#519)

* SDKS-5096: Enhance WebAuthn registration by adding optional device name parameter

* SDKS-5120: Add authenticationValidityDuration support to device binding and signing (#520)

* SDKS-5120: Allow configurable authenticationValidityDuration in DeviceBindingCallback and DeviceSigningVerifierCallback

* PR review - guard authentication validity duration.

* [fix] SDKS-5114 Handle AM 400 for Push Number Challenge with distinct exception (#521)

* [fix] SDKS-5114 Handle AM 400 for Push Number Challenge with distinct exception

AM 8.1.0 (OPENAM-24154) returns HTTP 400 when a user selects the wrong number
in a Push Number Challenge. Previously the SDK surfaced a generic
PushMechanismException with no semantic meaning. This fix introduces
PushNumberChallengeException (extends PushMechanismException) so callers can
distinguish a wrong-number rejection from other failures, and leaves the
PushNotification in its pending state so the app can offer a retry.

Phases:
- phase 1: Create PushNumberChallengeException (8804d77c)
- phase 2: Handle 400 for Push Number Challenge in PushResponder (fe17bf07)
- phase 3: Unit tests for 400 number-challenge path (4d57f2ca)
- code review: Remove body logging, fix test builder placement (cc910478)

Refs: SDKS-5114

* Addressing comment from Stoyan

* Updated version number for the ForgeRock 4.8.6 release (#522)

---------

Signed-off-by: Andy Witrisna <andy.witrisna@forgerock.com>
Co-authored-by: Andy Witrisna <witrisna@gmail.com>
Co-authored-by: Andy Witrisna <andy.witrisna@forgerock.com>
Co-authored-by: Vibhor Goswami <vibhor.goswami@gmail.com>
Co-authored-by: Rodrigo Reis <rodrigo.reis@forgerock.com>

Author: 4 people

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.8.6]
+
+#### Fixed
+- Fixed an issue where selecting the wrong number in a Push Number Challenge returned a generic error instead of a distinct exception [SDKS-5114]
+- Fixed an issue where the custom device name provided during WebAuthn registration was ignored when `supportsJsonResponse` is enabled. [SDKS-5096]
+- Added configurable `authenticationValidityDuration` to `DeviceBindingCallback` and `DeviceSigningVerifierCallback`, allowing the biometric key authorization window to be extended beyond the default 5 seconds. [SDKS-5120]
+
 ## [4.8.5]
 
 #### Fixed

forgerock-auth/src/main/java/org/forgerock/android/auth/callback/Binding.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -9,6 +9,7 @@ package org.forgerock.android.auth.callback
 import android.os.OperationCanceledException
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.TimeoutCancellationException
+import org.forgerock.android.auth.DEFAULT_AUTHENTICATION_VALIDITY_DURATION
 import org.forgerock.android.auth.Logger
 import org.forgerock.android.auth.devicebind.DeviceAuthenticator
 import org.forgerock.android.auth.devicebind.DeviceBindingErrorStatus.Abort
@@ -22,6 +23,7 @@ import kotlin.time.toDuration
 
 private val TAG = Binding::class.java.simpleName
 
+
 /**
  * Device Binding interface to provide utility method for [DeviceBindingCallback] and [DeviceSigningVerifierCallback]
  */
@@ -83,6 +85,16 @@ interface Binding {
 
     fun setClientError(clientError: String?)
 
+    /**
+     * Validates that [authenticationValidityDuration] is greater than 0.
+     * The Android Keystore treats 0 and -1 as special values that disable the time-based window
+     * and require fresh user authentication on every single key use.
+     * @throws IllegalArgumentException if [value] is not greater than 0
+     */
+    fun validateAuthenticationValidityDuration(value: Int) {
+        require(value > 0) { "authenticationValidityDuration must be greater than 0" }
+    }
+
     /**
      * Default function to identify [DeviceAuthenticator]
      */

forgerock-auth/src/main/java/org/forgerock/android/auth/callback/DeviceBindingCallback.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -9,6 +9,7 @@ package org.forgerock.android.auth.callback
 import android.content.Context
 import android.util.Base64
 import androidx.annotation.Keep
+import org.forgerock.android.auth.DEFAULT_AUTHENTICATION_VALIDITY_DURATION
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -104,6 +105,26 @@ open class DeviceBindingCallback : AbstractCallback, Binding {
     lateinit var attestation: Attestation
         private set
 
+    /**
+     * The duration in seconds for which the generated key remains valid for user authentication
+     * without requiring a fresh biometric/credential prompt. Only affects biometric-backed key
+     * types ([DeviceBindingAuthenticationType.BIOMETRIC_ONLY] and
+     * [DeviceBindingAuthenticationType.BIOMETRIC_ALLOW_FALLBACK]); ignored for [DeviceBindingAuthenticationType.NONE]
+     * and [DeviceBindingAuthenticationType.APPLICATION_PIN].
+     *
+     * Must be greater than 0. The Android Keystore treats 0 and -1 as special values that disable
+     * the time-based window and require fresh user authentication on every single key use — which
+     * is very different from any positive duration. Setting this to 0 or -1 will throw
+     * [IllegalArgumentException].
+     *
+     * Defaults to [DEFAULT_AUTHENTICATION_VALIDITY_DURATION] seconds.
+     */
+    var authenticationValidityDuration: Int = DEFAULT_AUTHENTICATION_VALIDITY_DURATION
+        set(value) {
+            validateAuthenticationValidityDuration(value)
+            field = value
+        }
+
     init {
         //If attestation is not provided, default to NONE
         if (!::attestation.isInitialized) {
@@ -222,7 +243,7 @@ open class DeviceBindingCallback : AbstractCallback, Binding {
                                      .build().identifier,
                                  prompt: Prompt? = null) {
 
-        deviceAuthenticator.initialize(userId, prompt ?: Prompt(title, subtitle, description))
+        deviceAuthenticator.initialize(userId, authenticationValidityDuration, prompt ?: Prompt(title, subtitle, description))
 
         if (deviceAuthenticator.isSupported(context, attestation).not()) {
             handleException(DeviceBindingException(Unsupported()))

forgerock-auth/src/main/java/org/forgerock/android/auth/callback/DeviceSigningVerifierCallback.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -8,6 +8,7 @@ package org.forgerock.android.auth.callback
 
 import android.content.Context
 import androidx.annotation.Keep
+import org.forgerock.android.auth.DEFAULT_AUTHENTICATION_VALIDITY_DURATION
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -114,6 +115,26 @@ open class DeviceSigningVerifierCallback : AbstractCallback, Binding {
         super.setValue(clientError, 1)
     }
 
+    /**
+     * The duration in seconds for which the generated key remains valid for user authentication
+     * without requiring a fresh biometric/credential prompt. Only affects biometric-backed key
+     * types ([DeviceBindingAuthenticationType.BIOMETRIC_ONLY] and
+     * [DeviceBindingAuthenticationType.BIOMETRIC_ALLOW_FALLBACK]); ignored for [DeviceBindingAuthenticationType.NONE]
+     * and [DeviceBindingAuthenticationType.APPLICATION_PIN].
+     *
+     * Must be greater than 0. The Android Keystore treats 0 and -1 as special values that disable
+     * the time-based window and require fresh user authentication on every single key use — which
+     * is very different from any positive duration. Setting this to 0 or -1 will throw
+     * [IllegalArgumentException].
+     *
+     * Defaults to [DEFAULT_AUTHENTICATION_VALIDITY_DURATION] seconds.
+     */
+    var authenticationValidityDuration: Int = DEFAULT_AUTHENTICATION_VALIDITY_DURATION
+        set(value) {
+            validateAuthenticationValidityDuration(value)
+            field = value
+        }
+
     /**
      * Sign the challenge with bounded device keys.
      *
@@ -178,7 +199,7 @@ open class DeviceSigningVerifierCallback : AbstractCallback, Binding {
                                             customClaims: Map<String, Any> = emptyMap(),
                                             prompt: Prompt? = null) {
 
-        deviceAuthenticator.initialize(userKey.userId, prompt?: Prompt(title, subtitle, description))
+        deviceAuthenticator.initialize(userKey.userId, authenticationValidityDuration, prompt?: Prompt(title, subtitle, description))
 
         if (deviceAuthenticator.isSupported(context).not()) {
             handleException(DeviceBindingException(Unsupported()))

forgerock-auth/src/main/java/org/forgerock/android/auth/callback/WebAuthnRegistrationCallback.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  *  This software may be modified and distributed under the terms
  *  of the MIT license. See the LICENSE file for details.
@@ -61,9 +61,9 @@ open class WebAuthnRegistrationCallback : MetadataCallback, WebAuthnCallback {
                 webAuthnRegistration.options = webAuthnRegistration.options.cloneWith(
                     ResidentKeyRequirement.valueOf(it))
             }
-            var result = webAuthnRegistration.register(context)
-            deviceName?.apply { result += "::$deviceName" }
-            setHiddenCallbackValue(node, result);
+
+            val result = webAuthnRegistration.register(context, deviceName)
+            setHiddenCallbackValue(node, result)
         } catch (e: Exception) {
             setErrorRethrow(node, e)
         }

forgerock-auth/src/main/java/org/forgerock/android/auth/devicebind/DeviceBindAuthenticators.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -22,6 +22,7 @@ import com.nimbusds.jwt.SignedJWT
 import kotlinx.parcelize.Parcelize
 import org.forgerock.android.auth.CryptoKey
 import org.forgerock.android.auth.Logger
+import org.forgerock.android.auth.DEFAULT_AUTHENTICATION_VALIDITY_DURATION
 import org.forgerock.android.auth.callback.Attestation
 import org.forgerock.android.auth.callback.DeviceBindingAuthenticationType
 import java.security.PrivateKey
@@ -72,7 +73,10 @@ interface DeviceAuthenticator {
      * @param kid Generated kid from the Preference
      * @param userId userId received from server
      * @param challenge challenge received from server
-     * @param customClaims A map of custom claims to be added to the jws payload
+     * @param expiration token expiration time
+     * @param attestation Attestation type to decide whether to include certificate chain in the JWS header
+     *
+     * @return the signed JWT as String
      */
     fun sign(context: Context,
              keyPair: KeyPair,
@@ -89,7 +93,7 @@ interface DeviceAuthenticator {
         if (attestation !is Attestation.None) {
             builder.x509CertChain(getCertificateChain(userId))
         }
-        val jwk = builder.build();
+        val jwk = builder.build()
         val signedJWT = SignedJWT(JWSHeader.Builder(parse(getAlgorithm()))
             .keyID(kid).jwk(jwk).build(),
             JWTClaimsSet.Builder().subject(userId)
@@ -210,7 +214,16 @@ interface DeviceAuthenticator {
 
 }
 
-fun DeviceAuthenticator.initialize(userId: String, prompt: Prompt): DeviceAuthenticator {
+/**
+ * Initialize the DeviceAuthenticator with userId, authentication validity duration and prompt
+ * @param userId The user ID for which the keys will be generated.
+ * @param authenticationValidityDuration The duration (in seconds) for which the generated key remains valid
+ * for user authentication. Passed to the underlying crypto key during key generation.
+ * @param prompt The Prompt to modify the title, subtitle, description
+ *
+ * @return The initialized DeviceAuthenticator instance.
+ */
+fun DeviceAuthenticator.initialize(userId: String, authenticationValidityDuration: Int, prompt: Prompt): DeviceAuthenticator {
 
     //Inject objects
     if (this is BiometricAuthenticator) {
@@ -219,15 +232,26 @@ fun DeviceAuthenticator.initialize(userId: String, prompt: Prompt): DeviceAuthen
             prompt.description,
             deviceBindAuthenticationType = this.type()))
     }
-    initialize(userId)
+    initialize(userId, authenticationValidityDuration)
     this.prompt(prompt)
     return this
 }
 
-fun DeviceAuthenticator.initialize(userId: String): DeviceAuthenticator {
+/**
+ * Initialize the DeviceAuthenticator with userId and authentication validity duration
+ * @param userId The user ID for which the keys will be generated.
+ * @param authenticationValidityDuration The duration (in seconds) for which the generated key remains valid
+ * for user authentication. Passed to the underlying crypto key during key generation. Defaults to 5 seconds.
+ *
+ * @return The initialized DeviceAuthenticator instance.
+ */
+fun DeviceAuthenticator.initialize(
+    userId: String,
+    authenticationValidityDuration: Int = DEFAULT_AUTHENTICATION_VALIDITY_DURATION,
+): DeviceAuthenticator {
     //Inject objects
     if (this is CryptoAware) {
-        this.setKey(CryptoKey(userId))
+        this.setKey(CryptoKey(userId, authenticationValidityDuration))
     }
     return this
 }

forgerock-auth/src/main/java/org/forgerock/android/auth/webauthn/WebAuthnOutcome.kt

@@ -1,13 +1,15 @@
 /*
- * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2025 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
  */
 
 package org.forgerock.android.auth.webauthn
 
+import android.annotation.SuppressLint
 import kotlinx.serialization.Serializable
 
+@SuppressLint("UnsafeOptInUsageError")
 @Serializable
 data class WebAuthnOutcome(val authenticatorAttachment: String , val legacyData: String)

forgerock-auth/src/main/java/org/forgerock/android/auth/webauthn/WebAuthnRegistration.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 - 2025 Ping Identity Corporation. All rights reserved.
+ * Copyright (c) 2022 - 2026 Ping Identity Corporation. All rights reserved.
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -27,8 +27,6 @@ import kotlinx.coroutines.tasks.await
 import kotlinx.coroutines.withContext
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
-import kotlinx.serialization.json.buildJsonObject
-import kotlinx.serialization.json.put
 import org.forgerock.android.auth.WebAuthnDataRepository
 import org.json.JSONArray
 import org.json.JSONException
@@ -149,7 +147,16 @@ open class WebAuthnRegistration() : WebAuthn() {
         return getCredentials(excludeCredentials)
     }
 
-    suspend fun register(context: Context): String {
+    /**
+     * Registers a new WebAuthn credential.
+     *
+     * @param context Application context used to launch the registration intent.
+     * @param deviceName Optional friendly name appended to the response so the server can label the credential.
+     *
+     * @return The registration outcome as a `::` delimited string, or a JSON-encoded
+     *   [WebAuthnOutcome] when the server supports JSON responses.
+     */
+    suspend fun register(context: Context, deviceName: String? = null): String {
         val publicKeyCredential = getPublicKeyCredential(context)
         val response = publicKeyCredential.response as AuthenticatorAttestationResponse
         val sb = StringBuilder()
@@ -173,10 +180,11 @@ open class WebAuthnRegistration() : WebAuthn() {
                 persist(context, source)
             }
         }
+        deviceName?.let { sb.append("::$it") }
         return if (supportsJsonResponse) {
             val outcome = WebAuthnOutcome(publicKeyCredential.authenticatorAttachment ?: "platform",
                 sb.toString())
-            return Json.encodeToString(outcome)
+            Json.encodeToString(outcome)
         } else {
             sb.toString()
         }