OAuthService

Overview

The OAuthService object provides a robust interface for managing OAuth authentication and handling authorized requests. It allows developers to create, configure, and execute HTTP requests such as GET, POST, PUT, and DELETE, ensuring secure access to resources. Developers can also retrieve and manage tokens for maintaining session continuity with the OAuth provider.

With methods like createGetRequest() and executeRequest(), the service supports constructing and executing customized requests. Token management is facilitated through methods like getAccessToken(), refreshToken(), and revokeToken(), which ensure proper handling of authentication tokens. The service also includes utilities for token expiration checks and obtaining OpenID tokens where supported.

The OAuthService integrates seamlessly with OAuth flows, enabling developers to work efficiently with access and refresh tokens, authorization URLs, and custom request configurations. For additional details about the OAuth authentication, refer to the Authentication section of this documentation.

Methods Summarized

Type	Name	Summary
OAuthRequest	createDeleteRequest(resourceURL)	Create a DELETE request.
OAuthRequest	createGetRequest(resourceURL)	Create a GET request for a resource.
OAuthRequest	createPostRequest(resourceURL)	Create a POST request.
OAuthRequest	createPutRequest(resourceURL)	Create a PUT request.
OAuthRequest	createRequest(requestType, resourceURL)	Creates a JSOAuthRequest for with the enum of RequestType (GET, PUT, DELETE, etc) for a resource url.
OAuthResponse	executeGetRequest(resourceURL)	This is quick method by executing a GET request and returning right away the OAuthResponse So it would be the same as executeRequest(createRequest(RequestType.
OAuthResponse	executeRequest(request)	Method to execute requests that are made, and configured by #createRequest(Verb,String)
Number	getAccessExpiresIn()	Returns the number of seconds left until the access token expires.
String	getAccessToken()	Get the access token currently set on the service.
Number	getAccessTokenLifetime()	Return the token lifetime in seconds.
String	getAuthorizationURL()
String	getAuthorizationURL(params)	Get the authorization url with some additional parameters.
String	getIdToken()	Obtain the Openid token if it is available.
String	getRefreshToken()	Return the refresh token.
Boolean	isAccessTokenExpired()	Checks if the access token is expired.
String	refreshToken()	Obtains a new access token if the OAuth api supports it.
String	refreshToken(refreshToken, scope)	Obtains a new access token based on the refresh token, if the OAuth api supports it.
void	revokeToken(token)	Revoke the provided access token.
void	setAccessToken(code)	Configure the oauth service with an access token using the scope that was initially set when creating the service.
void	setAccessToken(code, scope)	Configure the oauth service with an access token for the specified scope.

Methods Detailed

createDeleteRequest(resourceURL)

Create a DELETE request.

Parameters

• String resourceURL the url of the resource to be deleted

Returns: OAuthRequest the request object

Sample

var putRequest = service.createDeleteRequest("https://graph.microsoft.com/v1.0/me/drive/root:/FolderAA/FileBB.txt:/content");
var response = putRequest.execute();
if (response.getCode() == 204) {
		application.output("File was deleted "+response.getBody());
	}
else
{
		application.output('http status '+response.getCode());
		application.output("File could not be deleted: "+response.getBody())
}

createGetRequest(resourceURL)

Create a GET request for a resource.

Parameters

• String resourceURL the url of the resource which you want to get

Returns: OAuthRequest the request object

Sample

var getRequest = service.createGetRequest("https://api.linkedin.com/v2/me");
getRequest.addHeader("Accept", "application/json");

var response = getRequest.execute();
if (response.getCode() == 200) {
		var json = response.getAsJSON();
		application.output("Name is "+json.firstName);
	}
else
{
		application.output("ERROR http status "+response.getCode());
		application.output(response.getBody())
}

createPostRequest(resourceURL)

Create a POST request.

Parameters

• String resourceURL the url where the enclosed entity will be stored

Returns: OAuthRequest the request object

Sample

var postRequest = service.createPostRequest("https://.....");
postRequest.addHeader("Content-Type", "text/plain");
postRequest.addBodyParameter("param1", "value1");
var response = postRequest.execute();

createPutRequest(resourceURL)

Create a PUT request.

Parameters

• String resourceURL the url where the enclosed entity will be stored

Returns: OAuthRequest the request object

Sample

var putRequest = service.createPutRequest("https://graph.microsoft.com/v1.0/me/drive/root:/FolderAA/FileBB.txt:/content");
putRequest.addHeader("Content-Type", "text/plain");
putRequest.setPayload("ABC");
var response = putRequest.execute();
if (response.getCode() == 201) {
		application.output("New file was created "+response.getBody());
	}
else
{
		application.output("ERROR http status "+response.getCode());
		application.output("File could not be created: "+response.getBody())
}

createRequest(requestType, resourceURL)

Creates a JSOAuthRequest for with the enum of RequestType (GET, PUT, DELETE, etc) for a resource url.

Parameters

• enum requestType one of the types of plugins.oauth.RequestType

• String resourceURL the url of the resource you want to access

Returns: OAuthRequest a JSOAuthRequest object

Sample

var request = service.createRequest(plugins.oauth.RequestType.GET, "https://api.linkedin.com/v2/me");
request.addHeader("Accept", "application/json");

var response = request.execute();
if (response.getCode() == 200) {
		var json = response.getAsJSON();
		application.output("Name is "+json.firstName);
	}
else
{
		application.output("ERROR http status "+response.getCode());
		application.output(response.getBody())
}

executeGetRequest(resourceURL)

This is quick method by executing a GET request and returning right away the OAuthResponse So it would be the same as executeRequest(createRequest(RequestType.GET, url))

Parameters

• String resourceURL ;

Returns: OAuthResponse the OAuthResponse object

executeRequest(request)

Method to execute requests that are made, and configured by #createRequest(Verb,String)

Parameters

• OAuthRequest request the JSOAuthRequest object that was created by #createRequest(Verb,String)

Returns: OAuthResponse the OAuthResponse object

Sample

var request = service.createRequest(plugins.oauth.RequestType.GET, "https://api.linkedin.com/v2/me");
request.addHeader("Accept", "application/json");

var response = service.executeRequest(request);
if (response.getCode() == 200) {
		var json = response.getAsJSON();
		application.output("Name is "+json.firstName);
	}
else
{
		application.output("ERROR http status "+response.getCode());
		application.output(response.getBody())
}

getAccessExpiresIn()

Returns the number of seconds left until the access token expires.

Returns: Number seconds left untol the access token expires.

Sample

var seconds = service.getAccessExpiresIn();
 if (seconds < 60)
 {
 	application.output("The access token is going to expire in less than 1 minute! Use service.refreshToken() to get a new one");
 }
 else
 {
 	application.output("Make some requests");
 }

getAccessToken()

Get the access token currently set on the service.

Returns: String the access token or null if it was not set

getAccessTokenLifetime()

Return the token lifetime in seconds.

Returns: Number the token lifetime as it was retrieved by the OAuth provider with the access token

getAuthorizationURL()

Returns: String

getAuthorizationURL(params)

Get the authorization url with some additional parameters.

Parameters

• Object params a json containing the parameters and their values e.g. {'param1': 'value1', 'param2': 'value2'}

Returns: String the authorization url with the provided parameters appended to the query string.

getIdToken()

Obtain the Openid token if it is available.

Returns: String the id token, or null if was not set on the service.

getRefreshToken()

Return the refresh token.

Returns: String the refresh token or null if it is not present

isAccessTokenExpired()

Checks if the access token is expired. Returns false if the access token expire information is not set.

Returns: Boolean true if the access token is expired, false otherwise

refreshToken()

Obtains a new access token if the OAuth api supports it.

Returns: String The new access token issued by the authorization server

Sample

accessToken = service.refreshToken();

refreshToken(refreshToken, scope)

Obtains a new access token based on the refresh token, if the OAuth api supports it.

Parameters

• String refreshToken the refresh token string

• String scope optional, if missing then the default scope configured on the service is used

Returns: String The new access token issued by the authorization server

Sample

accessToken = service.refreshToken(theRefreshToken, scope);

revokeToken(token)

Revoke the provided access token.

Parameters

• String token to revoke

Returns: void

setAccessToken(code)

Configure the oauth service with an access token using the scope that was initially set when creating the service.

Parameters

• String code the authorization code used to request and access token

Returns: void

setAccessToken(code, scope)

Configure the oauth service with an access token for the specified scope.

Parameters

• String code the authorization code used to request an access token

• String scope the scope for which to obtain an access token

Returns: void

---