001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.auth;
018
019import java.security.*;
020
021/**
022 * SPI for verifying an opaque bearer token and producing the associated {@link Principal}.
023 *
024 * <p>
025 * {@link BearerTokenGuard} extracts the token from the {@code Authorization: Bearer <token>} header
026 * and delegates verification to a {@code TokenValidator} the host supplies. The validator is the
027 * authoritative source of "is this token still good?" &mdash; signature, expiry, audience, issuer,
028 * revocation, etc.
029 *
030 * <p>
031 * Implementations:
032 * <ul>
033 *    <li><b>JWT</b> &mdash; the optional {@code juneau-rest-server-auth-jwt} sub-module ships
034 *       {@code JwtTokenValidator}, which performs JWKS-backed signature verification with full
035 *       {@code iss} / {@code aud} / {@code exp} / {@code nbf} / algorithm-allowlist enforcement.
036 *    <li><b>Opaque token</b> &mdash; e.g. a 32-byte random token stored in a database; the validator
037 *       looks the token up in the store and returns the associated user record wrapped as a
038 *       {@link Principal}.
039 *    <li><b>Introspection</b> &mdash; e.g. RFC 7662 token introspection over HTTP against the issuing
040 *       IdP; the validator caches successful responses for a short TTL.
041 * </ul>
042 *
043 * <h5 class='topic'>Contract</h5>
044 *
045 * <p>
046 * On success, return a non-null {@link Principal}. On failure, throw {@link AuthenticationException}
047 * with a {@code WWW-Authenticate} challenge string set via
048 * {@link AuthenticationException#wwwAuthenticate(String)}. Returning <jk>null</jk> is treated as failure
049 * by the guard but produces a generic challenge &mdash; throwing is preferred so the failure reason
050 * surfaces in the response body.
051 *
052 * <p>
053 * The supplied {@code token} string is exactly what followed {@code "Bearer "} in the {@code Authorization}
054 * header &mdash; the guard does not pre-trim or unquote. Validators should treat it as untrusted input
055 * (no logging of full tokens, no exception messages echoing the token, etc.).
056 *
057 * <h5 class='section'>See Also:</h5><ul>
058 *    <li class='jc'>{@link BearerTokenGuard}
059 *    <li class='jc'>{@link AuthenticationException}
060 *    <li class='link'><a class="doclink" href="https://datatracker.ietf.org/doc/html/rfc6750">RFC 6750 &mdash; Bearer Token Usage</a>
061 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerAuthGuards">AuthN Guards — Bearer / API-Key / JWT</a>
062 * </ul>
063 *
064 * @since 10.0.0
065 */
066@FunctionalInterface
067public interface TokenValidator {
068
069   /**
070    * Validates the supplied bearer token and returns the associated {@link Principal}.
071    *
072    * @param token The raw token string from {@code Authorization: Bearer <token>}. Never <jk>null</jk>.
073    * @return The authenticated principal. Must not be <jk>null</jk> on success.
074    * @throws AuthenticationException If the token is invalid, expired, revoked, or otherwise unacceptable.
075    */
076   Principal validate(String token) throws AuthenticationException;
077}