io.restassured.module.mockmvc.specification.MockMvcAuthenticationSpecification Maven / Gradle / Ivy

/*
 * Copyright 2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.restassured.module.mockmvc.specification;

import org.springframework.test.web.servlet.request.RequestPostProcessor;

import java.security.Principal;

/**
 * Specify an authentication scheme to use when sending a request. It's recommended to add the spring-security-test module to the classpath and use the {@link #with(RequestPostProcessor, RequestPostProcessor...)} method for authentication and authorization.
 */
public interface MockMvcAuthenticationSpecification {
    /**
     * Authenticate using the given principal. This method simply delegates to {@link org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder#principal(java.security.Principal)}.
     *
     * @param principal The principal to use.
     * @return The request specification
     * @see org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder#principal(java.security.Principal)
     */
    MockMvcRequestSpecification principal(Principal principal);

    /**
     * Authenticate using a {@link RequestPostProcessor}.
     * This is mainly useful when you have added the spring-security-test artifact to classpath. This allows
     * you to do for example:
     *      * given().auth().with(user("username").password("password")). ..
     * 
     * where user is statically imported from org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.
     *
     * @param requestPostProcessor           The first request post processor to be used for authentication
     * @param additionalRequestPostProcessor Additional request post processors to be used for authentication
     * @return A {@link MockMvcAuthenticationScheme} instance.
     */
    MockMvcRequestSpecification with(RequestPostProcessor requestPostProcessor, RequestPostProcessor... additionalRequestPostProcessor);

    /**
     * Authenticate using the given principal. The principal will be used like this:
     *      * SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken(principal, ""));
     * 
     * 
     * 

     * Note that this method require Spring Security to be on the classpath. Also note that if you use this method Rest Assured will NOT be thread-safe.
     * 
     *
     * @param principal The principal to use.
     * @return The request specification
     */
    MockMvcRequestSpecification principal(Object principal);

    /**
     * Authenticate using the given principal and credentials. The principal and credentials will be used like this:
     *      * SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken(principal, credentials, authorities));
     * 
     * 
     * 

     * Note that this method require Spring Security to be on the classpath. Also note that if you use this method Rest Assured will NOT be thread-safe.
     * 
     *
     * @param principal   The principal to use.
     * @param credentials The credentials to use
     * @param authorities Optional list of authorities
     * @return The request specification
     */
    MockMvcRequestSpecification principalWithCredentials(Object principal, Object credentials, String... authorities);

    /**
     * Authenticate using the given authentication instance. The authentication instance will be used like this:
     *      * SecurityContextHolder.getContext().setAuthentication(authentication);
     * 
     * This means that the supplied object must be an instance of org.springframework.security.core.Authentication.
     * 
     * Note that this method require Spring Security to be on the classpath. Also note that if you use this method Rest Assured will NOT be thread-safe.
     * 
     *
     * @param authentication the spring security authentication to use.
     * @return The request specification
     */
    MockMvcRequestSpecification authentication(Object authentication);

    /**
     * Explicitly state that you don't which to use any authentication in this request. This is useful only in cases where you've
     * specified a default authentication scheme and you wish to override it for a single request.
     *
     * @return The request specification
     */
    MockMvcRequestSpecification none();
}