Using the TA REST API
There are many ways to invoke the RESTful services available from Tidal Automation.
Changes to the API Query Grammar
The query conditions and group clauses are supported as part of the revised API grammar.
Conditions:
-
NOT LIKE
-
NOT IN
-
NOT NULL
Group Clauses:
-
<cond1> AND <cond2> AND ...
-
<cond3> OR <cond4> OR ...
-
(<cond1> AND <cond2>) OR <cond3>
-
(<cond1> OR <cond2) AND (<cond3> OR <cond4>)
Multiple levels of AND and OR group clauses and conditions are supported.
This table provides the list of query conditions that TA supports.
| Query |
Examples |
Result |
|---|---|---|
|
Conditions |
||
|
‘FIELD_NAME’=’STRING’ |
name=”John” |
Returns the rows with name as “John”. |
|
‘FIELD_NAME’ LIKE ‘STRING’ |
name LIKE ‘JP*Alpha*Beta’ |
Returns all matches where the ‘name’ property has a pattern ‘JP*Alpha*Beta’, where '*' is zero or more characters. |
|
‘FIELD_NAME’ NOT LIKE ‘STRING’ |
name NOT LIKE '%d' |
Returns the rows in which ‘name’ does not end with ‘%d’. |
|
‘FIELD_NAME’ IS NULL |
Address IS NULL |
Returns the rows that have a null value in ‘Address’ field. |
|
‘FILED_NAME’ IS NOT NULL |
Lastname IS NOT NULL |
Returns the rows that have ‘Lastname’. |
|
‘FIELD_NAME’ IN (value1, value2, ...) |
Branches IN (‘USA’, ‘Philippines’, ‘Norway’) |
Returns the rows with ‘Branches’ in USA, Philippines, and Norway. |
|
‘FIELD_NAME’ NOT IN (value1, value2,...) |
Customers NOT IN (‘USA’, ‘Philippines’, ‘Norway’) |
Returns the rows of ‘Customers’ not residing in USA, Philippines, and Norway. |
|
('PRODDATE' | 'RUNDATE') ('=' | '<' | '<=' | '>' | '>='| '<>' | '!=') date |
“RUNDATE = ‘20201225’ AND STARTSWITH (name, ‘JP’) “PRODDATE = ‘20201225’ AND STARTSWITH (name, ‘JP’) |
Returns the rows where the ‘rundate’ property is Dec. 25, 2020 and the ‘name’ property begins with ‘JP’. Returns the rows where the ‘proddate’ property is Dec. 25, 2020 and the ‘name’ property begins with ‘JP’. |
|
(‘UPPER’ | ‘LOWER’) (field_name) |
UPPER (name) LOWER (name) |
Returns the ‘name’ in uppercase. Returns the ‘name’ in lowercase. |
|
BETWEEN (‘FIELD_NAME’, value1, value2) |
BETWEEN(productiondate, ‘20201225’, ‘20201231’) |
Returns the rows where the ‘productiondate’ falls between ‘20201225’ and ‘20201231’. |
|
CONTAINS ('FIELD_NAME ', 'STRING') |
CONTAINS (‘name’, ‘au’) |
Returns the rows where the name contains the string ‘au’. |
|
Group Clauses |
||
|
(<cond1> AND <cond2> AND ...) |
RUNDATE = ‘20201225’ AND STARTSWITH(name, ‘JP’) |
Returns the rows with ‘rundate’ as ‘Dec. 25, 2020’ and the ‘name’ that begins with ‘JP’. |
|
<cond1> OR <cond2> OR ... |
RUNDATE = ‘20201225’ OR STARTSWITH(name, ‘JP’) |
Returns the rows either with the ‘rundate’ as‘Dec. 25, 2020’ or with the ‘name’ that begins with ‘JP’. |
|
(<cond1> AND <cond2>) OR <cond3> |
(STARTSWITH(name, ‘JP’) AND ENDSWITH(name, ‘KQ’)) OR RUNDATE=”20201225” |
Returns the rows with the name that starts with ‘JP’ and ends with ‘KQ’ or with the ‘rundate’ as ‘Dec. 25, 2020’. |
|
(<cond1> OR <cond2) AND (<cond3> OR <cond4>)
|
(STARTSWITH(name, ‘JP’) OR ENDSWITH(name, ‘KQ’)) AND (RUNDATE=”20201225” OR RUNDATE=”20201231”) |
Returns the rows with the name that either starts with ‘JP’ or ends with ‘KQ’ and with the ‘rundate’ as ‘Dec. 25, 2020’. |
Search results of the fields with null value and the fields with an empty string value are not the same.
Example: <field> IS NULL – Returns the records of fields with null value.
Example: <field>='' – Returns the records of fields with an empty string value.
REST API from a Browser
Before writing code to invoke the REST API, you can browse the services available via a browser. Clicking the links issues a "GET" request to the API. A "POST" request to the API can also be issued from the browser by using the "Manual Commands (Post)" link.
REST API Security Notes
The calls to the REST API are subject to the same security restrictions as the same user accessing Tidal Automation UI. In Code Example 1 below, a call is issued to get all of the available jobs. The list of available jobs returned is determined by the user name used in the API call.
Java Client REST API Examples
GET Request
The Java client issues a GET request to the REST API. This is the equivalent of clicking on the ApiObject link as described in the REST API From Browser section. This example retrieves all of the jobs currently defined in the Tidal Automation environment. The username and password pair is Base64 encoded and passed to the server as the "Authorization" property.
An XML document containing a list of jobs is returned from this call.
public static void postRequest() throws Exception
{URL url = new URL("http://www.companyscheduler.com:8080/api/tes-6.5/post"); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("GET");conn.setDoInput(true); conn.setDoOutput(true);
String userNamePassword = "myusername:mypassword"; userNamePassword =
new String(org.apache.commons.codec.binary.Base64.encodeBase64(userNamePassword
.getBytes())); conn.setRequestProperty("Authorization", userNamePassword);conn.connect();
BufferedReader reader = new BufferedReader(new InputStreamReader( conn.getInputStream()));
String resp = ""; String next = null;
while ((next = reader.readLine()) != null) resp += next;
System.out.println(resp);
}
POST Request
It shows a POST request issued to the TA REST API. The URL for issuing a POST request is always the same: http://<hostname>:<port>/api/<DSP Name>/ post.
In the post request, the execution command is sent in a URL encoded string. In this particular example, a POST request is sent to insert a job into the schedule. The <id> is the id of the job. Other parameters include <startdate> - the requested runtime for the job; <vars> - local job variable overrides; <params> - local job parameter overrides; and <deps> - the Y/N value for whether or not to override the job's dependencies.
An XML document acknowledging the job insert is returned.
public static void postRequest() throws Exception
{URL url = new URL("http://www.companyscheduler.com:8080/api/tes-6.5/post"); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("POST");conn.setDoInput(true); conn.setDoOutput(true);
conn.setRequestProperty("Content-Type","application/x-www-form-urlencoded"); String userNamePassword = "myusername:mypassword";userNamePassword =
new String(org.apache.commons.codec.binary.Base64.encodeBase64(userNamePassword
.getBytes())); conn.setRequestProperty("Authorization", userNamePassword);String postCommand = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\" ?>"
+ "<atom:entry xmlns:atom=\"http://purl.org/atom/ns#\">"
+ "<atom:id>1</atom:id><atom:title>api</atom:title>"
+ "<Job.insert>"
+ "<id>2</id>"
+ "<startdate>20110812</startdate>"
+ "<vars></vars>"
+ "<params></params>"
+ "<deps>N</deps>"
+ "</Job.insert>"
+ "</atom:entry>";
String payload = "data="+ java.net.URLEncoder.encode(postCommand, "ISO-8859-1");
conn.setRequestProperty("Content-Length", Integer.toString(payload.getBytes().length)); conn.setFixedLengthStreamingMode(payload.getBytes().length);DataOutputStream out = new DataOutputStream(conn.getOutputStream()); out.writeBytes(payload);
out.flush();
BufferedReader reader = new BufferedReader(new InputStreamReader( conn.getInputStream()));
String resp = ""; String next = null;
while ((next = reader.readLine()) != null) resp += next;
System.out.println(resp);
}
Session Management Using the Session Cookie
In both previous code examples, the calls establish new sessions on the server. For typical applications that make repeated calls to the REST API, the best practice is to reuse the established sessions so that the server does not create excessive number of active sessions, which eventually could cause it to run out of memory.
The Session Management Using the Session Cookie example is an extension of GET Request example showing the usages of a cookie for session management.
public static void tesGetRequestWithSession() throws Exception
{String sessionID = null;
for (int i=0; i<10; i++)
{URL url = new URL(
"http://www.mycompanyscheduler.com:8080/api/tes-6.5/Job.getList");
HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("GET");conn.setDoInput(true); conn.setDoOutput(true);
if (sessionID == null)
{String userNamePassword = " myusername:mypassword "; userNamePassword =
new String(org.apache.commons.codec.binary.Base64.encodeBase64(userNamePassword
.getBytes())); conn.setRequestProperty("Authorization", userNamePassword);}
else
{conn.setRequestProperty("Cookie", sessionID);}
conn.connect();
BufferedReader reader = new BufferedReader(new InputStreamReader( conn.getInputStream()));
String resp = ""; String next = null;
while ((next = reader.readLine()) != null) resp += next;
System.out.println(resp);
//extract cookie
String setCookies = conn.getHeaderField("Set-Cookie");if (setCookies != null && sessionID == null)
{String cookies[] = setCookies.split(";");if (cookies.length > 0) sessionID = cookies[0];
}
}
}
Note: After making all calls for this session, users can log out of the session by calling http://localhost:8080/api/production/Users.logoutSession. If users do not make the call to logout this session, the session will expire after a period (Default: 30 minutes) of inactivity.
Execute a Query with Conditions
In GET Request example, a GET request was issued to get a list of all jobs. The GET request can accept additional parameters such that the list of jobs returned can be filtered further.
If one needs to get a list of jobs that match a specific name pattern, the GET request URL can be constructed as follows:
Example: URL url = new URL("http://www.mycompanyscheduler.com:8080/api/tes-6.5/Job.getList?query=Job.name LIKE '*name*'")
In this case a where clause (Job.name LIKE '*name*') is sent. The where clause must be URL encoded. Similarly, other queries using other field names in the Job object can be constructed.
The same also be achieved using a POST request. The POST payload is below. In addition to the queryCondition, using the POST one could also specify columns needed.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://purl.org/atom/ns#">
<atom:id>1</atom:id>
<atom:title>api</atom:title>
<Job.getList>
<selectColumns> id,ownerid,parentid,parentname,runtimeusername
</selectColumns>
<queryCondition>
Job.name LIKE '*name*'
</queryCondition>
</Job.getList>
</atom:entry>
If one needs to get a list of job runs that match a specific date pattern, then GET request URL can be constructed as follows:
Example: URL url = new URL(http://www.mycompanyscheduler.com:8080/api/tes-6.5/JobRun.getList?query= productiondate = '20201225')
Other supported Date Formats:
-
yyyy-MM-dd HH:mm:ss
-
yyyyMMddHHmmss
-
yyyyMMdd
The POST payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://purl.org/atom/ns#">
<atom:id>1</atom:id>
<atom:title>api</atom:title>
<JobRun.getList>
<selectColumns> id,ownerid,parentid,parentname,runtimeusername
</selectColumns>
<queryCondition> PRODDATE = '20201225'
</queryCondition>
</JobRun.getList>
</atom:entry>
If one needs to get a list of jobs running between two dates, then GET request URL can be constructed as follows:
Example: URL url = new URL("http://www.mycompanyscheduler.com:8080/api/tes-6.5/JobRun.getList?query= BETWEEN( productiondate, '20201225', '20201231' )")
The POST payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://purl.org/atom/ns#">
<atom:id>1</atom:id>
<atom:title>api</atom:title>
<JobRun.getList>
<selectColumns> id,ownerid,parentid,parentname,runtimeusername
</selectColumns>
<queryCondition>
BETWEEN( productiondate, '20201225', '20201231')
</queryCondition>
</JobRun.getList>
</atom:entry>
If one needs to get a list of job runs that match a specific date and a string begins with, then GET request URL can be constructed as follows:
Example: URL url = new URL("http://www.mycompanyscheduler.com:8080/api/tes-6.5/JobRun.getList?query= RUNDATE = '20201225' AND STARTSWITH( name, 'JP')")
The POST payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://purl.org/atom/ns#">
<atom:id>1</atom:id>
<atom:title>api</atom:title>
<JobRun.getList>
<selectColumns> id,ownerid,parentid,parentname,runtimeusername
</selectColumns>
<queryCondition>
RUNDATE = '20201225' AND STARTSWITH( name, 'JP')
</queryCondition>
</JobRun.getList>
</atom:entry>
ClientManager API Token-based Authentication
The token-based ClientManager API allows an API client to authenticate the Client Manager API using the token provided.
Token Object API
Token objects can be managed using standard REST API, as described in the standard API documentation page /apidoc/<plugin-in>/method/Token. For more information, see Accessing Documentation for REST API Objects and Methods.
These endpoints have been deprecated:
-
http://<clientmgr-host>:<clientmgr-port>/api/authorize
-
http://<clientmgr-host>:<clientmgr-port>/api/revoke
To manage tokens through the API:
-
An API client issues a POST request with the token.create method to specify the properties for the token by passing them in the Token object of the REST call body.
Example: curl -s -v POST http://localhost:8080/api/production/postbody -H 'Content-Type: application/xml' -d @token.create.xml -u tes
Where token.create.xml file is a file containing a subset of the Token object properties, similar to this:
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Token.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<object>
<tes:token xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:name>curl borne</tes:name>
<tes:description>Created by curl</tes:description>
<tes:userid>9</tes:userid>
<tes:ownerid>9</tes:ownerid>
<tes:expiredtime>2020-10-25T16:00:00-0000</tes:expiredtime>
<tes:timetolive>900</tes:timetolive> <!-- -1, no expiration -->
<tes:remainlogincount>10</tes:remainlogincount> <!-- -1, unlimited -->
<tes:maxapicall>3</tes:maxapicall> <!-- -1, unlimited -->
<tes:maxconcurrentlogin>2</tes:maxconcurrentlogin> <!-- -1, unlimited -->
<tes:autorefresh>Y</tes:autorefresh>
<tes:autodelete>Y</tes:autodelete>
<tes:active>Y</tes:active>
<tes:publicflag>Y</tes:publicflag>
</tes:token>
</object>
</tes:Token.create>
</entry>
The API includes a Token object in its response that contains the token ID in the object’s id field as shown in this. You can use this ID to generate the token.
<entry>
<id>0</id>
<title>Token has beeen created.</title>
<source>com.tidalsoft.framework.rpc.Result</source>
<tes:result><tes:message>Token has been created.</tes:message>
<tes:objectid>5</tes:objectid>
<tes:id>123</tes:id>
<tes:operation>CREATE</tes:operation>
<tes:ok>true</tes:ok>
<tes:objectname>Token</tes:objectname>
</tes:result>
</entry>
Note: You can omit this step if you want to re-use a previously created Token record.
-
The API client requests a token by calling the token.generateToken endpoint, similar to this:
Example: curl -s -v POST http://localhost:8080/api/production/postbody -H 'Content-Type: application/xml' -d @token.generate.xml -u tes
Where token.generate.xml file is a file containing a subset of the Token object properties, similar to this:
<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Token.generateToken xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:id>123</tes:id>
</tes:Token.generateToken>
</entry>
The API sends the token in the tokenstring field of the Token object in the response:
<tes:token xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:tokenstring>eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInVzclwiOlwidGFcIn0iLCJpYXQiOjE2MDMyMzE2MjksImV4cCI6MTYwMzY0MTU5OX0.9F3McadnooMc5eEY_
fAgArNvprbD6UqL00bd kTWO1fTaQhRqajgkFcXk30YKUlZ7g_
XN2LY3WukLyVbb7lif0w</tes:tokenstring>
<tes:id>345</tes:id>
<tes:generatetime>2020-10-20T17:07:09-0500</tes:generatetime>
<tes:expiredtime>2020-10-25T11:00:00-0500</tes:expiredtime>
</tes:token>
-
The client extracts the token string and uses it to authenticate subsequent API calls.
Authentication
To use a previously authorized token in an API call, specify the token in the HTTP Authorization header as follows:
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcImRvbVwiOlwiZGlsbG9ua2FuZVwiLFwidXNyXCI6XCJqdW5taW5wXCJ9IiwiaWF0IjoxNjAyNTIwNTkyLCJleHAiOjE2MDI1MjExOTJ9.Rxk2MpQ1QVgt8VqoreMVbaUMxN2oRBwZ X7nKDloQimFyJ9oLtFIZgcmRuAkdasPIUWstvWSrQycIhzdOpRmUzQ
This illustrates using curl command:
Example: curl -s -v -H 'Authorization: BearereyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcImRvbVwiOlwiZGlsbG9ua2FuZVwiLFwidXNyXCI6XCJqdW5taW5wXCJ9IiwiaWF0IjoxNjAyNTIwNTkyLCJleHAiOjE2MDI1MjExOTJ9.Rxk2MpQ1QVgt8VqoreMVbaUMxN 2oRBwZX7nKDloQimFyJ9oLtFIZgcmRuAkdasPIUWstvWSrQycIhzdOpRmUzQ' http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
The Client Manager sends a response containing the session cookies:
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5; HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: text/xml;charset=utf-8
< Set-Cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6 XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsIml hdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ; HttpOnly
< Transfer-Encoding: chunked
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><entry xmlns="http://purl.org/atom/ns#"><id>0</id><title>Y</title><source>com.tidalsoft.framework.rpc.Result</ source><tes:result xmlns:tes="http://www.tidalsoftware.com/client/tesservlet"><tes:message>Y</tes:message><tes:objectid>1<
/tes:objectid><tes:id>0</tes:id><tes:operation>checkMasterConnectionStatus</tes:operation><tes:ok>true<
/tes:ok></tes:result></entry>* Connection #0 to host localhost left intact
Note: If an improper token, such as a token that has already expired or been revoked, leads to an “401 Unauthorized” error as response.
Client Manager Authentication Settings
The Client Manager receives the token through an API call, it automatically authenticates the token against a directory service, such as LDAP or Active Directory. To enable this lookup, the Client Manager administrator must configure the properties in its clientmgr.props file.
If Security.Authentication=ActiveDirectory:
|
Property Name |
Description |
|
|---|---|---|
|
ActiveDirectory.AuthenticationMethod |
The authentication method required to connect to the directory to do a directory lookup. Set to none if the directory can be looked up anonymously. Set to simple if the user and password are required to connect to the directory to do a directory lookup. |
simple |
|
ActiveDirectory.BindUser |
User with the privilege to search the global directory. If the AuthenticationMethod is not none, you must specify a user. |
|
|
ActiveDirectory.BindPassword |
BindUser’s password. Execute this command to set or change the ActiveDirectory.BindPassword in clientmgr.props for single-domain user authentication for Client Manager. Windows: Example: TIDAL\ClientManager\script\cm.cmd setbindpwd Unix: Example: /opt/TIDAL/ClientManager/bin/cm setbindpwd Note: The user-auth.xml is displayed in clientmgr.props for multi-domain user authentication for Client Manager. user-auth.xml includes all AD/LDAP servers for TA user authentication. For more information, see the Enabling Multi-Domain Authentication section in the Installing Client Manager for Windows chapter of the TA Installation Guide. |
|
If Security.Authentication=LDAP:
|
Property Name |
Description |
|
|---|---|---|
|
LDAP.AuthenticationMethod |
The authentication method required to connect to the directory to do a directory lookup. Set to none if the directory can be looked up anonymously. Set to simple if the user and password are required to connect to the directory to do a directory lookup. |
simple |
|
LDAP.BindUser |
User with the privilege to search the global directory. If the AuthenticationMethod is not none, you must specify a user. |
|
|
LDAP.BindPassword |
BindUser’s password. Execute the command to set or change the LDAP.BindPassword in clientmgr.props for single-domain user authentication for Client Manager. Windows: Example: TIDAL\ClientManager\script\cm.cmd setbindpwd Unix: Example: /opt/TIDAL/ClientManager/bin/cm setbindpwd Note: The user-auth.xml is displayed in clientmgr.props for multiple-domain user authentication for Client Manager. user-auth.xml includes all AD/LDAP servers for TA user authentication. For more information, see Enabling Multi-Domain Authentication section in the Installing Client Manager for Windows chapter of the TA Installation Guide. |
|
Session Tokens
Session tokens enable the Client Manager to secure user sessions from unauthorized access, such as cross-site or spoofing. Tokens allows the Client Manager to exchange client info with its clients, and only grant access to those meet the criteria.
A Tidal administrator can configure the Client Manager to generate session tokens and send them, along with session ID, as cookies in the HTTP response. The client is then required to send the session token and ID back in subsequent requests in order to connect to the same session. An administrator can elect to verify the origin of the request, such as user agent and remote host, in addition to the request user. Also, an administrator can specify whether session tokens should expire after a certain period of time and whether the token can be refreshed.
Session Token Configuration Properties
You can manage session token authentication settings for a Client Manager by configuring the properties in the Client Manager clientmgr.props file. You must restart the Client Manager for the changes to take effect.
These settings have been deprecated in Tidal Automation
-
API.Auth.Token.ValidUntil
-
API.Auth.Token.Secret
|
Property Name |
Description |
Default |
|---|---|---|
|
Auth.BASIC |
Specifies whether to enable or disable HTTP Basic authentication. Values are: ON
OFF
Upon success, client receives session ID and session token in response. Client then accesses protected web contexts, such as /client, /info and /apidoc, by using the session ID and session token to connect back to existing session. Note: API requests using API Token Authentication are not affected by this property and will continue to work either way. Note: For API requests using the traditional HTTP Basic authentication scheme, see the property Auth.API.CompatMode. |
OFF |
|
Auth.API.CompatMode |
When Auth.BASIC=OFF, API requests will be allowed to use HTTP Basic authentication scheme, if this property is set to Y. |
Y |
|
Auth.Token.Enabled |
Whether to enable session token generation and validation.
Generates session tokens for all Web Client and API requests regardless of the setting of Auth.Token.Enabled. Validates session tokens for Web Client requests. Validates session tokens for API requests that include them, but does not reject requests with no session tokens.
|
Y |
|
These parameters are valid only when the Auth.Token.Enabled=Y |
||
|
Auth.Token.TTL |
Duration (time to live) of the session token. Valid values include:
When a session token expires, a new session token will be generated with the same TTL, if automatic token refreshing is enabled. Otherwise, the request will be rejected. By default, the Auth.Token.AutoRefresh property controls request permissions. However, if the session originated from a request authenticated by an API token, the value of the API token’s autorefresh property (<tes:autorefresh>) takes precedence over the Client Manager setting. |
10m |
|
Auth.Token.Secret |
Base64-encoded secret key for signing session tokens. Note: For higher security, Tidal recommends using at least a 128 byte array. The Client Manager generates a key internally if this property is not set. For more information about generating a base64 hash, consult the Linux shellbase64 command or java.util.Base64.Encoder documentation. |
None |
|
Auth.Token.AutoRefresh |
Whether to refresh the session token automatically when it expires (Y/N). |
Y |
|
Auth.Token.VerifyUserAgent |
Whether to verify the user-agent from which the HTTP request came against the token (Y/N). |
N |
|
Auth.Token.VerifyRemoteHost |
Whether to verify the remote host from which the HTTP request came against the token (Y/N). |
N |
Client Manager Session Token Authentication
When session tokens are enabled in the Client Manager configuration (Auth.Token.Enabled=Y), basic and API-token authentication are impacted.
To authenticate using basic authentication (username and password), you can enter a curl command similar to:
Example: curl -s -v -u <username>:<password> http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus
The Client Manager sends a response containing the session cookies:
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5; HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: text/xml;charset=utf-8
< Set-Cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6 XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsIml hdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ; HttpOnly
< Transfer-Encoding: chunked
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><entry xmlns="http://purl.org/atom/ns#"><id>0</id><title>Y</title><source>com.tidalsoft.framework.rpc.Result</ source><tes:result xmlns:tes="http://www.tidalsoftware.com/client/tesservlet"><tes:message>Y</tes:message><tes:objectid>1<
/tes:objectid><tes:id>0</tes:id><tes:operation>checkMasterConnectionStatus</tes:operation><tes:ok>true<
/tes:ok></tes:result></entry>* Connection #0 to host localhost left intact
You need to provide the CSTSED and Session-Token cookies in all future requests, similar to:
curl -s -v http://localhost:8080/api/production/MasterNode.checkMasterConnectionStatus -H "cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5" -H "cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsIml hdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ"
All subsequent responses contain the cookies you must provide in the next request.
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node015x2z5kt91n8av8cgkl7zeh6v5; HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: text/xml;charset=utf-8
< Set-Cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6 XCIwOjA6MDowOjA6MDowOjFcIixcInVzZXJcIjpcInZpbmNlbnRsXCIsXCJ1c2VyLWFnZW50XCI6XCJjdXJsLzcuNTUuMVwifSIsIml hdCI6MTYwMzMwNjk5MCwiZXhwIjoxNjAzMzA3MjkwfQ.E-VU4mOWsMhLzOk92tlZidE92UWFCscYkoWSeDvJVFAYRp7HnXF-tpkSqt4 ypVm07lDrxTLl6I7Tx4o0FeyyGQ; HttpOnly
< Transfer-Encoding: chunked
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><entry xmlns="http://purl.org/atom/ns#"><id>0</id><title>Y</title><source>com.tidalsoft.framework.rpc.Result</ source><tes:result xmlns:tes="http://www.tidalsoftware.com/client/tesservlet"><tes:message>Y</tes:message><tes:objectid>1<
/tes:objectid><tes:id>0</tes:id><tes:operation>checkMasterConnectionStatus</tes:operation><tes:ok>true<
/tes:ok></tes:result></entry>* Connection #0 to host localhost left intact
These API endpoints are added in TA for a secure Client Authentication:
-
/auth/key – A request to the /auth/key/ API endpoint generates the base64 encoded key. The Client must use a new key each time the Client calls the /auth/authenticate API.
-
/auth/authenticate – This API endpoint is used for the Client Authentication using the key generated from /auth/key API request. On successful authentication, a Session ID and Session Token are generated, which can be used to access protected web contexts such as /client, /info, and /apidoc to connect back to existing session.
-
/auth/key
-
Not protected by HTTP Basic or Bearer authentication scheme.
-
Accepts only POST method calls. No content is required.
-
Returns a Base64 encoded key in response body.
Example: <base64 encoded key>.
Note: This key is for one-time use only; it expires in 10 minutes if not used.
Example using Curl:
$ curl -s -v -X POST http://localhost:8080/auth/key
< HTTP/1.1 200 OK
< Content-Type: application/base64; charset=ISO-8859-1
< Content-Length: 392
<
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxqYQ/bDMFDqHMxteELuidZdAVGIMiiWr4K2u6bsKzrLEYWcoS+pVysagrAkgxVRt7972H1RN4GQo87NItxzbKgVs+hA4xgXOQh1MSmNOZrTJwp5wPUL4QqSuYKmiYfF64nDf9fo8nbs9sQtmLPigx0e1v3pjPIGi5iKkpbr+gPLLuy/U9Ns7hzISNiO/dwwJPE6oRFX7/t9dAsbybZVR5Vcm63Bz2VmgS5+LllIfp99QsP8HSNOF7jcvH7g5/v5/5JlmIwPFAKQi1zc9eEXBf6y1Inn5sGkZ4/46lEbzQtQRezL/dMv9oI2LFq1lUyb0mfVrMrU1DbyoPkbwwuVnyQIDAQAB
-
-
/auth/authenticate
-
Not protected by HTTP Basic or Bearer authentication schemes.
-
Accepts only POST method calls.
-
Expects user credentials in the request body, in either of the formats:
Specify:
-
Content-Type: application/base64
-
Request body: <base64 encoded username:password>
Encode the entire string using the Base64 encoding scheme.
$ curl -s -v -X POST http://localhost:8080/auth/authenticate \-H "Content-Type: application/base64" -d dGVzOjIwMTksdGVzContent-Type: application/base64
Content-Length: 16
-
-
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node01i87g0ubymipsnrtbhkvd1a3w1; Path=/; HttpOnly
< Set-Cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob
3N0XCI6XCIxMjcuMC4wLjFcIixcImRvbWFpblwiOlwiXCIsXCJ1c2VyXCI6XCJ0ZXNcIixcInVzZXItYWdlbnRcIjpcImN1c
mwvNy41OC4wXCJ9IiwiaWF0IjoxNjEyNzk3NzY0LCJleHAiOjE2MTI3OTgzNjR9.xObnEX3MKEgZFzAntdX42fnsgNJVQrh7 urhjelZzZ8xMO8d7QuF6HxPMuT1FTYP3D1OdKvunSVKusYTSQUP0HA; Path=/; HttpOnly
< Content-Type: text/plain;charset=utf-8
< Content-Length: 14
<
authenticated!
Alternatively, specify:
Content-Type: application/x-www-form-urlencoded the parameters in request body: k=<URL encoded base64 encoded key> &c=<URL encoded credential> &l=<URL encoded location URL> where <URL encoded base64 encoded key> is a URL encoded string containing the Base64 encoded key obtained from a prior request to the /auth/key endpoint. This is a required parameter.
Note: The Client must use a new key each time calling the /auth/authenticate API.
-
<URL encoded credential> is a URL encoded string composed by the procedure. This is a required parameter.
-
Encrypt account password by RSA algorithm, RSA/ECB/PKCS1Padding, using the raw <key>. For example, the Base64 decoded form of the key from /auth/key request.
Note: The Client may need to transform the key into proper format according to the requirements of the programming language and tool used to encrypt the credential.
-
Base64 encode the encrypted password from step a.
-
Compose credential as <username>:<base64 encoded RSA encrypted password> where <base64 encoded RSA encrypted password> is the string obtained from step b.
-
URL encode the string resulted from step three.
-
-
<URL encoded location URL> is a URL encoded string containing the URL to the resource the API client intends to access after successful authentication. This parameter is optional.
Example: URL: http(s)://<host>:<port>/client/
Note: Responds with “400 Bad Request”, if the credentials are not provided or format is incorrect.
-
Authenticates the credentials against LDAP/AD:
-
If successful, injects session ID and session token as cookies.
-
If the parameter “<URL encoded location URL>” is specified, injects it as Location header and responds with “200 OK”.
The client can make another request with the URL specified in the Location header, along with the session ID and session token cookies to access the desired location.
-
If unsuccessful, responds with “401 Unauthorized”.
-
$ curl -s -v -X POST http://localhost:8080/auth/authenticate \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "k=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsWqa77yEW1S6KTUO6gLTiIxLc4qvpEfeSuRu3FPABCGcX36zv
MONUN%2BiMwMnIgbHZVU4EDAgCZvd%2BySqtJ2GjDjLPBqt7nk5MC4FRk%2FTq25jPliQMZq6og0V8UjC1juePjTaWa2Ly7o
EKiZee7TB4%2B2Fn9kBPCwC%2Bp5CciBqxqXOOVQFvqxOPJGuBIyU64McDMyrsUAX%2Fl94PNhZYGwMfGfKkfEhakASoe3I
dLc07Ar3jb9in2oCWGekJX6xiYLKIAA0yuJKE7%2BzPOKl61mSDHyqT07mWqQ34dYYtJ9%2BGpzBUK%2BdQaDdNo6mR1GcS
gx16DIn%2F5%2FRYXF9tEv5eThQIDAQAB&c=tes%3AR5WBbrz5Tr5e5lAHKBQ56W7qdPNWZrulTK4q4XzuKZxCBuNNr43k9Umfv%2B3JpqgGY9lwLbb%2FJotmEiW03fb1uQJrjKLJ0WAo3UtrYS7HapbCF0O3e1YFzBaNfqgBCJxosR0EwtbrmNYfkxMhGZ6cPCYb5FCRPfkujUQ%2B%2FVTbJXXxonFa75RtstfY6FiiZpbaBXTQXzCQxhiuQFQszquhbjQDrqw0HHddqLZPl1Ai38NxnekbvCjks9iUs3yUWDh0CHD4w%2BDBW3ixr%2BsHV04CaNO2Le174Rt8pZ8qTcOS0ZiFiFmvA7hekRT%2FzrbMDO%2BiisdijT 5YLocydZDEfB%2FDAQ%3D%3D&l=%2Fclient%2Fconsole.html"
Content-Type: application/x-www-form-urlencoded
Content-Length: 818
< HTTP/1.1 200 OK
< Set-Cookie: CSTSED=node0dn8qqo9lis95f9gggmdsqbwn2; Path=/; HttpOnly
< Set-Cookie:
Session-Token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ0aWRhbHNvZnR3YXJlLmNvbSIsInN1YiI6IntcInJlbW90ZS1ob3N0XCI6XCIxMjcuMC4wLjFcIixcImRvbWFpblwiOlwiXCIsXCJ1c2VyXCI6XCJ0ZXNcIixcInVzZXItYWdlbnRcIjpcImN1cmwvNy41OC4wXCJ9IiwiaWF0IjoxNjEyNzk4MjEzLCJleHAiOjE2MTI3OTg4MTN9.VFmKMz1wzUspPAaBS-7aYe2F5J43OpIb vvtobOQN1V9s38ThN8CZ0vNt6Va67saiiHxAffoYcjbUyFhRrAsyvQ; Path=/; HttpOnly
< Location: http://localhost:8080/client/console.html
< Content-Type: text/plain;charset=utf-8
< Content-Length: 14
<
authenticated!
The existing API endpoints /client, /info, /apidoc, and /api/* are modified for these conditions:
-
/client, /info, and /apidoc – If Auth.BASIC = OFF (default) and session ID and session token are not provided, redirects the request to /login. Injects the original request URL as cookie by name “location-url” so that the login page can extract it, encode it, and insert as the “<URL encoded location URL>” parameter when invoking /auth/authenticate.
-
/api/* – If Auth.BASIC = OFF (default) and Auth.API.CompatMode = N and session ID and session token are not provided, responds with “401 Unauthorized”.
TA APIs in the WebService Adapter
TA APIs can be accessed as a TA WebService job as shown here.
TA APIs in the SOAP UI Tool
TA APIs can be accessed from SOAP UI tool. The request should be in XML format. The XML Request should be sent to:
http://<ClientManager_server_hostname>:<port>/api/<Plugin_Name>/postbody
Accessing Documentation for REST API Objects and Methods
Documentation for the REST API Objects and the associated REST API Methods can be accessed via:
-
TA Web or Java Client or your browser as described below.
Method 1:
-
Open the TA Web.
-
Click API Docs on the Help menu.
Method 2:
-
Obtain the Plugin Name from the TA Web:
-
Open the TA Web.
-
Click Master Status in the Navigator. After a few seconds, the Plugin name appears at the top of the panel.
-
-
Enter the URL in your browser
http://<ClientManager server hostname>:<port>/apidoc/<Plugin Name>.