com.cloudbees.api.oauth

Interface OauthClient

All Known Implementing Classes:

OauthClientImpl

public interface OauthClient

Defines OAuth-related CloudBees API. Also see OauthClientServletUtil that defines related convenience methods for webapps.

Author:

Vivek Pandey

See Also:

BeesClient.getOauthClient()

Method Summary

Methods

Modifier and Type	Method and Description
OauthToken	createOAuthClientToken(Collection<String> scopes) OAuth client application can use this method to create an OAuth token with arbitrary scopes that belongs to the user who registered the application.
OauthToken	createOAuthClientToken(String... scopes) Overloaded version of createOAuthClientToken(Collection)
OauthToken	createOAuthClientToken(TokenRequest tokenRequest) Overloaded version of createOAuthClientToken(Collection)
OauthToken	createToken(TokenRequest tokenRequest) Creates a OAuth token for the current user (used to create BeesClient)
void	deleteApplication(String clientId)
void	deleteToken(String oauthTokenId) Deletes a token created by createToken(TokenRequest)
OauthToken	exchangeToAccessToken(String refreshToken, String... scopes) Exchange refresh_token to an access token.
OauthToken	exchangeToAccessToken(String authorizationCode, String redirectUri) 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.
OauthClientApplication	getApplication(String clientId) Gets the details of an OAuth client application by its client ID.
List<OauthClientApplication>	listApplication() Lists up all the OAuth client applications registered by the current user.
List<OauthTokenDetail>	listTokens() Lists up all the tokens generated by te current user.
String	parseAuthorizationHeader(String authorizationHeader) Parses Bearer token from HTTP Authorization header
OauthClientApplication	registerApplication(OauthClientApplication input) Registers a new OAuth client application.
OauthToken	validateToken(String token) 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.
OauthToken	validateToken(String token, String... scopes) Validates token with the given scopes.

Method Detail

createToken

OauthToken createToken(TokenRequest tokenRequest)
                       throws OauthClientException

Creates a OAuth token for the current user (used to create BeesClient)

Returns:

OauthToken. always non-null if there was error such as invalid credentials

Throws:

OauthClientException - if there is any error during token validation

deleteToken

void deleteToken(String oauthTokenId)
                 throws OauthClientException

Deletes a token created by createToken(TokenRequest)

Throws:

OauthClientException

See Also:

AbstractOauthToken.delete()

listTokens

List<OauthTokenDetail> listTokens()
                                  throws OauthClientException

Lists up all the tokens generated by te current user.

Throws:

OauthClientException

validateToken

@CheckForNull
OauthToken validateToken(String token,
                                    String... scopes)
                         throws OauthClientException

Validates token with the given scopes. Returns null if the given access token is invalid, otherwise OauthToken is returned.

BeesClient must be constructed with OAuth client ID and client secret as the username and password.

Parameters:

token - non-null token

scopes - array of scope that are expected to be granted for this token

Returns:

null if the token is invalid such as expired or unknown to the CloudBees OAuth server or the expected scopes are not found.

Throws:

OauthClientException

validateToken

@CheckForNull
OauthToken validateToken(String token)
                         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.

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.

Parameters:

token - non-null token

Returns:

null if the token is invalid such as expired or unknown to the CloudBees OAuth server.

Throws:

OauthClientException

parseAuthorizationHeader

String parseAuthorizationHeader(String authorizationHeader)

Parses Bearer token from HTTP Authorization header

Parameters:

authorizationHeader - HTTP Authorization Header

Returns:

Returns null if there is no Bearer token found otherwise a String representing oauth token

registerApplication

OauthClientApplication registerApplication(OauthClientApplication input)
                                           throws OauthClientException

Registers a new OAuth client application.

Returns:

A fully populated OauthClientApplication object. This is not the same object as you passed in the input.

Throws:

OauthClientException

getApplication

OauthClientApplication getApplication(String clientId)
                                      throws OauthClientException

Gets the details of an OAuth client application by its client ID.

Returns:

never null. If the app isn't found, an exeption will be thrown.

Throws:

OauthClientException

listApplication

List<OauthClientApplication> listApplication()
                                             throws OauthClientException

Lists up all the OAuth client applications registered by the current user.

Throws:

OauthClientException

deleteApplication

void deleteApplication(String clientId)
                       throws OauthClientException

Throws:

OauthClientException

exchangeToAccessToken

OauthToken exchangeToAccessToken(String authorizationCode,
                               String redirectUri)
                                 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, BeesClient should be called with OAuth client ID and secret.

Parameters:

redirectUri - Required if present in the authorization request, and the value must be the same.

Returns:

never null. In case of a problem, an exception will be thrown.

Throws:

OauthClientException

See Also:

Wiki

exchangeToAccessToken

OauthToken exchangeToAccessToken(String refreshToken,
                               String... scopes)
                                 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.

Parameters:

refreshToken - required. refresh_token.

scopes - optional. If not provided the returned access_token carries the same scopes as the one granted to refresh_token.

Returns:

Valid OauthToken

Throws:

OauthClientException

createOAuthClientToken

OauthToken createOAuthClientToken(Collection<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, BeesClient should be called with OAuth client ID and secret.

Returns:

never null. In case of a problem, an exception will be thrown.

Throws:

OauthClientException

See Also:

Wiki

createOAuthClientToken

OauthToken createOAuthClientToken(String... scopes)
                                  throws OauthClientException

Overloaded version of createOAuthClientToken(Collection)

Throws:

OauthClientException

createOAuthClientToken

OauthToken createOAuthClientToken(TokenRequest tokenRequest)
                                  throws OauthClientException

Overloaded version of createOAuthClientToken(Collection)

Throws:

OauthClientException