NEW RELEASE - Universal Cloud REST API Schema v2.1 - Cookie Support

[ChrisCollinsIBM]

Universal Cloud REST API Schema v2.1 - Cookie Support

New Schema Namespace Value

To use any of the new tags please update your namespace to the v2.1 namespace URL of http://qradar.ibm.com/UniversalCloudRESTAPI/Workflow/V2_1

You will also need to install PROTOCOL-UniversalCloudRESTAPI-7.5-20240812075740.noarch.rpm or later from Autoupdate or FixCentral to use the new v2.1 features.

Cookie Support - Overview

Cookies can be utilized in API interactions in two ways, Response Cookies and Request Cookies.

A common use case is to get some type of auth token or sessionID returned in an API response in a cookie after hitting an authentication endpoint of some type (a response cookie). This value must be read from the response cookie and often attached in a request cookie in subsequent <CallEndpoint> actions (a request cookie).

Cookie Support - Response Cookies

This CURL debug example below shows an HTTP response with a response cookie for a cookie named JSESSIONID

< HTTP/1.1 302
< Strict-Transport-Security: max-age=31536000;includeSubDomains
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< Cache-Control: no-cache, no-store, must-revalidate
< Set-Cookie: JSESSIONID=227AD3172D3EA36ACA2BBB19EBA98D83; Max-Age=28800; Expires=Tue, 03 Sep 2024 23:34:46 GMT; Path=/; Secure; HttpOnly; SameSite=Lax
< Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Mon, 02-Sep-2024 15:34:46 GMT; SameSite=lax
< Location: /login.html?error
< Content-Length: 0
< Date: Tue, 03 Sep 2024 15:34:46 GMT

Cookies are handled different than HTTP headers and thus wouldn't have previously appeared in the /savePath/headers of the <CallEndpoint> response header map. A new path of savePath/cookies will now contain a map of the response cookies indexed by name.

Cookie values are encrypted when logged, but here's an example <CallEndpoint> JSON response with the cookies and headers.

{
   "status_code":200,
   "status_message":"OK",
   "headers":{
      "cache-control":"no-cache, no-store, must-revalidate",
      "strict-transport-security":"max-age=31536000;includeSubDomains",
      "x-frame-options":"DENY",
      "x-content-type-options":"nosniff",
      "accept-ranges":"bytes",
      "etag":"W/\"1972-1721901378000\"",
      "last-modified":"Thu, 25 Jul 2024 09:56:18 GMT",
      "vary":"accept-encoding",
      "content-type":"text/html",
      "transfer-encoding":"chunked",
      "date":"Tue, 03 Sep 2024 16:21:09 GMT",
      "keep-alive":"timeout=60",
      "connection":"keep-alive"
   },
   "body":"<*removed*>",
   "cookies":{
      "JSESSIONID":{
         "value":"🔐➡AQAAAAAAAAABUuq01zs3hUG7U3BGy9l3xAa3DtihKRSVRvLV9VmHLx19kzP5UIti27xbt/OiDQzyxIo9WWK7wEkn1kfq/Xg=⬅🔐",
         "name":"JSESSIONID",
         "path":"/",
         "domain":"test.example.net",
         "expiryDate":"Wed Sep 04 00:15:22 UTC 2024"
      }
   }
}

So to access the value of JSESSIONID above you would use ${savePath/cookies/JSESSIONID/value} and the return value would be the unencrypted value which you could log to debug during development.

Cookie Support - Request Cookies

Referring back to the response cookie example above, any further requests to this API above will need the JSESSIONID cookie attached to the request to carry the authenticated session through.

The v2.1 schema brings a new attribute to <CallEndpoint> called <RequestCookie> and is outlined [here]

Example usage:

    <CallEndpoint url="https://${/hostname}/example" method="POST" savePath="/response">
        <RequestHeader name="Content-Type" value="application/json" />
        <RequestCookie name="JSESSIONID" value="${/response/cookies/JSESSIONID/value}" secret="true"/>
    </CallEndpoint>

In this example we pulled the JSESSIONID cookie from the previous response, but it could come from anywhere in the JSON state. We're also flagging it as secret here to ensure it isn't logged anywhere unencrypted since we know it's auth related but this flag is optional.

There are domain and path values you can manually set on the <RequestCookie> as well if needed, but those are set to the hostname and path of the <CallEndpont> fields by default to ensure they are attached to the request and do not usually need to be set explicitly.

[ashishkumarc4u]

Getting Error when I'm trying to configure workflow xml v2.1 to use requestCoockies sub-element as part of callEndpoint action.

[ChrisCollinsIBM]

Hello @ashishkumarc4u.

It's not XML version 2.1, rather the namespace URL should be set to http://qradar.ibm.com/UniversalCloudRESTAPI/Workflow/V2_1 instead of http://qradar.ibm.com/UniversalCloudRESTAPI/Workflow/V1 or http://qradar.ibm.com/UniversalCloudRESTAPI/Workflow/V2

[ashishkumarc4u]

I'm trying below xml syntax.

But when I'm trying to save the log source it's giving below error.

The 'workflowParameterValues' parameter is not valid.
Reason:
Unsupported version: %s V1. Provide valid version.

FYI, Protocol version is latest "PROTOCOL-UniversalCloudRESTAPI-7.5-20250423073031.noarch"

[ChrisCollinsIBM]

Moved to issue #289 (comment) to discuss