JSSP Authentication

The JSSP supports two authentication modes: OAuth and Basic authentication. You can call APIs that do not require authentication by setting the WithCredentials property of the XHR object to false, or simply leaving it out of your code. To use OAuth or Basic authentication, set the withCredentials property of the XHR object to true.

Using Basic Authentication

To set the format of your authorization header, use the Authorization Header Format service key. If you want to use Basic Authentication, set the Authorization Header Format service key to Basic {0}:{1} to pass in the username and password. If you configure the Service Instance with Static credentials and entered the username and password, use the same approach of setting the Authorization Header Format service key to Basic {0}:{1} and then, in your code, set the XMLHTTPRequest object's withCredentials property to true.

1
2
3
4
5
6
7
8
//set up the XML HTTP Request
var xhr = new XMLHttpRequest();

//Use the Service Instance's Basic (Static) username + password configuration
xhr.withCredentials = true;

//send the xhr request
xhr.send();

Using OAuth Authentication

You can use OAuth Authentication in two ways: by passing in an Access Token, or by configuring an OAuth Resource and using that resource on the Service Instance.

OAuth by passing in an access token

To pass in an Access Token, you would typically define a parameter for your service object method and then read the parameter value at runtime by querying the collection of parameters that are set when the SmartObject is executed.

1
2
3
4
5
6
7
8
9
10
11
12
//set up the XML HTTP Request
var xhr = new XMLHttpRequest();

//use .setRequestHeader to set the Authentication header with an Access Token. Do not set .withCredentials
//The access token is passed through as a parameter defined for the service object method
//in this example the parameter is called accessToken
xhr.setRequestHeader("Authorization", "Bearer " + encodeURIComponent(parameters["accessToken"]));

//..TODO: set up the rest of the xhr object

//send the xhr request
xhr.send();

OAuth with a configured resource for the service instance

If you want to use resource-based OAuth, you'll need to set up an OAuth resource type and resource and then configure the Service Instance to use these resources. For more information about doing this, see the OAuth topic in the product documentation and KB001702: Configuring a Service Instance to use a Custom OAuth Resource.

To set the format of your authorization header/OAuth token, use the Authorization Header Format service key. By default the Authorization Header Format is set to Bearer {0}, where {0} is the format specifier where the token will be added, and Authorization Header Name is used to override which header is used for authentication.

1
2
3
4
5
6
7
8
9
10
//set up the XML HTTP Request
var xhr = new XMLHttpRequest();

//Set .withCredentials to use the service instance's configured OAuth (Bearer) Resource
xhr.withCredentials = true;

//..TODO: set up the rest of the xhr object

//send the xhr request
xhr.send();

Considerations

• When you need to use a SmartObject method in a workflow and you've set withCredentials to true on the XHR object, you'll need to cache a token for the K2 service account. This is necessary because events in workflows execute under the service account because there is no user context in a workflow server event. To do this, check the Cache OAuth token for K2 service account for using SmartObjects in workflow steps option when creating the Service Instance.