tencent cloud

Overview

CLS allows you to embed the CLS console into an external system so you can conduct log search and analysis without logging in to Tencent Cloud console. This feature offers benefits as follows:

• Quickly integrate CLS search and analysis capabilities into an external service system (e.g., for business maintenance or operation).
• Easily share your log data with others without needing to manage additional Tencent Cloud sub-accounts.

Sample code for an embedded page: cls-iframe-demo.

Note：

This example does not include the authentication logic of external systems. After deployment, all users (even if they have not logged in to Tencent cloud) can view the data under their accounts with the role permissions configured in the example. To ensure data privacy and security, please add the authentication logic of external systems or restrict their access to the private network only to ensure that only authorized users can view the page.

See the figure below for an overview of this feature:

Prerequisites

1. Log in to the CAM console to create a CAM role with console login permissions. Set the role entity to root account, e.g. CompanyOpsRole. Grant the CAM role appropriate access permissions using policies, e.g. QcloudCLSReadOnlyAccess for read-only access.
   
2. Log in to the CAM console.
3. Click Roles on the left sidebar to go to the roles list page.
4. Choose Create Role > Tencent Cloud Account to create a custom role.
5. Select Current root account **, check **Allow the current role to access console, and click Next.
   

   Note：

   If the option Allow the current role to access console is not available, submit a ticket to apply for adding the role to the allowlist.

6. Set access policies for the role, e.g., the read-only policy QcloudCLSReadOnlyAccess, and click Next.
   
7. Enter the role name and click Done.
   
   
8. Obtain the access key of the current user. For more information, see Root Account Access Key.

Directions

1. Log in to the web server outside Tencent Cloud.

2. The external web server assigns you the pre-created role created in Prerequisite 1 based on your identity, e.g. CompanyOpsRole.

3. The web server accesses the Tencent Cloud STS service based on the role name and uses the access key obtained in Prerequisite 2 to call the AssumeRole API to apply for a temporary key of CompanyOpsRole.

4. Call the AssumeRole API to get the temporary key of CompanyOpsRole.

5. Generate a login signature using the temporary key with the steps as shown below:

6. Sorting parameters
   Sort parameters to be signed listed below in ascending alphabetical or numerical order. That is, sort the parameters by their first letters, then by their second letters if their first letters are the same, and so on. You can do this with the aid of sorting functions in programming languages, such as the ksort function in PHP.

   Parameter	Required	Type	Description
   action	Yes	String	Action; fixed as `roleLogin`
   timestamp	Yes	Int	Current timestamp
   nonce	Yes	Int	Random integer. Value range: 10000-100000000
   secretId	Yes	String	Temporary AK returned by STS

7. Formatting parameters
   Combine the above sorted parameters into the form of "parameter name=parameter value". Example:

   action=roleLogin&nonce=67439&secretId=AKI***PLE×tamp=1484793352
   

8. Constructing a signature string
   Construct a signature string in the format of “request method + request CVM + request path + ? + request string”.

   Parameter	Required	Description
   Request CVM and path	Yes	Fixed as cloud.tencent.com/login/roleAccessCallback
   Request method	Yes	GET or POST

   Sample signature string

       GETcloud.tencent.com/login/roleAccessCallback?action=roleLogin&nonce=67439&secretId=AKI***PLE×tamp=1484793352
   

9. Generating a signature string
   Currently, you can sign a string using HMAC-SHA1 or HMAC-SHA256. The sample code in PHP is as follows:

   $secretKey = 'Gu5***1qA';
   $srcStr    = 'GETcloud.tencent.com/login/roleAccessCallback?action=roleLogin&nonce=67439&secretId=×tamp=1484793352';
   $signStr   = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
   echo $signStr;
   

   Sample code for PHP

       <?php
   $secretId  = "AKI***";            //Temporary AK returned by STS
   $secretKey = "Gu5***PLE";         //Temporary SecretKey returned by STS
   $token     = "ADE***fds";         //Security Token returned by STS
   $param["nonce"]     = 11886;      //rand(10000,100000000);
   $param["timestamp"] = 1465185768; //time();
   $param["secretId"]  = $secretId;
   $param["action"]    = "roleLogin";
   ksort($param);
   $signStr = "GETcloud.tencent.com/login/roleAccessCallback?";
   foreach ( $param as $key => $value ) {
       $signStr = $signStr . $key . "=" . $value . "&";
   }
   $signStr   = substr($signStr, 0, -1);
   $signature = base64_encode(hash_hmac("sha1", $signStr, $secretKey, true));
   echo $signature.PHP_EOL;
   

