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 */ 016 017package com.revetsec.oauth; 018 019import com.revetsec.internal.Limits; 020import com.revetsec.internal.encoding.EncodingException; 021import com.revetsec.internal.encoding.StrictUtf8; 022import com.revetsec.internal.json.JsonCodec; 023import com.revetsec.internal.json.JsonLimits; 024import com.revetsec.internal.json.JsonParseException; 025import com.revetsec.json.JsonArray; 026import com.revetsec.json.JsonBoolean; 027import com.revetsec.json.JsonObject; 028import com.revetsec.json.JsonString; 029import com.revetsec.json.JsonValue; 030import org.jspecify.annotations.NonNull; 031import org.jspecify.annotations.Nullable; 032 033import com.google.errorprone.annotations.CheckReturnValue; 034import javax.annotation.concurrent.Immutable; 035import javax.annotation.concurrent.NotThreadSafe; 036import java.net.URI; 037import java.util.LinkedHashSet; 038import java.util.Map; 039import java.util.Optional; 040import java.util.Set; 041 042import static java.util.Objects.requireNonNull; 043 044/** 045 * Known authorization-server metadata. A remote document's issuer must match the configured issuer exactly. A 046 * manual instance is application configuration, not proof from a remote server. The {@link OAuthClient} builder 047 * checks every known requestable endpoint against its outbound URI policy before use. 048 * 049 * @author <a href="https://www.revetkn.com">Mark Allen</a> 050 * @since 1.0.0 051 */ 052@Immutable 053public final class AuthorizationServerMetadata { 054 private final @NonNull String issuer; 055 private final @NonNull URI authorizationEndpoint; 056 private final @NonNull URI tokenEndpoint; 057 private final @Nullable URI jwksUri; 058 private final @Nullable URI introspectionEndpoint; 059 private final @Nullable URI revocationEndpoint; 060 private final @Nullable Set<@NonNull String> codeChallengeMethodsSupported; 061 private final @Nullable Set<@NonNull String> tokenEndpointAuthMethodsSupported; 062 private final @Nullable Set<@NonNull String> introspectionEndpointAuthMethodsSupported; 063 private final @Nullable Set<@NonNull String> tokenEndpointAuthSigningAlgValuesSupported; 064 private final @Nullable Set<@NonNull String> revocationEndpointAuthMethodsSupported; 065 private final @Nullable Set<@NonNull String> revocationEndpointAuthSigningAlgValuesSupported; 066 private final @Nullable Set<@NonNull String> introspectionEndpointAuthSigningAlgValuesSupported; 067 private final boolean authorizationResponseIssuerSupported; 068 private final boolean remotelyDiscovered; 069 070 private AuthorizationServerMetadata(@NonNull Builder builder, boolean remotelyDiscovered) { 071 this.issuer = builder.issuer; 072 this.authorizationEndpoint = requireNonNull(builder.authorizationEndpoint); 073 this.tokenEndpoint = requireNonNull(builder.tokenEndpoint); 074 this.jwksUri = builder.jwksUri; 075 this.introspectionEndpoint = builder.introspectionEndpoint; 076 this.revocationEndpoint = builder.revocationEndpoint; 077 this.codeChallengeMethodsSupported = builder.codeChallengeMethodsSupported; 078 this.tokenEndpointAuthMethodsSupported = builder.tokenEndpointAuthMethodsSupported; 079 this.introspectionEndpointAuthMethodsSupported = builder.introspectionEndpointAuthMethodsSupported; 080 this.tokenEndpointAuthSigningAlgValuesSupported = builder.tokenEndpointAuthSigningAlgValuesSupported; 081 this.revocationEndpointAuthMethodsSupported = builder.revocationEndpointAuthMethodsSupported; 082 this.revocationEndpointAuthSigningAlgValuesSupported = builder.revocationEndpointAuthSigningAlgValuesSupported; 083 this.introspectionEndpointAuthSigningAlgValuesSupported = builder.introspectionEndpointAuthSigningAlgValuesSupported; 084 this.authorizationResponseIssuerSupported = builder.authorizationResponseIssuerSupported; 085 this.remotelyDiscovered = remotelyDiscovered; 086 } 087 088 /** 089 * Starts a manual metadata builder for an AS without discovery. 090 * 091 * @param issuer the deployment's exact issuer identifier 092 * @return the builder 093 * @since 1.0.0 094 */ 095 public static @NonNull Builder withIssuer(@NonNull String issuer) { 096 return new Builder(issuer); 097 } 098 099 /** 100 * Parses bounded metadata and reports a fixed document or issuer rejection as a value. 101 * @param expectedIssuer configured trust issuer 102 * @param json metadata JSON text 103 * @return the metadata parsing outcome 104 * @throws NullPointerException if an argument is null 105 * @since 1.0.0 106 */ 107 @com.google.errorprone.annotations.CheckReturnValue 108 public static @NonNull AuthorizationServerMetadataParseResult fromJsonResult(@NonNull String expectedIssuer, 109 @NonNull String json) { 110 requireNonNull(expectedIssuer); requireNonNull(json); 111 withIssuer(expectedIssuer); 112 try { return AuthorizationServerMetadataParseResult.succeeded(parse(expectedIssuer, json)); } 113 catch (OAuthException rejected) { 114 if (rejected.getReason() != OAuthException.Reason.DOCUMENT_MALFORMED 115 && rejected.getReason() != OAuthException.Reason.ISSUER_MISMATCH) throw rejected; 116 return AuthorizationServerMetadataParseResult.rejected(rejected.getReason()); 117 } 118 } 119 120 /** 121 * Parses a strict, bounded metadata JSON document and compares its issuer exactly. 122 * 123 * @param expectedIssuer the configured issuer 124 * @param json the JSON text 125 * @return the metadata 126 * @since 1.0.0 127 */ 128 private static @NonNull AuthorizationServerMetadata parse(@NonNull String expectedIssuer, 129 @NonNull String json) { 130 requireNonNull(expectedIssuer); 131 requireNonNull(json); 132 try { 133 byte[] bytes = StrictUtf8.encode(json); 134 JsonValue parsed = JsonCodec.parse(bytes, 135 JsonLimits.protocolDocument(Limits.HTTP_RESPONSE_BODY_SIZE.getDefaultIntValue())); 136 if (!(parsed instanceof JsonObject object)) 137 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 138 Map<String, JsonValue> members = object.getMembers(); 139 String actualIssuer = requiredString(members, "issuer"); 140 if (!expectedIssuer.equals(actualIssuer)) 141 throw OAuthValidationException.fromReason(OAuthException.Reason.ISSUER_MISMATCH); 142 Builder builder = withIssuer(expectedIssuer) 143 .authorizationEndpoint(URI.create(requiredString(members, "authorization_endpoint"))) 144 .tokenEndpoint(URI.create(requiredString(members, "token_endpoint"))); 145 if (members.containsKey("jwks_uri")) builder = builder.jwksUri(URI.create(requiredString(members, "jwks_uri"))); 146 if (members.containsKey("introspection_endpoint")) builder = builder.introspectionEndpoint(URI.create(requiredString(members, "introspection_endpoint"))); 147 if (members.containsKey("revocation_endpoint")) 148 builder = builder.revocationEndpoint(URI.create(requiredString(members, "revocation_endpoint"))); 149 if (members.containsKey("code_challenge_methods_supported")) 150 builder = builder.codeChallengeMethodsSupported(stringSet(members.get("code_challenge_methods_supported"))); 151 if (members.containsKey("token_endpoint_auth_methods_supported")) 152 builder = builder.tokenEndpointAuthMethodsSupported(stringSet(members.get("token_endpoint_auth_methods_supported"))); 153 if (members.containsKey("introspection_endpoint_auth_methods_supported")) builder = builder.introspectionEndpointAuthMethodsSupported(stringSet(members.get("introspection_endpoint_auth_methods_supported"))); 154 if (members.containsKey("token_endpoint_auth_signing_alg_values_supported")) builder = builder.tokenEndpointAuthSigningAlgValuesSupported(stringSet(members.get("token_endpoint_auth_signing_alg_values_supported"))); 155 if (members.containsKey("revocation_endpoint_auth_methods_supported")) builder = builder.revocationEndpointAuthMethodsSupported(stringSet(members.get("revocation_endpoint_auth_methods_supported"))); 156 if (members.containsKey("revocation_endpoint_auth_signing_alg_values_supported")) builder = builder.revocationEndpointAuthSigningAlgValuesSupported(stringSet(members.get("revocation_endpoint_auth_signing_alg_values_supported"))); 157 if (members.containsKey("introspection_endpoint_auth_signing_alg_values_supported")) builder = builder.introspectionEndpointAuthSigningAlgValuesSupported(stringSet(members.get("introspection_endpoint_auth_signing_alg_values_supported"))); 158 if (members.containsKey("authorization_response_iss_parameter_supported")) { 159 JsonValue value = members.get("authorization_response_iss_parameter_supported"); 160 if (!(value instanceof JsonBoolean booleanValue)) 161 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 162 builder = builder.authorizationResponseIssuerSupported(booleanValue.getValue()); 163 } 164 return builder.buildDiscovered(); 165 } catch (EncodingException | JsonParseException | IllegalArgumentException exception) { 166 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 167 } 168 } 169 170 private static @NonNull String requiredString(@NonNull Map<@NonNull String, @NonNull JsonValue> members, @NonNull String name) { 171 JsonValue value = members.get(name); 172 if (!(value instanceof JsonString text) || text.getValue().isEmpty()) 173 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 174 return text.getValue(); 175 } 176 177 private static @NonNull Set<@NonNull String> stringSet(@NonNull JsonValue value) { 178 if (!(value instanceof JsonArray array)) 179 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 180 Set<String> strings = new LinkedHashSet<>(); 181 for (JsonValue element : array.getElements()) { 182 if (!(element instanceof JsonString text) || text.getValue().isEmpty() 183 || !strings.add(text.getValue())) 184 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 185 } 186 return Set.copyOf(strings); 187 } 188 189 /** 190 * Returns the exact issuer identifier. 191 * 192 * @return issuer 193 * @since 1.0.0 194 */ 195 public @NonNull String getIssuer() { return this.issuer; } 196 197 /** 198 * Returns the authorization endpoint. 199 * 200 * @return endpoint 201 * @since 1.0.0 202 */ 203 public @NonNull URI getAuthorizationEndpoint() { return this.authorizationEndpoint; } 204 205 /** 206 * Returns the token endpoint. 207 * 208 * @return endpoint 209 * @since 1.0.0 210 */ 211 public @NonNull URI getTokenEndpoint() { return this.tokenEndpoint; } 212 213 /** Returns the optional jwks_uri. 214 * @return endpoint when configured or advertised 215 * @since 1.0.0 216 */ 217 public @NonNull Optional<@NonNull URI> getJwksUri() { return Optional.ofNullable(this.jwksUri); } 218 /** Returns the optional introspection_endpoint. 219 * @return endpoint when configured or advertised 220 * @since 1.0.0 221 */ 222 public @NonNull Optional<@NonNull URI> getIntrospectionEndpoint() { return Optional.ofNullable(this.introspectionEndpoint); } 223 /** 224 * Returns the revocation endpoint, when one was advertised or configured. 225 * 226 * @return endpoint 227 * @since 1.0.0 228 */ 229 public @NonNull Optional<@NonNull URI> getRevocationEndpoint() { 230 return Optional.ofNullable(this.revocationEndpoint); 231 } 232 233 /** 234 * Returns advertised PKCE methods, or empty when the metadata field was absent. 235 * 236 * @return methods if advertised 237 * @since 1.0.0 238 */ 239 public @NonNull Optional<@NonNull Set<@NonNull String>> getCodeChallengeMethodsSupported() { 240 return Optional.ofNullable(this.codeChallengeMethodsSupported); 241 } 242 243 /** 244 * Returns advertised token endpoint client authentication methods, or empty when absent. 245 * 246 * @return methods if advertised 247 * @since 1.0.0 248 */ 249 public @NonNull Optional<@NonNull Set<@NonNull String>> getTokenEndpointAuthMethodsSupported() { 250 return Optional.ofNullable(this.tokenEndpointAuthMethodsSupported); 251 } 252 253 /** Returns introspection endpoint methods separately from token endpoint methods. 254 * @return advertised methods, or empty when absent 255 * @since 1.0.0 256 */ 257 public @NonNull Optional<@NonNull Set<@NonNull String>> getIntrospectionEndpointAuthMethodsSupported() { return Optional.ofNullable(this.introspectionEndpointAuthMethodsSupported); } 258 /** 259 * Returns the optional token_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names. 260 * @return advertised or configured names when present 261 * @since 1.0.0 262 */ 263 public @NonNull Optional<@NonNull Set<@NonNull String>> getTokenEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.tokenEndpointAuthSigningAlgValuesSupported); } 264 /** 265 * Returns the optional revocation_endpoint_auth_methods_supported role policy, retaining absent versus empty and unknown names. 266 * @return advertised or configured names when present 267 * @since 1.0.0 268 */ 269 public @NonNull Optional<@NonNull Set<@NonNull String>> getRevocationEndpointAuthMethodsSupported() { return Optional.ofNullable(this.revocationEndpointAuthMethodsSupported); } 270 /** 271 * Returns the optional revocation_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names. 272 * @return advertised or configured names when present 273 * @since 1.0.0 274 */ 275 public @NonNull Optional<@NonNull Set<@NonNull String>> getRevocationEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.revocationEndpointAuthSigningAlgValuesSupported); } 276 /** 277 * Returns the optional introspection_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names. 278 * @return advertised or configured names when present 279 * @since 1.0.0 280 */ 281 public @NonNull Optional<@NonNull Set<@NonNull String>> getIntrospectionEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.introspectionEndpointAuthSigningAlgValuesSupported); } 282 /** 283 * Returns whether metadata advertised RFC 9207 issuer response support. 284 * 285 * @return whether support was advertised 286 * @since 1.0.0 287 */ 288 public @NonNull Boolean isAuthorizationResponseIssuerSupported() { 289 return this.authorizationResponseIssuerSupported; 290 } 291 292 /** 293 * Returns whether this instance came from a checked remote metadata document. 294 * 295 * @return whether discovered 296 * @since 1.0.0 297 */ 298 public @NonNull Boolean isRemotelyDiscovered() { return this.remotelyDiscovered; } 299 300 /** 301 * Builds manually configured metadata. 302 * 303 * @author <a href="https://www.revetkn.com">Mark Allen</a> 304 * @since 1.0.0 305 */ 306 @NotThreadSafe 307 @CheckReturnValue 308 public static final class Builder { 309 private final @NonNull String issuer; 310 private @Nullable URI authorizationEndpoint; 311 private @Nullable URI tokenEndpoint; 312 private @Nullable URI jwksUri; 313 private @Nullable URI introspectionEndpoint; 314 private @Nullable URI revocationEndpoint; 315 private @Nullable Set<@NonNull String> codeChallengeMethodsSupported; 316 private @Nullable Set<@NonNull String> tokenEndpointAuthMethodsSupported; 317 private @Nullable Set<@NonNull String> introspectionEndpointAuthMethodsSupported; 318 private boolean authorizationResponseIssuerSupported; 319 320 private @Nullable Set<@NonNull String> tokenEndpointAuthSigningAlgValuesSupported; 321 322 /** 323 * Replaces the complete token_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set. 324 * @param value names, or null to restore absence 325 * @return this builder 326 * @since 1.0.0 327 */ 328 public @NonNull Builder tokenEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) { 329 this.tokenEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; 330 } 331 332 private @Nullable Set<@NonNull String> revocationEndpointAuthMethodsSupported; 333 334 /** 335 * Replaces the complete revocation_endpoint_auth_methods_supported role policy, preserving an empty set. 336 * @param value names, or null to restore absence 337 * @return this builder 338 * @since 1.0.0 339 */ 340 public @NonNull Builder revocationEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) { 341 this.revocationEndpointAuthMethodsSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; 342 } 343 344 private @Nullable Set<@NonNull String> revocationEndpointAuthSigningAlgValuesSupported; 345 346 /** 347 * Replaces the complete revocation_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set. 348 * @param value names, or null to restore absence 349 * @return this builder 350 * @since 1.0.0 351 */ 352 public @NonNull Builder revocationEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) { 353 this.revocationEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; 354 } 355 356 private @Nullable Set<@NonNull String> introspectionEndpointAuthSigningAlgValuesSupported; 357 358 /** 359 * Replaces the complete introspection_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set. 360 * @param value names, or null to restore absence 361 * @return this builder 362 * @since 1.0.0 363 */ 364 public @NonNull Builder introspectionEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) { 365 this.introspectionEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; 366 } 367 368 private Builder(@NonNull String issuer) { 369 if (requireNonNull(issuer).isEmpty()) 370 throw new IllegalArgumentException("An issuer must not be empty."); 371 this.issuer = issuer; 372 } 373 374 /** 375 * Sets the authorization endpoint. 376 * 377 * @param value endpoint, or null to restore the unset default 378 * @return this builder 379 * @since 1.0.0 380 */ 381 public @NonNull Builder authorizationEndpoint(@Nullable URI value) { 382 this.authorizationEndpoint = value; 383 return this; 384 } 385 386 /** 387 * Sets the token endpoint. 388 * 389 * @param value endpoint, or null to restore the unset default 390 * @return this builder 391 * @since 1.0.0 392 */ 393 public @NonNull Builder tokenEndpoint(@Nullable URI value) { 394 this.tokenEndpoint = value; 395 return this; 396 } 397 398 /** Sets optional jwks_uri. 399 * @param value endpoint, or null to omit 400 * @return this builder 401 * @since 1.0.0 402 */ 403 public @NonNull Builder jwksUri(@Nullable URI value) { this.jwksUri = value; return this; } 404 /** Sets optional introspection_endpoint. 405 * @param value endpoint, or null to omit 406 * @return this builder 407 * @since 1.0.0 408 */ 409 public @NonNull Builder introspectionEndpoint(@Nullable URI value) { this.introspectionEndpoint = value; return this; } 410 /** 411 * Sets an optional revocation endpoint. 412 * 413 * @param value endpoint, or null to restore the unset default, or null to omit 414 * @return this builder 415 * @since 1.0.0 416 */ 417 public @NonNull Builder revocationEndpoint(@Nullable URI value) { 418 this.revocationEndpoint = value; 419 return this; 420 } 421 422 /** 423 * Sets the complete advertised PKCE method set. Null denotes absent metadata. 424 * 425 * @param value methods, or null 426 * @return this builder 427 * @since 1.0.0 428 */ 429 public @NonNull Builder codeChallengeMethodsSupported(@Nullable Set<@NonNull String> value) { 430 this.codeChallengeMethodsSupported = value == null ? null : Set.copyOf(value); 431 return this; 432 } 433 434 /** 435 * Sets the complete advertised client authentication method set. Null denotes absent metadata. 436 * 437 * @param value methods, or null 438 * @return this builder 439 * @since 1.0.0 440 */ 441 public @NonNull Builder tokenEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) { 442 this.tokenEndpointAuthMethodsSupported = value == null ? null : Set.copyOf(value); 443 return this; 444 } 445 446 /** Sets introspection endpoint client authentication methods. 447 * @param value methods, or null to restore absence 448 * @return this builder 449 * @since 1.0.0 450 */ 451 public @NonNull Builder introspectionEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) { this.introspectionEndpointAuthMethodsSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; } 452 /** 453 * Sets whether RFC 9207 issuer response support was advertised. 454 * 455 * @param value whether advertised, or null which restores the default 456 * @return this builder 457 * @since 1.0.0 458 */ 459 public @NonNull Builder authorizationResponseIssuerSupported(@Nullable Boolean value) { 460 this.authorizationResponseIssuerSupported = Boolean.TRUE.equals(value); 461 return this; 462 } 463 464 /** 465 * Builds manually configured metadata. 466 * 467 * @return metadata 468 * @since 1.0.0 469 */ 470 public @NonNull AuthorizationServerMetadata build() { 471 if (this.authorizationEndpoint == null || this.tokenEndpoint == null) 472 throw new IllegalStateException("Authorization and token endpoints are required."); 473 return new AuthorizationServerMetadata(this, false); 474 } 475 476 private @NonNull AuthorizationServerMetadata buildDiscovered() { 477 if (this.authorizationEndpoint == null || this.tokenEndpoint == null) 478 throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED); 479 return new AuthorizationServerMetadata(this, true); 480 } 481 } 482}