* An OAuth Service is an abstract representation of the standard remote API * offered by an {@link org.apache.amber.server.OAuthProvider}, providing a simple mechanism * for performing {@link org.apache.amber.OAuth} authentication and authorisation * tasks. *
* ** By far the easiest way to use an OAuthClient is by configuring an * {@link org.apache.amber.server.OAuthProvider} in an XML file (called * "oauth-providers.xml") and placing it in the META-INF directory on * the applications classpath. *
* ** <?xml version="1.0" encoding="UTF-8"?> * <providers> * <provider * realm="http://example.com" * algorithm="HmacSHA1" * requestTokenPath="/oauth/request_token" * authorizePath="/oauth/authorize" * accessTokenPath="/oauth/access_token"> * <consumer * name="mysite.com" * callback="http://www.mysite.com/oauth/response" * key="mykey" * secret="mysecret"/> * </provider> * </providers> ** *
* The OAuthClient is called by using it's realm name as a reference. The * example below assumes the API is used in a Servlet environment, and simply * redirects the user to the {@link org.apache.amber.server.OAuthProvider} to authorize the * token. *
* ** The {@link org.apache.amber.server.OAuthProvider} uses the default * {@link OAuthConsumer} configured in the XML file. *
* *
* HttpSession session = request.getSession();
*
* OAuthClient service = OAuth.useService("http://example.com");
* OAuthToken requestToken = service.getRequestToken(); // This method also takes an OAuthToken implementation class
*
* session.setAttribute("requestToken", requestToken);
*
* String authorizePath = service.getAuthorizeURL(requestToken);
* response.sendRedirect(authorizePath);
*
*
* * If you supply your own implementation of the {@link org.apache.amber.OAuthToken} * interface when you call the requestToken method, you could store the * OAuthToken in a database. *
* ** The token is stored in the user session, as we can re-use it when the * response comes back. We initialise the service and retrieve the token from * the session, before resubmitting the token and the verifier to the * {@link org.apache.amber.server.OAuthProvider}, who converts the authorised Request Token * into an Access Token. *
* ** After checking that the token is authorised, we remove the old request token * from the session and add the access token, so it can be used to sign future * requests for services at the {@link org.apache.amber.server.OAuthProvider}. *
* *
* HttpSession session = req.getSession();
*
* OAuthClient service = OAuth.useService("http://oauth.apache.site/");
* OAuthToken requestToken = OAuthToken.class.cast(session
* .getAttribute("requestToken"));
*
* String oauth_token = req.getParameter("oauth_token"); // you could check this matches the one in the session
* String oauth_verifier = req.getParameter("oauth_verifier"); // supplied with the response
* OAuthToken accessToken = service.getAccessToken(requestToken, oauth_verifier);
*
* if (accessToken.isAuthorized()) {
* session.removeAttribute("requestToken");
* session.setAttribute("accessToken", accessToken);
* }
*
*
* * The OAuthClient could be initialised in an HttpServlet.init() method and * stored in an instance field. Implementations must be thread-safe. *
* * @version $Id$ */ public interface OAuthClient extends Serializable { /** * Get a request token using the default consumer and token. * * @return token * @throws org.apache.amber.OAuthException */ OAuthToken getRequestToken() throws OAuthException; /** * Get a request token using the specified consumer. * * @param consumer * @return token * @throws OAuthException */ OAuthToken getRequestToken(OAuthConsumer consumer) throws OAuthException; /** * Get a request token, instantiated from the provided class, using the * default consumer. * * @param tokenClass * @return token * @throws OAuthException */ OAuthToken getRequestToken(Class tokenClass) throws OAuthException; /** * Get a request token, instantiated from the provided class, using the * specified consumer. * * @param tokenClass * @param consumer * @return token * @throws OAuthException */ OAuthToken getRequestToken(Class tokenClass, OAuthConsumer consumer) throws OAuthException; /** * Get the authentication URL for the configured provider, using the * specified token. * * @param token * The token to be authenticated * @return path The path to which the user should be directed for * authentication */ String getAuthenticateURL(OAuthToken token); /** * Get the authentication URL for the configured provider, using the * specified token and callback. * * @param token * @param callback * The URL to which the user should be redirected after * authentication * @return path The path to which the user should be directed for * authentication */ String getAuthenticateURL(OAuthToken token, String callback); /** * Get the authorisation URL for the configured provider, using the * specified token. * * @param token * The token to be authorised * @return path The path to which the user should be directed for * authentication */ String getAuthorizeURL(OAuthToken token); /** * Get the authorisation URL for the configured provider, using the * specified token. * * @param token * @param callback * The URL to which the user should be redirected after * authorisation * @return path The path to which the user should be directed for * authorisation */ String getAuthorizeURL(OAuthToken token, String callback); /** * Convert the authorised token to an access token, using the supplied * verification code. * * @param token * @param verifier * @return authorised token * @throws OAuthException */ OAuthToken getAccessToken(OAuthToken token, String verifier) throws OAuthException; /** * Convert the authorised token to an access token, using the supplied * consumer and verification code. * * @param consumer * @param token * @param verifier * @return authorised token * @throws OAuthException */ OAuthToken getAccessToken(OAuthConsumer consumer, OAuthToken token, String verifier) throws OAuthException; /** * Get the current connector. * * @return connector */ HttpConnector getConnector(); /** * Set the connector to be used. * * @param httpConnector */ void setConnector(HttpConnector httpConnector); /** * Returns the current nonce generator to be used. * * @return the current nonce generator to be used. */ NonceGenerator getNonceGenerator(); /** * Sets the nonce generator to be used. * * @param nonceGenerator the nonce generator to be used. */ void setNonceGenerator(NonceGenerator nonceGenerator); }