1 /*
2 * Copyright 2008 Web Cohesion
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.security.oauth.consumer;
18
19
20 import java.net.URL;
21 import java.io.InputStream;
22 import java.util.Map;
23
24 /**
25 * Consumer-side support for OAuth.
26 *
27 * @author Ryan Heaton
28 */
29 public interface OAuthConsumerSupport {
30
31 /**
32 * Get an unauthorized request token for a protected resource.
33 *
34 * @param resourceId The id of the protected resource for which to get a consumer token.
35 * @param callback The callback URL.
36 * @return The unauthorized request token.
37 */
38 OAuthConsumerToken getUnauthorizedRequestToken(String resourceId, String callback) throws OAuthRequestFailedException;
39
40 /**
41 * Get an unauthorized request token for a protected resource.
42 *
43 * @param resource The protected resource for which to get a consumer token.
44 * @param callback The callback URL.
45 * @return The unauthorized request token.
46 */
47 OAuthConsumerToken getUnauthorizedRequestToken(ProtectedResourceDetails resource, String callback) throws OAuthRequestFailedException;
48
49 /**
50 * Get an access token for a protected resource.
51 *
52 * @param requestToken The (presumably authorized) request token.
53 * @param verifier The token verifier.
54 * @return The access token.
55 */
56 OAuthConsumerTokeng/springframework/security/oauth/consumer/OAuthConsumerToken.html#OAuthConsumerToken">OAuthConsumerToken getAccessToken(OAuthConsumerToken requestToken, String verifier) throws OAuthRequestFailedException;
57
58 /**
59 * Get an access token for a protected resource.
60 *
61 * @param resource The resource for which to get the access token.
62 * @param requestToken The (presumably authorized) request token.
63 * @param verifier The token verifier.
64 * @return The access token.
65 */
66 OAuthConsumerTokennsumer/OAuthConsumerToken.html#OAuthConsumerToken">OAuthConsumerToken getAccessToken(ProtectedResourceDetails resource, OAuthConsumerToken requestToken, String verifier);
67
68 /**
69 * Read a protected resource from the given URL using the specified access token and HTTP method.
70 *
71 * @param url The URL.
72 * @param accessToken The access token.
73 * @param httpMethod The HTTP method.
74 * @return The protected resource.
75 */
76 InputStream readProtectedResource(URL url, OAuthConsumerToken accessToken, String httpMethod) throws OAuthRequestFailedException;
77
78 /**
79 * Create a configured URL. If the HTTP method to access the resource is "POST" or "PUT" and the "Authorization"
80 * header isn't supported, then the OAuth parameters will be expected to be sent in the body of the request. Otherwise,
81 * you can assume that the given URL is ready to be used without further work.
82 *
83 * @param url The base URL.
84 * @param accessToken The access token.
85 * @param httpMethod The HTTP method.
86 * @param additionalParameters Any additional request parameters.
87 * @return The configured URL.
88 */
89 URL configureURLForProtectedAccess(URL url, OAuthConsumerToken accessToken, String httpMethod, Map<String, String> additionalParameters) throws OAuthRequestFailedException;
90
91 /**
92 * Get the authorization header using the given access token that should be applied to the specified URL.
93 *
94 * @param details The details of the protected resource.
95 * @param accessToken The access token.
96 * @param url The URL of the request.
97 * @param httpMethod The http method for the protected resource.
98 * @param additionalParameters Any additional request parameters.
99 * @return The authorization header, or null if the authorization header isn't supported by the provider of this resource.
100 */
101 String getAuthorizationHeader(ProtectedResourceDetails details, OAuthConsumerToken accessToken, URL url, String httpMethod, Map<String, String> additionalParameters);
102
103 /**
104 * Get the query string that is to be used in the given request. The query string will
105 * include any custom query parameters in the URL and any necessary OAuth parameters. Note,
106 * however, that an OAuth parameter is not considered "necessary" if the provider of the resource
107 * supports the authorization header.
108 *
109 * Any OAuth parameters will be URL-encoded, but not oauth-encoded, per the OAuth spec.
110 *
111 * The query string is to be used by either applying it to the URL (for HTTP GET) or putting it
112 * in the body of the request (for HTTP POST).
113 *
114 * @param details The resource details.
115 * @param accessToken The access token.
116 * @param url The URL
117 * @param httpMethod The http method.
118 * @param additionalParameters Any additional OAuth request parameters.
119 * @return The query string.
120 */
121 String getOAuthQueryString(ProtectedResourceDetails details, OAuthConsumerToken accessToken, URL url, String httpMethod, Map<String, String> additionalParameters);
122 }