org.springframework.security.oauth.consumer.OAuthConsumerSupport.java Source code

Introduction

Here is the source code for org.springframework.security.oauth.consumer.OAuthConsumerSupport.java

Source

/*
 * Copyright 2008 Web Cohesion
 *
 * 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
 *
 *   https://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 org.springframework.security.oauth.consumer;

import java.net.URL;
import java.io.InputStream;
import java.util.Map;

/**
 * Consumer-side support for OAuth.
 *
 * @author Ryan Heaton
 */
public interface OAuthConsumerSupport {

    /**
     * Get an unauthorized request token for a protected resource.
     *
     * @param resourceId The id of the protected resource for which to get a consumer token.
     * @param callback The callback URL.
     * @return The unauthorized request token.
     */
    OAuthConsumerToken getUnauthorizedRequestToken(String resourceId, String callback)
            throws OAuthRequestFailedException;

    /**
     * Get an unauthorized request token for a protected resource.
     *
     * @param resource The protected resource for which to get a consumer token.
     * @param callback The callback URL.
     * @return The unauthorized request token.
     */
    OAuthConsumerToken getUnauthorizedRequestToken(ProtectedResourceDetails resource, String callback)
            throws OAuthRequestFailedException;

    /**
     * Get an access token for a protected resource.
     *
     * @param requestToken The (presumably authorized) request token.
     * @param verifier The token verifier.
     * @return The access token.
     */
    OAuthConsumerToken getAccessToken(OAuthConsumerToken requestToken, String verifier)
            throws OAuthRequestFailedException;

    /**
     * Get an access token for a protected resource.
     *
     * @param resource The resource for which to get the access token.
     * @param requestToken The (presumably authorized) request token.
     * @param verifier The token verifier.
     * @return The access token.
     */
    OAuthConsumerToken getAccessToken(ProtectedResourceDetails resource, OAuthConsumerToken requestToken,
            String verifier);

    /**
     * Read a protected resource from the given URL using the specified access token and HTTP method.
     *
     * @param url The URL.
     * @param accessToken The access token.
     * @param httpMethod The HTTP method.
     * @return The protected resource.
     */
    InputStream readProtectedResource(URL url, OAuthConsumerToken accessToken, String httpMethod)
            throws OAuthRequestFailedException;

    /**
     * Create a configured URL.  If the HTTP method to access the resource is "POST" or "PUT" and the "Authorization"
     * header isn't supported, then the OAuth parameters will be expected to be sent in the body of the request. Otherwise,
     * you can assume that the given URL is ready to be used without further work.
     *
     * @param url         The base URL.
     * @param accessToken The access token.
     * @param httpMethod The HTTP method.
     * @param additionalParameters Any additional request parameters.
     * @return The configured URL.
     */
    URL configureURLForProtectedAccess(URL url, OAuthConsumerToken accessToken, String httpMethod,
            Map<String, String> additionalParameters) throws OAuthRequestFailedException;

    /**
     * Get the authorization header using the given access token that should be applied to the specified URL.
     *
     * @param details     The details of the protected resource.
     * @param accessToken The access token.
     * @param url         The URL of the request.
     * @param httpMethod  The http method for the protected resource.
     * @param additionalParameters Any additional request parameters.
     * @return The authorization header, or null if the authorization header isn't supported by the provider of this resource.
     */
    String getAuthorizationHeader(ProtectedResourceDetails details, OAuthConsumerToken accessToken, URL url,
            String httpMethod, Map<String, String> additionalParameters);

    /**
     * Get the query string that is to be used in the given request. The query string will
     * include any custom query parameters in the URL and any necessary OAuth parameters.  Note,
     * however, that an OAuth parameter is not considered "necessary" if the provider of the resource
     * supports the authorization header.
     *
     * Any OAuth parameters will be URL-encoded, but not oauth-encoded, per the OAuth spec. 
     *
     * The query string is to be used by either applying it to the URL (for HTTP GET) or putting it
     * in the body of the request (for HTTP POST).
     *
     * @param details The resource details.
     * @param accessToken The access token.
     * @param url The URL
     * @param httpMethod The http method.
     * @param additionalParameters Any additional OAuth request parameters.
     * @return The query string.
     */
    String getOAuthQueryString(ProtectedResourceDetails details, OAuthConsumerToken accessToken, URL url,
            String httpMethod, Map<String, String> additionalParameters);
}