add IdPMetadata public factory

Author: zibet27

ktor-server/ktor-server-plugins/ktor-server-auth-saml/api/ktor-server-auth-saml.api

@@ -21,8 +21,21 @@ public final class io/ktor/server/auth/saml/DigestAlgorithm$Companion {
 
 public final class io/ktor/server/auth/saml/IdPMetadata {
 	public final fun getEntityId ()Ljava/lang/String;
+	public final fun getSigningCredentials ()Ljava/util/List;
 	public final fun getSloUrl ()Ljava/lang/String;
+	public final fun getSloUrlPost ()Ljava/lang/String;
+	public final fun getSloUrlRedirect ()Ljava/lang/String;
 	public final fun getSsoUrl ()Ljava/lang/String;
+	public final fun getSsoUrlPost ()Ljava/lang/String;
+	public final fun getSsoUrlRedirect ()Ljava/lang/String;
+	public final fun setEntityId (Ljava/lang/String;)V
+	public final fun setSigningCredentials (Ljava/util/List;)V
+	public final fun setSloUrl (Ljava/lang/String;)V
+	public final fun setSloUrlPost (Ljava/lang/String;)V
+	public final fun setSloUrlRedirect (Ljava/lang/String;)V
+	public final fun setSsoUrl (Ljava/lang/String;)V
+	public final fun setSsoUrlPost (Ljava/lang/String;)V
+	public final fun setSsoUrlRedirect (Ljava/lang/String;)V
 }
 
 public final class io/ktor/server/auth/saml/InMemorySamlReplayCache : io/ktor/server/auth/saml/SamlReplayCache {
@@ -173,6 +186,7 @@ public final class io/ktor/server/auth/saml/SamlCrypto {
 }
 
 public final class io/ktor/server/auth/saml/SamlMetadataKt {
+	public static final fun IdPMetadata (Lkotlin/jvm/functions/Function1;)Lio/ktor/server/auth/saml/IdPMetadata;
 	public static final fun SamlSpMetadata (Lkotlin/jvm/functions/Function1;)Lio/ktor/server/auth/saml/SamlSpMetadata;
 	public static final fun parseSamlIdpMetadata (Ljava/lang/String;Z)Lio/ktor/server/auth/saml/IdPMetadata;
 	public static synthetic fun parseSamlIdpMetadata$default (Ljava/lang/String;ZILjava/lang/Object;)Lio/ktor/server/auth/saml/IdPMetadata;

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

@@ -279,29 +279,74 @@ public class SamlContactPerson {
  *
  * This class extracts and holds the essential information from SAML metadata
  * needed for the SP to interact with the IdP.
- *
- * @property entityId The IdP's entity ID
- * @property ssoUrl The Single Sign-On service URL (default binding - HTTP-Redirect or HTTP-POST)
- * @property sloUrl The Single Logout service URL (default binding - HTTP-Redirect or HTTP-POST), null if not available
  */
-public class IdPMetadata internal constructor(
-    public val entityId: String,
-    public val ssoUrl: String,
-    public val sloUrl: String?,
-    internal val signingCredentials: List<Credential>,
-    private val ssoUrlRedirect: String? = null,
-    private val ssoUrlPost: String? = null,
-    private val sloUrlRedirect: String? = null,
-    private val sloUrlPost: String? = null
-) {
+public class IdPMetadata internal constructor() {
+    /**
+     * The IdP's entity ID - a unique identifier for the Identity Provider.
+     * Required.
+     */
+    public var entityId: String? = null
+
+    /**
+     * The Single Sign-On service URL (default binding).
+     * This is the endpoint where SAML authentication requests should be sent.
+     * Required.
+     */
+    public var ssoUrl: String? = null
+
+    /**
+     * The Single Logout service URL (default binding).
+     * This is the endpoint where SAML logout requests and responses should be sent.
+     * Optional.
+     */
+    public var sloUrl: String? = null
+
+    /**
+     * List of signing credentials (certificates) used to verify signatures from the IdP.
+     * At least one credential is required for signature verification.
+     */
+    public var signingCredentials: List<Credential> = emptyList()
+
+    /**
+     * SSO URL for HTTP-Redirect binding.
+     * Falls back to [ssoUrl] if not specified.
+     */
+    public var ssoUrlRedirect: String? = null
+
+    /**
+     * SSO URL for HTTP-POST binding.
+     * Falls back to [ssoUrl] if not specified.
+     */
+    public var ssoUrlPost: String? = null
+
+    /**
+     * SLO URL for HTTP-Redirect binding.
+     * Falls back to [sloUrl] if not specified.
+     */
+    public var sloUrlRedirect: String? = null
+
+    /**
+     * SLO URL for HTTP-POST binding.
+     * Falls back to [sloUrl] if not specified.
+     */
+    public var sloUrlPost: String? = null
+
+    internal fun validate() {
+        requireNotNull(entityId) { "Entity ID cannot be null" }
+        requireNotNull(ssoUrl) { "SSO URL cannot be null" }
+        require(signingCredentials.isNotEmpty()) {
+            "No signing certificates found in IdP metadata. Signature verification will fail."
+        }
+    }
+
     /**
      * Returns the SSO URL for the specified binding.
      * Falls back to the default ssoUrl if binding-specific URL is not available.
      */
     internal fun getSsoUrlFor(binding: SamlBinding): String {
         return when (binding) {
-            SamlBinding.HttpRedirect -> ssoUrlRedirect ?: ssoUrl
-            SamlBinding.HttpPost -> ssoUrlPost ?: ssoUrl
+            SamlBinding.HttpRedirect -> checkNotNull(ssoUrlRedirect ?: ssoUrl)
+            SamlBinding.HttpPost -> checkNotNull(ssoUrlPost ?: ssoUrl)
         }
     }
 
@@ -317,6 +362,35 @@ public class IdPMetadata internal constructor(
     }
 }
 
+/**
+ * Creates a new SAML Identity Provider metadata configuration.
+ *
+ * This factory function allows creating a standalone [IdPMetadata] instance programmatically.
+ * Typically used for testing or when IdP metadata needs to be constructed from non-XML sources.
+ * For production use, prefer [parseSamlIdpMetadata] to parse actual IdP metadata XML.
+ *
+ * ## Example Usage
+ *
+ * ```kotlin
+ * val idp = IdPMetadata {
+ *     entityId = "https://idp.example.com"
+ *     ssoUrl = "https://idp.example.com/sso"
+ *     sloUrl = "https://idp.example.com/slo"
+ *     signingCredentials = listOf(credential)
+ * }
+ * ```
+ *
+ * @param configure Configuration block for IdP metadata settings
+ * @return A configured [IdPMetadata] instance
+ * @throws IllegalArgumentException if [IdPMetadata.entityId] or [IdPMetadata.ssoUrl] is null
+ * @throws IllegalArgumentException if [IdPMetadata.signingCredentials] is empty
+ *
+ * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.server.auth.saml.IdPMetadata)
+ */
+public fun IdPMetadata(configure: IdPMetadata.() -> Unit): IdPMetadata {
+    return IdPMetadata().apply(configure).also { it.validate() }
+}
+
 private val CERT_EXPIRY_WARNING_THRESHOLD = 30.days
 
 /**
@@ -366,20 +440,17 @@ private fun EntityDescriptor.extractIdPMetadata(validateCertificateExpiration: B
 
     // Extract signing certificates
     val signingCredentials = idpDescriptor.extractSigningCredentials(validateCertificateExpiration)
-    require(signingCredentials.isNotEmpty()) {
-        "No signing certificates found in IdP metadata. Signature verification will fail."
-    }
 
-    return IdPMetadata(
-        entityId = entityId,
-        ssoUrl = ssoUrl,
-        sloUrl = sloUrl,
-        signingCredentials = signingCredentials,
-        ssoUrlRedirect = ssoUrlRedirect,
-        ssoUrlPost = ssoUrlPost,
-        sloUrlRedirect = sloUrlRedirect,
-        sloUrlPost = sloUrlPost
-    )
+    return IdPMetadata {
+        this.entityId = entityId
+        this.ssoUrl = ssoUrl
+        this.sloUrl = sloUrl
+        this.signingCredentials = signingCredentials
+        this.ssoUrlRedirect = ssoUrlRedirect
+        this.ssoUrlPost = ssoUrlPost
+        this.sloUrlRedirect = sloUrlRedirect
+        this.sloUrlPost = sloUrlPost
+    }
 }
 
 private fun IDPSSODescriptor.extractSigningCredentials(
@@ -430,9 +501,7 @@ private fun X509Certificate.validate() {
     if (timeUntilExpiry < CERT_EXPIRY_WARNING_THRESHOLD) {
         val daysUntilExpiry = timeUntilExpiry.inWholeDays
         LOGGER.warn(
-            "IdP signing certificate is expiring soon! Subject: $subjectX500Principal, " +
-                "Expires: $notAfter (in $daysUntilExpiry days). " +
-                "Contact your IdP administrator to renew the certificate."
+            "IdP signing certificate is expiring soon! Subject: $subjectX500Principal, Expires: $notAfter (in $daysUntilExpiry days). Contact your IdP administrator to renew the certificate."
         )
     }
 }