Add @nullable Annotations to saml2-service-provider

Issue gh-17823

Signed-off-by: Josh Cummings <3627351+jzheaux@users.noreply.github.com>

Author: jzheaux

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/core/Saml2Error.java

@@ -18,6 +18,8 @@
 
 import java.io.Serializable;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.util.Assert;
 
 /**
@@ -37,14 +39,14 @@ public class Saml2Error implements Serializable {
 
 	private final String errorCode;
 
-	private final String description;
+	private final @Nullable String description;
 
 	/**
 	 * Constructs a {@code Saml2Error} using the provided parameters.
 	 * @param errorCode the error code
 	 * @param description the error description
 	 */
-	public Saml2Error(String errorCode, String description) {
+	public Saml2Error(String errorCode, @Nullable String description) {
 		Assert.hasText(errorCode, "errorCode cannot be empty");
 		this.errorCode = errorCode;
 		this.description = description;
@@ -56,7 +58,7 @@ public Saml2Error(String errorCode, String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error invalidResponse(String description) {
+	public static Saml2Error invalidResponse(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.INVALID_RESPONSE, description);
 	}
 
@@ -66,7 +68,7 @@ public static Saml2Error invalidResponse(String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error internalValidationError(String description) {
+	public static Saml2Error internalValidationError(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.INTERNAL_VALIDATION_ERROR, description);
 	}
 
@@ -76,7 +78,7 @@ public static Saml2Error internalValidationError(String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error malformedResponseData(String description) {
+	public static Saml2Error malformedResponseData(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.MALFORMED_RESPONSE_DATA, description);
 	}
 
@@ -86,7 +88,7 @@ public static Saml2Error malformedResponseData(String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error decryptionError(String description) {
+	public static Saml2Error decryptionError(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.DECRYPTION_ERROR, description);
 	}
 
@@ -96,7 +98,7 @@ public static Saml2Error decryptionError(String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error relyingPartyRegistrationNotFound(String description) {
+	public static Saml2Error relyingPartyRegistrationNotFound(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.RELYING_PARTY_REGISTRATION_NOT_FOUND, description);
 	}
 
@@ -106,7 +108,7 @@ public static Saml2Error relyingPartyRegistrationNotFound(String description) {
 	 * @return the resulting {@link Saml2Error}
 	 * @since 7.0
 	 */
-	public static Saml2Error subjectNotFound(String description) {
+	public static Saml2Error subjectNotFound(@Nullable String description) {
 		return new Saml2Error(Saml2ErrorCodes.SUBJECT_NOT_FOUND, description);
 	}
 
@@ -122,7 +124,7 @@ public final String getErrorCode() {
 	 * Returns the error description.
 	 * @return the error description
 	 */
-	public final String getDescription() {
+	public final @Nullable String getDescription() {
 		return this.description;
 	}
 

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/core/Saml2X509Credential.java

@@ -24,6 +24,8 @@
 import java.util.Objects;
 import java.util.Set;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.util.Assert;
 
 /**
@@ -40,7 +42,7 @@ public final class Saml2X509Credential implements Serializable {
 
 	private static final long serialVersionUID = -1015853414272603517L;
 
-	private final PrivateKey privateKey;
+	private final @Nullable PrivateKey privateKey;
 
 	private final X509Certificate certificate;
 
@@ -77,7 +79,8 @@ public Saml2X509Credential(PrivateKey privateKey, X509Certificate certificate, S
 	 * @param certificate the credential's public certificate
 	 * @param types the credential's intended usages
 	 */
-	public Saml2X509Credential(PrivateKey privateKey, X509Certificate certificate, Set<Saml2X509CredentialType> types) {
+	public Saml2X509Credential(@Nullable PrivateKey privateKey, X509Certificate certificate,
+			Set<Saml2X509CredentialType> types) {
 		Assert.notNull(certificate, "certificate cannot be null");
 		Assert.notNull(types, "credentialTypes cannot be null");
 		this.privateKey = privateKey;
@@ -123,7 +126,7 @@ public static Saml2X509Credential signing(PrivateKey privateKey, X509Certificate
 		return new Saml2X509Credential(privateKey, certificate, Saml2X509Credential.Saml2X509CredentialType.SIGNING);
 	}
 
-	private Saml2X509Credential(PrivateKey privateKey, boolean keyRequired, X509Certificate certificate,
+	private Saml2X509Credential(@Nullable PrivateKey privateKey, boolean keyRequired, X509Certificate certificate,
 			Saml2X509CredentialType... types) {
 		Assert.notNull(certificate, "certificate cannot be null");
 		Assert.notEmpty(types, "credentials types cannot be empty");
@@ -140,7 +143,7 @@ private Saml2X509Credential(PrivateKey privateKey, boolean keyRequired, X509Cert
 	 * @return the private key, may be null
 	 * @see #Saml2X509Credential(PrivateKey, X509Certificate, Saml2X509CredentialType...)
 	 */
-	public PrivateKey getPrivateKey() {
+	public @Nullable PrivateKey getPrivateKey() {
 		return this.privateKey;
 	}
 

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/core/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Core SAML2 types and utilities.
+ */
+@NullMarked
+package org.springframework.security.saml2.core;
+
+import org.jspecify.annotations.NullMarked;

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/internal/OpenSamlOperations.java

@@ -25,6 +25,7 @@
 
 import javax.xml.namespace.QName;
 
+import org.jspecify.annotations.Nullable;
 import org.opensaml.core.xml.XMLObject;
 import org.opensaml.saml.saml2.core.Issuer;
 import org.opensaml.saml.saml2.core.RequestAbstractType;
@@ -35,6 +36,7 @@
 import org.springframework.security.saml2.core.Saml2Error;
 import org.springframework.security.saml2.core.Saml2ParameterNames;
 import org.springframework.security.saml2.core.Saml2X509Credential;
+import org.springframework.util.Assert;
 import org.springframework.web.util.UriComponentsBuilder;
 
 interface OpenSamlOperations {
@@ -89,14 +91,17 @@ final class RedirectParameters {
 
 			private final String algorithm;
 
-			private final byte[] signature;
+			private final byte @Nullable [] signature;
 
 			private final byte[] content;
 
 			RedirectParameters(Map<String, String> parameters, String parametersQuery, RequestAbstractType request) {
+				Assert.notNull(request.getID(), "SAML request's ID cannot be null");
+				Assert.notNull(request.getIssuer(), "SAML request's Issuer cannot be null");
 				this.id = request.getID();
 				this.issuer = request.getIssuer();
-				this.algorithm = parameters.get(Saml2ParameterNames.SIG_ALG);
+				this.algorithm = Objects.requireNonNull(parameters.get(Saml2ParameterNames.SIG_ALG),
+						"sigAlg parameter cannot be null");
 				if (parameters.get(Saml2ParameterNames.SIGNATURE) != null) {
 					this.signature = Saml2Utils.samlDecode(parameters.get(Saml2ParameterNames.SIGNATURE));
 				}
@@ -113,9 +118,12 @@ final class RedirectParameters {
 			}
 
 			RedirectParameters(Map<String, String> parameters, String parametersQuery, StatusResponseType response) {
+				Assert.notNull(response.getID(), "SAML response's ID cannot be null");
+				Assert.notNull(response.getIssuer(), "SAML response's Issuer cannot be null");
 				this.id = response.getID();
 				this.issuer = response.getIssuer();
-				this.algorithm = parameters.get(Saml2ParameterNames.SIG_ALG);
+				this.algorithm = Objects.requireNonNull(parameters.get(Saml2ParameterNames.SIG_ALG),
+						"sigAlg parameter cannot be null");
 				if (parameters.get(Saml2ParameterNames.SIGNATURE) != null) {
 					this.signature = Saml2Utils.samlDecode(parameters.get(Saml2ParameterNames.SIGNATURE));
 				}
@@ -131,7 +139,8 @@ final class RedirectParameters {
 				this.content = getContent(Saml2ParameterNames.SAML_RESPONSE, relayState, queryParams);
 			}
 
-			static byte[] getContent(String samlObject, String relayState, final Map<String, String> queryParams) {
+			static byte[] getContent(String samlObject, @Nullable String relayState,
+					final Map<String, String> queryParams) {
 				if (Objects.nonNull(relayState)) {
 					return String
 						.format("%s=%s&%s=%s&%s=%s", samlObject, queryParams.get(samlObject),
@@ -163,7 +172,7 @@ String getAlgorithm() {
 				return this.algorithm;
 			}
 
-			byte[] getSignature() {
+			byte @Nullable [] getSignature() {
 				return this.signature;
 			}
 

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/internal/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Internal utilities for SAML2 support (not for public use).
+ */
+@NullMarked
+package org.springframework.security.saml2.internal;
+
+import org.jspecify.annotations.NullMarked;

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/jackson/DefaultSaml2AuthenticatedPrincipalMixin.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.annotation.JsonAutoDetect;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import org.jspecify.annotations.NullUnmarked;
 
 import org.springframework.security.jackson.SecurityJacksonModules;
 import org.springframework.security.saml2.provider.service.authentication.DefaultSaml2AuthenticatedPrincipal;
@@ -38,6 +39,7 @@
  */
 @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
 @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY, getterVisibility = JsonAutoDetect.Visibility.NONE)
+@NullUnmarked
 class DefaultSaml2AuthenticatedPrincipalMixin {
 
 	@JsonProperty("registrationId")

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/jackson/Saml2AssertionAuthenticationMixin.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import org.jspecify.annotations.NullUnmarked;
 
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.jackson.SecurityJacksonModules;
@@ -41,6 +42,7 @@
 @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
 @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY, getterVisibility = JsonAutoDetect.Visibility.NONE,
 		isGetterVisibility = JsonAutoDetect.Visibility.NONE)
+@NullUnmarked
 class Saml2AssertionAuthenticationMixin {
 
 	@JsonCreator

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/jackson/Saml2AuthenticationExceptionMixin.java

@@ -21,6 +21,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import org.jspecify.annotations.NullUnmarked;
 
 import org.springframework.security.saml2.core.Saml2Error;
 import org.springframework.security.saml2.provider.service.authentication.Saml2AuthenticationException;
@@ -38,6 +39,7 @@
 @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.NONE, getterVisibility = JsonAutoDetect.Visibility.NONE,
 		isGetterVisibility = JsonAutoDetect.Visibility.NONE)
 @JsonIgnoreProperties({ "cause", "stackTrace", "suppressedExceptions" })
+@NullUnmarked
 abstract class Saml2AuthenticationExceptionMixin {
 
 	@JsonProperty("error")

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/jackson/Saml2AuthenticationMixin.java

@@ -23,6 +23,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import org.jspecify.annotations.NullUnmarked;
 
 import org.springframework.security.core.AuthenticatedPrincipal;
 import org.springframework.security.core.GrantedAuthority;
@@ -41,6 +42,7 @@
 @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY, getterVisibility = JsonAutoDetect.Visibility.NONE,
 		isGetterVisibility = JsonAutoDetect.Visibility.NONE)
 @JsonIgnoreProperties({ "authenticated" })
+@NullUnmarked
 class Saml2AuthenticationMixin {
 
 	@JsonCreator

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/jackson/Saml2ErrorMixin.java

@@ -20,6 +20,7 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import org.jspecify.annotations.NullUnmarked;
 
 import org.springframework.security.saml2.core.Saml2Error;
 
@@ -35,6 +36,7 @@
 @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
 @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY, getterVisibility = JsonAutoDetect.Visibility.NONE,
 		isGetterVisibility = JsonAutoDetect.Visibility.NONE)
+@NullUnmarked
 class Saml2ErrorMixin {
 
 	@JsonCreator