001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package com.revetsec.soklet; 017 018import com.google.errorprone.annotations.CheckReturnValue; 019import com.revetsec.saml.SamlPostBindingMessage; 020import com.revetsec.saml.SamlPostBindingParseResult; 021import com.revetsec.saml.SamlPostForm; 022import com.revetsec.saml.SamlAuthenticationRequestResult; 023import com.revetsec.saml.SamlLogoutRedirectResult; 024import com.revetsec.saml.SamlLogoutResponseRedirectResult; 025import com.revetsec.saml.SamlLogoutPostResult; 026import com.revetsec.saml.SamlLogoutResponsePostResult; 027import com.revetsec.saml.SamlRedirectBindingMessage; 028import com.revetsec.saml.SamlRedirectBindingParseResult; 029import com.soklet.HttpMethod; 030import com.soklet.MarshaledResponse; 031import com.soklet.Request; 032import com.soklet.Response; 033import com.soklet.ResponseCookie; 034import org.jspecify.annotations.NonNull; 035import org.jspecify.annotations.Nullable; 036import javax.annotation.concurrent.ThreadSafe; 037import java.net.URI; 038import java.nio.charset.StandardCharsets; 039import java.util.HashMap; 040import java.util.List; 041import java.util.Map; 042import java.util.Set; 043 044import static java.util.Objects.requireNonNull; 045 046/** 047 * Thin SAML transport helpers for application-routed Soklet endpoints. Core performs all SAML 048 * parsing, signature, pending, audience and replay decisions. The application owns cookies, 049 * IdP selection, local sessions and response policy. 050 * 051 * @since 1.0.0 052 */ 053@ThreadSafe 054public final class SokletSaml { 055 private SokletSaml() { } 056 057 /** 058 * Parses a raw ACS POST body and every materialized Content-Type value, preserving duplicates. 059 * 060 * @param request application-routed ACS request 061 * @return an oversized transport outcome or core's untrusted POST-binding parse result 062 * @throws IllegalArgumentException if the application route is not POST 063 * @since 1.0.0 064 */ 065 @CheckReturnValue 066 public static @NonNull SokletRequestResult<@NonNull SamlPostBindingParseResult> postBindingResultFor(@NonNull Request request) { 067 requireNonNull(request); 068 if (request.getHttpMethod() != HttpMethod.POST) 069 throw new IllegalArgumentException("SAML ACS route requires POST"); 070 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 071 return SokletRequestResult.fromResult(SamlPostBindingMessage.fromFormBodyResult( 072 SokletOAuth.bodyBytesFor(request), 073 SokletOAuth.collectHeaderValues(request, "Content-Type"), 074 request.getRawQuery().orElse(null))); 075 } 076 077 /** 078 * Parses an original logout POST body and every Content-Type value, preserving duplicates. 079 * The application supplies its browser-bound pending state to core when completing SP logout; 080 * a pending cookie for a cross-site POST requires Secure, HttpOnly and SameSite=None. 081 * 082 * @param request application-routed logout POST request 083 * @return an oversized transport outcome or core's untrusted logout POST-binding parse result 084 * @throws IllegalArgumentException if the application route is not POST 085 * @since 1.0.0 086 */ 087 @CheckReturnValue 088 public static @NonNull SokletRequestResult<@NonNull SamlPostBindingParseResult> postLogoutBindingResultFor(@NonNull Request request) { 089 requireNonNull(request); 090 if (request.getHttpMethod() != HttpMethod.POST) 091 throw new IllegalArgumentException("SAML logout route requires POST"); 092 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 093 return SokletRequestResult.fromResult(SamlPostBindingMessage.fromLogoutFormBodyResult( 094 SokletOAuth.bodyBytesFor(request), 095 SokletOAuth.collectHeaderValues(request, "Content-Type"), 096 request.getRawQuery().orElse(null))); 097 } 098 099 /** 100 * Parses the untouched query string for HTTP-Redirect logout signature verification. 101 * 102 * @param request application-routed logout GET request 103 * @return an oversized transport outcome or core's untrusted Redirect-binding parse result 104 * @since 1.0.0 105 */ 106 @CheckReturnValue 107 public static @NonNull SamlRedirectBindingParseResult redirectBindingResultFor(@NonNull Request request) { 108 requireNonNull(request); 109 if (request.getHttpMethod() != HttpMethod.GET) 110 return SamlRedirectBindingParseResult.Rejected.INSTANCE; 111 return SamlRedirectBindingMessage.fromRawQueryResult(request.getRawQuery().orElse("")); 112 } 113 114 /** 115 * Sends a core-prepared authentication Redirect with no-store and no-referrer headers. 116 * 117 * @param prepared core-prepared authentication request 118 * @param cookies application-selected response cookies 119 * @return Soklet redirect response 120 * @since 1.0.0 121 */ 122 @CheckReturnValue 123 public static @NonNull Response authenticationRedirect( 124 SamlAuthenticationRequestResult.@NonNull Prepared prepared, 125 @NonNull Set<@NonNull ResponseCookie> cookies) { 126 return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies); 127 } 128 129 /** 130 * Sends a core-prepared SP logout Redirect. 131 * 132 * @param prepared core-prepared logout request 133 * @param cookies application-selected response cookies 134 * @return Soklet redirect response 135 * @since 1.0.0 136 */ 137 @CheckReturnValue 138 public static @NonNull Response logoutRedirect(SamlLogoutRedirectResult.@NonNull Prepared prepared, 139 @NonNull Set<@NonNull ResponseCookie> cookies) { 140 return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies); 141 } 142 143 /** 144 * Sends a core-prepared answer to an IdP logout request. 145 * 146 * @param prepared core-prepared logout response 147 * @param cookies application-selected response cookies 148 * @return Soklet redirect response 149 * @since 1.0.0 150 */ 151 @CheckReturnValue 152 public static @NonNull Response logoutResponseRedirect( 153 SamlLogoutResponseRedirectResult.@NonNull Prepared prepared, 154 @NonNull Set<@NonNull ResponseCookie> cookies) { 155 return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies); 156 } 157 158 /** 159 * Sends a core-prepared SP logout POST form. Set the browser-bound pending cookie and CSP 160 * before delivery; a cross-site POST pending cookie requires Secure, HttpOnly and SameSite=None. 161 * 162 * @param prepared core-prepared logout request 163 * @param cspNonce application-generated nonce, or null for manual submission 164 * @return exact UTF-8 HTML response 165 * @since 1.0.0 166 */ 167 @CheckReturnValue 168 public static @NonNull MarshaledResponse logoutPostFormResponse( 169 SamlLogoutPostResult.@NonNull Prepared prepared, @Nullable String cspNonce) { 170 return postFormResponse(requireNonNull(prepared).getPostForm(), cspNonce); 171 } 172 173 /** 174 * Sends a core-prepared POST answer to an IdP logout request. The application sets its CSP. 175 * 176 * @param prepared core-prepared logout response 177 * @param cspNonce application-generated nonce, or null for manual submission 178 * @return exact UTF-8 HTML response 179 * @since 1.0.0 180 */ 181 @CheckReturnValue 182 public static @NonNull MarshaledResponse logoutResponsePostFormResponse( 183 SamlLogoutResponsePostResult.@NonNull Prepared prepared, @Nullable String cspNonce) { 184 return postFormResponse(requireNonNull(prepared).getPostForm(), cspNonce); 185 } 186 187 private static @NonNull Response preparedRedirect(@NonNull URI destination, 188 @NonNull Set<@NonNull ResponseCookie> cookies) { 189 if (!"https".equalsIgnoreCase(requireNonNull(destination).getScheme())) 190 throw new IllegalArgumentException("SAML Redirect requires HTTPS"); 191 return SokletOAuth.redirect(destination, requireNonNull(cookies)); 192 } 193 194 /** 195 * Sends a core-prepared POST form with no-store headers. The application sets a CSP header 196 * appropriate to its page and chooses the pending cookie before calling this helper. 197 * 198 * @param form core-prepared SAML authentication or logout form 199 * @param cspNonce application-generated nonce, or null for manual submission 200 * @return exact UTF-8 HTML response 201 * @since 1.0.0 202 */ 203 @CheckReturnValue 204 public static @NonNull MarshaledResponse postFormResponse(@NonNull SamlPostForm form, 205 @Nullable String cspNonce) { 206 requireNonNull(form); 207 Map<String, List<String>> headers = new HashMap<>(); 208 form.getHeaders().forEach((name, value) -> headers.put(name, List.of(value))); 209 return MarshaledResponse.withStatusCode(200).headers(Map.copyOf(headers)) 210 .body(form.toHtml(cspNonce).getBytes(StandardCharsets.UTF_8)).build(); 211 } 212}