OpenSearch:Signature method of OpenSearch API V3

How it works

Each signed request goes through four construction stages before it reaches the OpenSearch server:

AccessKeySecret
      │
      ├─► Build CanonicalizedOpenSearchHeaders  ─┐
      │                                           │
      ├─► Build CanonicalizedResource            ─┤
      │                                           │
      ▼                                           ▼
   string-to-sign  ──► HMAC-SHA1 + Base64 ──► Signature
                                                  │
                                                  ▼
                                        Authorization header

The Authorization header has this format:

Authorization: OPENSEARCH <AccessKeyId>:<Signature>

A space is required after OPENSEARCH.

The signature is computed as:

Signature = base64(hmac-sha1(AccessKeySecret,
            VERB + "\n"
            + Content-MD5 + "\n"
            + Content-Type + "\n"
            + Date + "\n"
            + CanonicalizedOpenSearchHeaders
            + CanonicalizedResource))

Supported applications and protocols

• Application types: Advanced applications, Standard applications

• Protocol: HTTP only

• Request methods: GET for search requests, POST for push-data requests

Prerequisites

Before you begin, make sure you have:

• An AccessKey pair (AccessKey ID and AccessKey secret) issued through alibabacloud.com

• An OpenSearch application (Advanced or Standard edition)

Keep your AccessKey secret strictly confidential. It is used to sign every request.

Step 1: Assemble the string-to-sign

The string-to-sign concatenates the following components in order:

Each component is separated by a newline character (\n). Components with no value (such as Content-MD5 in a search request) contribute an empty string — the \n separator is still required.

Step 2: Build CanonicalizedOpenSearchHeaders

CanonicalizedOpenSearchHeaders covers all request headers whose names start with X-Opensearch-. The most common one is X-Opensearch-Nonce.

`X-Opensearch-Nonce` format: a 10-digit Unix timestamp followed by a 6-digit random number in the range 100000–999999. Example: 1551089397451704.

To build the string:

1. List all X-Opensearch-* headers that have non-empty values.

2. Sort them alphabetically by header name.

3. Convert each header name to lowercase: X-Opensearch-Nonce → x-opensearch-nonce.

4. Remove all spaces around the colon separator: x-opensearch-nonce : value → x-opensearch-nonce:value.

5. Join all header-value pairs with \n, and append \n after the last pair.

Before/after example:

Before: X-Opensearch-Nonce : 1551089397451704
After:  x-opensearch-nonce:1551089397451704\n

If the request has no X-Opensearch-* headers, omit CanonicalizedOpenSearchHeaders from the string-to-sign entirely — do not include an empty line or a trailing \n in its place.

When adding these headers to the actual HTTP request, use the original mixed-case names (X-Opensearch-Nonce), not the lowercase form used in signature calculation.

Step 3: Build CanonicalizedResource

• Search requests: CanonicalizedResource = path + ? + query string

• Push-data requests: CanonicalizedResource = path only

fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson

fetch_fields=name
query=query=name:'document'&&sort=id&&config=format:fulljson

/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson

Step 4: Compute the signature

Use HMAC-SHA1 as defined in RFC 2104. Encode all strings in UTF-8. If the string-to-sign contains non-ASCII characters, encode them to UTF-8 bytes before computing the HMAC.

Pseudocode:

string_to_sign = VERB + "\n"
               + Content-MD5 + "\n"
               + Content-Type + "\n"
               + Date + "\n"
               + CanonicalizedOpenSearchHeaders   # omit if no X-Opensearch-* headers
               + CanonicalizedResource

hmac_bytes = HMAC-SHA1(key=AccessKeySecret.encode("utf-8"),
                       msg=string_to_sign.encode("utf-8"))
Signature  = base64_encode(hmac_bytes)

Python 3 example:

import hmac
import base64

string_to_sign = '\n'.join([
    'GET',
    '',                          # Content-MD5 is blank for search requests
    'application/json',
    '2019-02-25T10:09:57Z',
    'x-opensearch-nonce:1551089397451704',
    '/v3/openapi/apps/app_schema_demo/search'
    '?fetch_fields=name'
    '&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson'
])

signature_hmac = hmac.new(
    'yourAccessKeySecret'.encode('utf-8'),
    string_to_sign.encode('utf-8'),
    'sha1'
)
signature = base64.b64encode(signature_hmac.digest())

Step 5: Add the Authorization header

Combine your AccessKey ID and the computed signature:

headers['Authorization'] = 'OPENSEARCH ' + '<your-access-key-id>' + ':' + signature

Include all required headers in the HTTP request. The header values must exactly match the values used during signature calculation.

End-to-end example

This example walks through a signed GET search request step by step so you can verify each intermediate value.

x-opensearch-nonce:1551089397451704\n

/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson

GET\n
\n
application/json\n
2019-02-25T10:09:57Z\n
x-opensearch-nonce:1551089397451704\n
/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson

1P7tfE****

Authorization: OPENSEARCH LTAI****************:1P7tfE****

Content-MD5:
Content-Type: application/json
Date: 2019-02-25T10:09:57Z
X-Opensearch-Nonce: 1551089397451704
Authorization: OPENSEARCH LTAI****************:1P7tfE****

http://<host>/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson

Request URL format

The full request URL is host + CanonicalizedResource. Replace <host> with the OpenSearch API endpoint for your region.

For push-data requests, include the data payload in the request body.

Application schema template

The following schema defines a Standard application named app_schema_demo. Use it as a starting point for your own application.

{
  "name": "app_schema_demo",
  "type": "standard",
  "schema": {
    "indexes": {
      "search_fields": {
        "id": { "fields": ["id"] },
        "name": { "fields": ["name"], "analyzer": "chn_standard" },
        "phone": { "fields": ["phone"], "analyzer": "fuzzy" },
        "int_arr": { "fields": ["int_arr"] },
        "literal_arr": { "fields": ["literal_arr"] },
        "cate_id": { "fields": ["cate_id"] }
      },
      "filter_fields": ["id", "int_arr", "literal_arr", "float_arr", "cate_id"]
    },
    "tables": {
      "tab": {
        "name": "tab",
        "fields": {
          "id":          { "name": "id",          "type": "INT",           "primary_key": true  },
          "name":        { "name": "name",        "type": "TEXT",          "primary_key": false },
          "phone":       { "name": "phone",       "type": "SHORT_TEXT",    "primary_key": false },
          "int_arr":     { "name": "int_arr",     "type": "INT_ARRAY",     "primary_key": false },
          "literal_arr": { "name": "literal_arr", "type": "LITERAL_ARRAY", "primary_key": false },
          "float_arr":   { "name": "float_arr",   "type": "FLOAT_ARRAY",   "primary_key": false },
          "cate_id":     { "name": "cate_id",     "type": "INT",           "primary_key": false }
        },
        "primary_table": true
      }
    },
    "route_field": null
  },
  "data_sources": [],
  "first_ranks": {},
  "second_ranks": {},
  "summary": [],
  "fetch_fields": ["id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"],
  "quota": { "qps": 6, "doc_size": 0.3 }
}

SDK alternatives

The OpenSearch SDKs for Java, PHP, Python, and C# implement this signature method. The PHP, Python, and C# SDKs include working implementations you can reference when implementing signing in other languages.

OpenSearch does not maintain SDKs that users build from the official source code. Users are responsible for maintaining such implementations.