10. Combine your login information and destination page URL into a login URL.

    1. Get the CLS console search analysis page URL.

       https://console.intl.cloud.tencent.com/cls/search?region=<region>&topic_id=<topic_id>
       

    Parameters in the CLS console search analysis page URL:

    Parameter	Required	Type	Description
    region	Yes	String	Region abbreviation, e.g., ap-shanghai for Shanghai region. For other available region abbreviations, see Available Regions
    topic_id	No	String	Log topic ID
    logset_name	No	String	Logset name
    topic_name	No	String	Log topic name
    time	No	String	Time range for log search. Format example: 2021-07-15T10:00:00.000,2021-07-15T12:30:00.000
    queryBase64	No	String	Search and analysis statement, which is base64Url-encoded
    filter	No	String	Filter condition, which is base64Url-encoded. For more information, see Filter Parameter Description
    hideWidget	No	Boolean	Indicates whether to hide agent/documentation button in the bottom-right corner. `true`: Yes; `false`: No (default)
    hideTopNav	No	Boolean	Indicates whether to hide the top navigation bar in the Tencent Cloud console. `true`: Yes; `false`: No (default)
    hideLeftNav	No	Boolean	Indicates whether to hide the left navigation bar in the Tencent Cloud console. `true`: Yes; `false`: No (default)
    hideTopicSelect	No	Boolean	Indicates whether to hide the log topic selection controls (including the region, logset, and log topic controls). `true`: Yes; `false`: No (default)
    hideHeader	No	Boolean	Indicates whether to hide the log topic selection control and the row where the control resides. `true`: Yes; `false`: No (default). This parameter is valid only when `hideTopicSelect` is `true`.
    hideTopTips	No	Boolean	Indicates whether to hide the announcements on the top of the page. `true`: Yes; `false`: No (default)
    hideConfigMenu	No	Boolean	Indicates whether to hide the log topic configuration management menu. `true`: Yes; `false`: No (default)
    hideLogDownload	No	Boolean	Indicates whether to hide the raw log download button. `true`: Yes; `false`: No (default)

Note：

You can specify the log topic to search using URL parameters in either the following modes:

• topic_id: use the log topic ID to specify the log topic to search.

• logset_name+topic_name: use the logset name and log topic name to specify the log topic to search. Note that if the logset or log topic name changes, the URL adopting this mode will become invalid.

• If the topic_id, logset_name, and topic_name parameters exist at the same time, topic_id prevails.

The following figure shows the mappings between hidden parameters and page modules:

2. Splice your login information and destination page URL into a login URL. The parameter values should be URL-encoded.

   https://cloud.tencent.com/login/roleAccessCallback
   ?algorithm=<encryption algorithm for signing; currently only supports SHA1 (used by default) and SHA256
   &secretId=<secretId for signing>
   &token=<Temporary key token>
   &nonce=<nonce for signing>
   ×tamp=<Timestamp for signing>
   &signature=<Signature string>
   &s_url=<Destination URL after login>
   

