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 static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023import java.security.*;
024
025/**
026 * Marks a {@code @RestOp}-method parameter as the authenticated {@link Principal} for the current request.
027 *
028 * <p>
029 * When a request reaches an op handler annotated with {@code @Auth}, the framework's
030 * {@link AuthArg} resolver pulls the {@link Principal} previously stashed by an upstream AuthN guard
031 * (such as {@link BearerTokenGuard} or {@link ApiKeyGuard}) on the request attributes under the
032 * {@code "juneau.principal"} key.
033 *
034 * <p>
035 * If an annotated parameter is reached without a principal being stashed (i.e. no guard ran, or the
036 * request was made on an unguarded path) the resolver returns <jk>null</jk> &mdash; the guard chain is
037 * the contract that guarantees a non-null value; this annotation only requests the lookup.
038 *
039 * <h5 class='section'>Type-driven equivalent:</h5>
040 *
041 * <p>
042 * For convenience, the framework also resolves a bare {@link Principal} (or {@link ClaimsPrincipal})
043 * parameter <i>without</i> any annotation &mdash; the type alone is enough to trigger the same lookup.
044 * Use {@code @Auth} when you want the intent to be self-documenting on the parameter list or you want
045 * to disambiguate against another arg resolver that might claim the parameter first.
046 *
047 * <h5 class='section'>Example:</h5>
048 *
049 * <p class='bjava'>
050 *    <ja>@RestGet</ja>(path=<js>"/me"</js>)
051 *    <jk>public</jk> Profile me(<ja>@Auth</ja> Principal <jv>p</jv>) {
052 *       <jk>return</jk> <jf>profileService</jf>.lookup(<jv>p</jv>.getName());
053 *    }
054 *
055 *    <ja>@RestGet</ja>(path=<js>"/claims"</js>)
056 *    <jk>public</jk> String scope(<ja>@Auth</ja> ClaimsPrincipal <jv>p</jv>) {
057 *       <jk>return</jk> <jv>p</jv>.getClaim(<js>"scope"</js>, String.<jk>class</jk>).orElse(<js>""</js>);
058 *    }
059 * </p>
060 *
061 * <h5 class='section'>See Also:</h5><ul>
062 *    <li class='jc'>{@link AuthArg}
063 *    <li class='jc'>{@link BearerTokenGuard}
064 *    <li class='jc'>{@link ApiKeyGuard}
065 *    <li class='jc'>{@link ClaimsPrincipal}
066 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerAuthGuards">AuthN Guards — Bearer / API-Key / JWT</a>
067 * </ul>
068 *
069 * @since 10.0.0
070 */
071@Target(PARAMETER)
072@Retention(RUNTIME)
073@Documented
074public @interface Auth {
075}