fix docs, fail eary on empty certificate

Author: zibet27

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/src/io/ktor/server/auth/saml/SamlConfig.kt

@@ -78,14 +78,14 @@ public class SamlConfig internal constructor(
      *
      * ## Example
      * ```kotlin
-     * val sp = SamlSpMetadata {
+     * val spMetadata = SamlSpMetadata {
      *     spEntityId = "https://myapp.example.com/saml/metadata"
      *     acsUrl = "https://myapp.example.com/saml/acs"
-     *     keyStore { ... }
+     *     signingCredential = SamlCrypto.loadCredential(...)
      * }
      *
      * saml("saml-auth") {
-     *     sp = sp
+     *     sp = spMetadata
      *     idp = parseSamlIdpMetadata(xmlString)
      * }
      * ```

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/src/io/ktor/server/auth/saml/SamlMetadata.kt

@@ -366,8 +366,8 @@ private fun EntityDescriptor.extractIdPMetadata(validateCertificateExpiration: B
 
     // Extract signing certificates
     val signingCredentials = idpDescriptor.extractSigningCredentials(validateCertificateExpiration)
-    if (signingCredentials.isEmpty()) {
-        LOGGER.warn("No signing certificates found in IdP metadata. Signature verification will fail.")
+    require(signingCredentials.isNotEmpty()) {
+        "No signing certificates found in IdP metadata. Signature verification will fail."
     }
 
     return IdPMetadata(

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/src/io/ktor/server/auth/saml/SamlPrincipal.kt

@@ -9,8 +9,6 @@ import org.opensaml.saml.saml2.core.*
 /**
  * Represents an unverified SAML credential extracted from a SAML response.
  *
- * It should only be used during the authentication process and never exposed to application code.
- *
  * @property response The SAML response containing the assertion
  * @property assertion The SAML assertion (maybe decrypted)
  */
@@ -139,14 +137,15 @@ public class SamlPrincipal(
     public fun hasAttribute(name: String): Boolean = attributes.containsKey(name)
 }
 
-private fun Assertion.buildAttributesMap() = buildMap {
+private fun Assertion.buildAttributesMap(): Map<String, List<String>> = buildMap {
     attributeStatements.forEach { attributeStatement ->
         attributeStatement.attributes.forEach { attribute ->
+            val name = attribute.name ?: return@forEach
             val values = attribute.attributeValues.mapNotNull { attributeValue ->
                 attributeValue.dom?.textContent
             }
             if (values.isNotEmpty()) {
-                put(attribute.name!!, values)
+                put(name, this[name].orEmpty() + values)
             }
         }
     }

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/src/io/ktor/server/auth/saml/SamlReplayCache.kt

@@ -53,6 +53,10 @@ public interface SamlReplayCache : AutoCloseable {
     /**
      * Atomically checks if an assertion ID has been seen and records it if not.
      * This method combines [isReplayed] and [recordAssertion] into a single atomic operation.
+     *
+     * `@param` assertionId The unique assertion ID to check and record
+     * `@param` expirationTime The expiration time of the assertion (used for cache eviction)
+     * `@return` true if the assertion was not seen before and was recorded; false if replay detected
      */
     public suspend fun tryRecordAssertion(assertionId: String, expirationTime: Instant): Boolean
 }
@@ -93,6 +97,7 @@ public interface SamlReplayCache : AutoCloseable {
  *
  * @property maxSize Maximum number of assertion IDs to cache (default: 10,000).
  *                   When this limit is reached, the oldest entries are evicted.
+ * @param parentScope Optional parent scope for cleanup coroutine lifecycle management
  */
 @OptIn(ExperimentalTime::class)
 public class InMemorySamlReplayCache(

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/src/io/ktor/server/auth/saml/SamlSecurity.kt

@@ -62,14 +62,20 @@ public object SamlCrypto {
         keyPassword: String,
         keystoreType: String = "JKS"
     ): BasicX509Credential {
-        val keyStore = loadKeyStore(keystorePath, keystorePassword, keystoreType)
-        val key = keyStore.getKey(keyAlias, keyPassword.toCharArray()) as? PrivateKey
-            ?: throw KeyStoreException("Key with alias '$keyAlias' not found or is not a PrivateKey")
-        val certificateChain = keyStore.getCertificateChain(keyAlias)
-            ?: throw KeyStoreException("Certificate chain for alias '$keyAlias' not found")
-        val certificate = certificateChain.first() as? X509Certificate
-            ?: throw KeyStoreException("First certificate in chain is not an X509Certificate")
-        return BasicX509Credential(certificate).also { it.setPrivateKey(key) }
+        try {
+            val keyStore = loadKeyStore(keystorePath, keystorePassword, keystoreType)
+            val key = keyStore.getKey(keyAlias, keyPassword.toCharArray()) as? PrivateKey
+                ?: throw KeyStoreException("Key with alias '$keyAlias' not found or is not a PrivateKey")
+            val certificateChain = keyStore.getCertificateChain(keyAlias)
+                ?: throw KeyStoreException("Certificate chain for alias '$keyAlias' not found")
+            val certificate = certificateChain.firstOrNull() as? X509Certificate
+                ?: throw KeyStoreException("First certificate in chain is not an X509Certificate")
+            return BasicX509Credential(certificate).also { it.setPrivateKey(key) }
+        } catch (e: KeyStoreException) {
+            throw e
+        } catch (e: Throwable) {
+            throw KeyStoreException("Failed to load credential", e)
+        }
     }
 }
 

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/test/io/ktor/server/auth/saml/InMemorySamlReplayCacheTest.kt

@@ -4,6 +4,7 @@
 
 package io.ktor.server.auth.saml
 
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.joinAll
 import kotlinx.coroutines.launch
@@ -60,7 +61,7 @@ class InMemorySamlReplayCacheTest {
             val assertionsPerCoroutine = 100
 
             val jobs = (0 until coroutineCount).map { coroutineIndex ->
-                launch {
+                launch(Dispatchers.Default) {
                     repeat(assertionsPerCoroutine) { assertionIndex ->
                         val assertionId = "coroutine-$coroutineIndex-assertion-$assertionIndex"
                         cache.recordAssertion(assertionId, expirationTime)

ktor-server/ktor-server-plugins/ktor-server-auth-saml/jvm/test/io/ktor/server/auth/saml/SamlConfigTest.kt

@@ -4,6 +4,9 @@
 
 package io.ktor.server.auth.saml
 
+import io.ktor.network.tls.certificates.*
+import java.security.cert.X509Certificate
+import kotlin.io.encoding.Base64
 import kotlin.test.*
 import kotlin.time.Duration.Companion.seconds
 
@@ -50,11 +53,29 @@ class SamlConfigTest {
     }
 
     companion object {
+        private val TEST_KEY_STORE = buildKeyStore {
+            certificate("test") {
+                password = "test"
+            }
+        }
+
+        private val TEST_CERTIFICATE = TEST_KEY_STORE.getCertificate("test") as X509Certificate
+
+        private val TEST_CERTIFICATE_BASE64 = Base64.encode(TEST_CERTIFICATE.encoded)
+
         private val MINIMAL_IDP_METADATA = """
         <?xml version="1.0" encoding="UTF-8"?>
         <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
+                          xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                           entityID="https://idp.example.com">
             <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+                <KeyDescriptor use="signing">
+                    <ds:KeyInfo>
+                        <ds:X509Data>
+                            <ds:X509Certificate>$TEST_CERTIFICATE_BASE64</ds:X509Certificate>
+                        </ds:X509Data>
+                    </ds:KeyInfo>
+                </KeyDescriptor>
                 <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                                      Location="https://idp.example.com/sso"/>
             </IDPSSODescriptor>