001    /*
002     * The contents of this file are subject to the terms
003     * of the Common Development and Distribution License
004     * (the "License").  You may not use this file except
005     * in compliance with the License.
006     * 
007     * You can obtain a copy of the license at
008     * http://www.opensource.org/licenses/cddl1.php
009     * See the License for the specific language governing
010     * permissions and limitations under the License.
011     */
012    
013    package javax.ws.rs.core;
014    
015    import java.security.Principal;
016    
017    /**
018     * An injectable interface that provides access to security related
019     * information.
020     * 
021     * @see Context
022     */
023    public interface SecurityContext {
024        
025        /**
026         * String identifier for Basic authentication. Value "BASIC"
027         */
028        public static final String BASIC_AUTH = "BASIC";
029        
030        /**
031         * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
032         */
033        public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
034        
035        /**
036         * String identifier for Digest authentication. Value "DIGEST"
037         */
038        public static final String DIGEST_AUTH = "DIGEST";
039        
040        /**
041         * String identifier for Form authentication. Value "FORM"
042         */
043        public static final String FORM_AUTH = "FORM";
044    
045        /**
046         * Returns a <code>java.security.Principal</code> object containing the 
047         * name of the current authenticated user. If the user 
048         * has not been authenticated, the method returns null.
049         *
050         * @return a <code>java.security.Principal</code> containing the name
051         * of the user making this request; null if the user has not been 
052         * authenticated
053         * @throws java.lang.IllegalStateException if called outside the scope of a request
054         */
055        public Principal getUserPrincipal();
056        
057        /**
058         * Returns a boolean indicating whether the authenticated user is included 
059         * in the specified logical "role". If the user has not been authenticated,
060         * the method returns <code>false</code>.
061         *
062         * @param role a <code>String</code> specifying the name of the role
063         * @return a <code>boolean</code> indicating whether the user making 
064         * the request belongs to a given role; <code>false</code> if the user
065         * has not been authenticated
066         * @throws java.lang.IllegalStateException if called outside the scope of a request
067         */
068        public boolean isUserInRole(String role);
069        
070        /**
071         * Returns a boolean indicating whether this request was made 
072         * using a secure channel, such as HTTPS.
073         *
074         * @return <code>true</code> if the request was made using a secure 
075         * channel, <code>false</code> otherwise
076         * @throws java.lang.IllegalStateException if called outside the scope of a request
077         */
078        public boolean isSecure();
079        
080        /**
081         * Returns the string value of the authentication scheme used to protect 
082         * the resource. If the resource is not authenticated, null is returned.
083         * 
084         * Values are the same as the CGI variable AUTH_TYPE
085         * 
086         * @return one of the static members BASIC_AUTH, FORM_AUTH, 
087         * CLIENT_CERT_AUTH, DIGEST_AUTH (suitable for == comparison) or the 
088         * container-specific string indicating the authentication scheme, 
089         * or null if the request was not authenticated.
090         * @throws java.lang.IllegalStateException if called outside the scope of a request
091         */
092        public String getAuthenticationScheme();
093        
094    }