3. Use the final URL to access the embedded CLS page of the Tencent Cloud console. The sample below is a URL to the CLS search analysis page:

   https://cloud.tencent.com/login/roleAccessCallback?nonce=52055817&s_url=https%3A%2F%2Fconsole.cloud.tencent.com%2Fcls%2Fsearch%3Fregion%3Dap-guangzhou%26start_time%3D2020-05-26%25252014%25253A01%25253A18%26end_time%3D2020-05-26%25252014%25253A16%25253A18&secretId=AKID-vHJ7WPHcy_RVIOm-QTIktXOf9S9z_k_JackOp3dyQPJwmDrNLQJuiNuw9******&signature=eXeWaDn6iJlcPp1sqqGd6m9%2FQk****×tamp=1592455018&token=5e4vuBHL7fBQPi1V9fvSINw4Vu7PSr9Ic3de78b86109c171eb4e3ea27c137c1fIWKU8JC-LO01L87sIYlfTSaHHXeHcqim7Jg9hBuN2nbdfgeBUPXhmpyAk4G6e9bHFZ-7yNRig7Y33CQHxh6jOesP4VfhRzQprWGRtC5No1ty******-aoj_WJhA55oyvqaqxw2jtTdh8nx9OjJr3tlbIa9oJe7aZYoPbdpFqrF6ZjlCPPap2yQB_SkUsWwDl_9BrK2Km3U2IocdvQ7QxrW0ts1aiBi7xtTSJRcfkBYPYEV_YoJrtkhYW3E4L47imA1bfVAjM9F5uKWzVzsDGDT0aCUU9mqdb4vjJrY8tm-wJKKEe8eiyY9EbkH3VWnFV2YocYNDJqFyjKOWR******
   

Filter Parameter Description

Filter parameters are used to generate the filter condition in the query statement box at the bottom of the page, as shown in the figure blow, and are suitable for fixed search criteria.

Filter parameters are in JSON format in the following structure:

[{
   "key": "action",
   "grammarName": "INCLUDE",
   "values": [{
       "values": ["test1"]
   }]
}]

Where:

• key indicates the field name for key-value search. For full-text search, leave key empty.
• grammarName indicates the specific filter mode of the filter condition. Supported values include INCLUDE, EXCLUDE, EXISTS, and RANGE.

  Feature	grammarName	Example	Equivalent Search Statement
  Key-value search - INCLUDE	INCLUDE	[{"key":"action","grammarName":"INCLUDE","values":[{"values":["test1"]}]}]	action:"test1"
  Key-value search - EXCLUDE	EXCLUDE	[{"key":"action","grammarName":"EXCLUDE","values":[{"values":["test1","test2"]}]}]	NOT action:"test1" AND NOT action:"test2"
  Full-text search - INCLUDE	INCLUDE_WITHOUT_KEY	[{"key":"","grammarName":"INCLUDE_WITHOUT_KEY","values":[{"values":["test3"]}]}]	"test3"
  Full-text search - EXCLUDE	EXCLUDE_WITHOUT_KEY	[{"key":"","grammarName":"EXCLUDE_WITHOUT_KEY","values":[{"values":["test3"]}]}]	NOT "test3"
  The field exists	EXISTS	[{"key":"action","grammarName":"EXISTS","values":[]}]	_exists_:action
  The field does not exist	NOT_EXISTS	[{"key":"action","grammarName":"NOT_EXISTS","values":[]}]	NOT _exists_:action
  The numeric type field is in the specified range	RANGE	[{"key":"time","grammarName":"RANGE","values":[{"values":["1"]},{"values":["100"]}]}]	time:[1 TO 100]
  The numeric type field is outside the specified range	NOT_RANGE	[{"key":"time","grammarName":"NOT_RANGE","values":[{"values":["1"]},{"values":["100"]}]}]	NOT time:[1 TO 100]
  The numeric type field is greater than the specified value	MORE_THAN	[{"key":"time","grammarName":"MORE_THAN","values":[{"values":["1"]}]}]	time:>1
  The numeric type field is greater than or equal to the specified value	MORE_THAN_OR_EQUAL	[{"key":"time","grammarName":"MORE_THAN_OR_EQUAL","values":[{"values":["1"]}]}]	time:>=1
  The numeric type field is less than the specified value	LESS_THAN	[{"key":"time","grammarName":"LESS_THAN","values":[{"values":["1"]}]}]	time:<1
  The numeric type field is less than or equal to the specified value	LESS_THAN_OR_EQUAL	[{"key":"time","grammarName":"LESS_THAN_OR_EQUAL","values":[{"values":["1"]}]}]	time:<=1

Note：

Only base64Url-encoded filter parameters can be added to URLs.