Interface OAuthProvider
-
- All Superinterfaces:
java.io.Serializable
- All Known Implementing Classes:
AbstractOAuthProvider
,CommonsHttpOAuthProvider
,DefaultOAuthProvider
public interface OAuthProvider extends java.io.Serializable
Supplies an interface that can be used to retrieve request and access tokens from an OAuth 1.0(a) service provider. A provider object requires an
OAuthConsumer
to sign the token request message; after a token has been retrieved, the consumer is automatically updated with the token and the corresponding secret.To initiate the token exchange, create a new provider instance and configure it with the URLs the service provider exposes for requesting tokens and resource authorization, e.g.:
OAuthProvider provider = new DefaultOAuthProvider("http://twitter.com/oauth/request_token", "http://twitter.com/oauth/access_token", "http://twitter.com/oauth/authorize");
Depending on the HTTP library you use, you may need a different provider type, refer to the website documentation for how to do that.
To receive a request token which the user must authorize, you invoke it using a consumer instance and a callback URL:
String url = provider.retrieveRequestToken(consumer, "http://www.example.com/callback");
That url must be opened in a Web browser, where the user can grant access to the resources in question. If that succeeds, the service provider will redirect to the callback URL and append the blessed request token.
That token must now be exchanged for an access token, as such:
provider.retrieveAccessToken(consumer, nullOrVerifierCode);
where nullOrVerifierCode is either null if your provided a callback URL in the previous step, or the pin code issued by the service provider to the user if the request was out-of-band (cf.
OAuth.OUT_OF_BAND
.The consumer used during token handshakes is now ready for signing.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description java.lang.String
getAccessTokenEndpointUrl()
java.lang.String
getAuthorizationWebsiteUrl()
java.util.Map<java.lang.String,java.lang.String>
getRequestHeaders()
Deprecated.THIS METHOD HAS BEEN DEPRECATED.java.lang.String
getRequestTokenEndpointUrl()
HttpParameters
getResponseParameters()
Any additional non-OAuth parameters returned in the response body of a token request can be obtained through this method.boolean
isOAuth10a()
void
removeListener(OAuthProviderListener listener)
void
retrieveAccessToken(OAuthConsumer consumer, java.lang.String oauthVerifier, java.lang.String... customOAuthParams)
Queries the service provider for an access token.java.lang.String
retrieveRequestToken(OAuthConsumer consumer, java.lang.String callbackUrl, java.lang.String... customOAuthParams)
Queries the service provider for a request token.void
setListener(OAuthProviderListener listener)
void
setOAuth10a(boolean isOAuth10aProvider)
void
setRequestHeader(java.lang.String header, java.lang.String value)
Deprecated.void
setResponseParameters(HttpParameters parameters)
Subclasses must use this setter to preserve any non-OAuth query parameters contained in the server response.
-
-
-
Method Detail
-
retrieveRequestToken
java.lang.String retrieveRequestToken(OAuthConsumer consumer, java.lang.String callbackUrl, java.lang.String... customOAuthParams) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
Queries the service provider for a request token.Pre-conditions: the given
OAuthConsumer
must have a valid consumer key and consumer secret already set.Post-conditions: the given
OAuthConsumer
will have an unauthorized request token and token secret set.- Parameters:
consumer
- theOAuthConsumer
that should be used to sign the requestcallbackUrl
- Pass an actual URL if your app can receive callbacks and you want to get informed about the result of the authorization process. PassOAuth.OUT_OF_BAND
if the service provider implements OAuth 1.0a and your app cannot receive callbacks. Pass null if the service provider implements OAuth 1.0 and your app cannot receive callbacks. Please note that some services (among them Twitter) will fail authorization if you pass a callback URL but register your application as a desktop app (which would only be able to handle OOB requests).customOAuthParams
- you can pass custom OAuth parameters here which will go directly into the signer, i.e. you don't have to put them into the request first. This is useful for pre-setting OAuth params for signing. Pass them sequentially in key/value order.- Returns:
- The URL to which the user must be sent in order to authorize the consumer. It includes the unauthorized request token (and in the case of OAuth 1.0, the callback URL -- 1.0a clients send along with the token request).
- Throws:
OAuthMessageSignerException
- if signing the request failedOAuthNotAuthorizedException
- if the service provider rejected the consumerOAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or service providerOAuthCommunicationException
- if server communication failed
-
retrieveAccessToken
void retrieveAccessToken(OAuthConsumer consumer, java.lang.String oauthVerifier, java.lang.String... customOAuthParams) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
Queries the service provider for an access token.Pre-conditions: the given
OAuthConsumer
must have a valid consumer key, consumer secret, authorized request token and token secret already set.Post-conditions: the given
OAuthConsumer
will have an access token and token secret set.- Parameters:
consumer
- theOAuthConsumer
that should be used to sign the requestoauthVerifier
- NOTE: Only applies to service providers implementing OAuth 1.0a. Set to null if the service provider is still using OAuth 1.0. The verification code issued by the service provider after the the user has granted the consumer authorization. If the callback method provided in the previous step wasOAuth.OUT_OF_BAND
, then you must ask the user for this value. If your app has received a callback, the verfication code was passed as part of that request instead.customOAuthParams
- you can pass custom OAuth parameters here which will go directly into the signer, i.e. you don't have to put them into the request first. This is useful for pre-setting OAuth params for signing. Pass them sequentially in key/value order.- Throws:
OAuthMessageSignerException
- if signing the request failedOAuthNotAuthorizedException
- if the service provider rejected the consumerOAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or service providerOAuthCommunicationException
- if server communication failed
-
getResponseParameters
HttpParameters getResponseParameters()
Any additional non-OAuth parameters returned in the response body of a token request can be obtained through this method. These parameters will be preserved until the next token request is issued. The return value is never null.
-
setResponseParameters
void setResponseParameters(HttpParameters parameters)
Subclasses must use this setter to preserve any non-OAuth query parameters contained in the server response. It's the caller's responsibility that any OAuth parameters be removed beforehand.- Parameters:
parameters
- the map of query parameters served by the service provider in the token response
-
setRequestHeader
@Deprecated void setRequestHeader(java.lang.String header, java.lang.String value)
Deprecated.Use this method to set custom HTTP headers to be used for the requests which are sent to retrieve tokens. @deprecated THIS METHOD HAS BEEN DEPRECATED. UseOAuthProviderListener
to customize requests.- Parameters:
header
- The header name (e.g. 'WWW-Authenticate')value
- The header value (e.g. 'realm=www.example.com')
-
getRequestHeaders
@Deprecated java.util.Map<java.lang.String,java.lang.String> getRequestHeaders()
Deprecated.THIS METHOD HAS BEEN DEPRECATED. UseOAuthProviderListener
to customize requests.- Returns:
- all request headers set via
setRequestHeader(java.lang.String, java.lang.String)
-
setOAuth10a
void setOAuth10a(boolean isOAuth10aProvider)
- Parameters:
isOAuth10aProvider
- set to true if the service provider supports OAuth 1.0a. Note that you need only call this method if you reconstruct a provider object in between calls to retrieveRequestToken() and retrieveAccessToken() (i.e. if the object state isn't preserved). If instead those two methods are called on the same provider instance, this flag will be deducted automatically based on the server response during retrieveRequestToken(), so you can simply ignore this method.
-
isOAuth10a
boolean isOAuth10a()
- Returns:
- true if the service provider supports OAuth 1.0a. Note that the value returned here is only meaningful after you have already performed the token handshake, otherwise there is no way to determine what version of the OAuth protocol the service provider implements.
-
getRequestTokenEndpointUrl
java.lang.String getRequestTokenEndpointUrl()
-
getAccessTokenEndpointUrl
java.lang.String getAccessTokenEndpointUrl()
-
getAuthorizationWebsiteUrl
java.lang.String getAuthorizationWebsiteUrl()
-
setListener
void setListener(OAuthProviderListener listener)
-
removeListener
void removeListener(OAuthProviderListener listener)
-
-