com.cloudbees.api.oauth.OauthClient Maven / Gradle / Ivy
Show all versions of cloudbees-api-client Show documentation
package com.cloudbees.api.oauth;
import com.cloudbees.api.BeesClient;
import javax.annotation.CheckForNull;
import java.util.Collection;
import java.util.List;
/**
* Defines OAuth-related CloudBees API.
*
* Also see {@link OauthClientServletUtil} that defines related convenience methods for webapps.
*
* @author Vivek Pandey
* @see BeesClient#getOauthClient()
*/
public interface OauthClient {
/**
* Creates a OAuth token for the current user (used to create {@link BeesClient})
*
* @return OauthToken. always non-null if there was error such as invalid credentials
* @throws OauthClientException if there is any error during token validation
*/
public OauthToken createToken(TokenRequest tokenRequest) throws OauthClientException;
/**
* Deletes a token created by {@link #createToken(TokenRequest)}
*
* @see AbstractOauthToken#delete()
*/
public void deleteToken(String oauthTokenId) throws OauthClientException;
/**
* Lists up all the tokens generated by te current user.
*/
public List listTokens() throws OauthClientException;
/**
* Validates token with the given scopes. Returns null if the given access token is invalid, otherwise OauthToken is returned.
*
*
* {@link BeesClient} must be constructed with OAuth client ID and client secret as the username and password.
*
* @param token non-null token
* @param scopes array of scope that are expected to be granted for this token
* @return null if the token is invalid such as expired or unknown to the CloudBees OAuth server or the expected
* scopes are not found.
*/
@CheckForNull
public OauthToken validateToken(String token, String... scopes) throws OauthClientException;
/**
* Obtains the details of the token and performs minimal validation (such as expiration.)
* Returns null if the given access token is invalid, otherwise OauthToken is returned.
*
*
* {@link BeesClient} must be constructed with OAuth client ID and client secret as the username and password.
*
*
Caching
*
* This method call is a network operation. If you are developing a server application that performs
* frequent token validations, then consider using https://github.com/CloudBees-community/cached-token-validator ,
* which adds caching on top of this.
*
* @param token non-null token
* @return null if the token is invalid such as expired or unknown to the CloudBees OAuth server.
*/
@CheckForNull
public OauthToken validateToken(String token) throws OauthClientException;
/**
* Parses Bearer token from HTTP Authorization header
*
* @param authorizationHeader HTTP Authorization Header
*
* @return Returns null if there is no Bearer token found otherwise a String representing oauth token
*/
public String parseAuthorizationHeader(String authorizationHeader);
/**
* Registers a new OAuth client application.
*
* @return
* A fully populated {@link OauthClientApplication} object. This is not the same object
* as you passed in the input.
*/
public OauthClientApplication registerApplication(OauthClientApplication input) throws OauthClientException;
/**
* Gets the details of an OAuth client application by its client ID.
*
* @return never null. If the app isn't found, an exeption will be thrown.
*/
public OauthClientApplication getApplication(String clientId) throws OauthClientException;
/**
* Lists up all the OAuth client applications registered by the current user.
*/
public List listApplication() throws OauthClientException;
void deleteApplication(String clientId) throws OauthClientException;
/**
* OAuth client application can use this method to exchange the authorization code
* (which it gets from the browser after GC authenticates the user and redirects him back to you)
* to the OAuth access token.
*
*
* For this method to work, {@link BeesClient} should be called with OAuth client ID and secret.
*
* @see Wiki
*
* @param redirectUri
* Required if present in the authorization request, and the value must be the same.
* @return never null. In case of a problem, an exception will be thrown.
*/
OauthToken exchangeToAccessToken(String authorizationCode, String redirectUri) throws OauthClientException;
/**
* Exchange refresh_token to an access token. The new access_token can be created with the same or subset of
* original scopes the refresh token was granted for.
*
* @param refreshToken required. refresh_token.
*
* @param scopes optional. If not provided the returned access_token carries the same scopes as the one granted
* to refresh_token.
* @return Valid OauthToken
*
* @throws OauthClientException
*/
OauthToken exchangeToAccessToken(String refreshToken, String... scopes) throws OauthClientException;
/**
* OAuth client application can use this method to create an OAuth token with arbitrary scopes
* that belongs to the user who registered the application.
*
* The created token will be tied only to the account that the OAuth client application is registered with,
* even if the user who registered it may have access to other accounts.
*
*
* For this method to work, {@link BeesClient} should be called with OAuth client ID and secret.
*
* @see Wiki
*
* @return never null. In case of a problem, an exception will be thrown.
*/
OauthToken createOAuthClientToken(Collection scopes) throws OauthClientException;
/**
* Overloaded version of {@link #createOAuthClientToken(Collection)}
*/
OauthToken createOAuthClientToken(String... scopes) throws OauthClientException;
/**
* Overloaded version of {@link #createOAuthClientToken(Collection)}
*
*/
OauthToken createOAuthClientToken(TokenRequest tokenRequest) throws OauthClientException;
}