All Products
Search

This Product

    Object Storage Service:Include a V4 signature in the Authorization header (recommended)

    Document Center

    Object Storage Service:Include a V4 signature in the Authorization header (recommended)

    Last Updated:Apr 09, 2024

    In Object Storage Service (OSS), using the Authorization header of HTTP requests is the most common method of providing authentication information. Except for POST requests and requests that are signed by using query parameters, all OSS operations use the Authorization header for authentication. This topic describes how to include a V4 signature in the Authorization header.

    Use OSS SDKs to automatically implement V4 signatures

    OSS SDKs support the automatic implementation of V4 signatures. We recommend that you use OSS SDKs to initiate requests. This eliminates the need to manually calculate signatures. For more information about how to sign requests by using the V4 signature algorithm when you use OSS SDKs for different programming languages, see the sample code of OSS SDKs. The following table provides references to the sample code used to sign requests by using the V4 signature algorithm when you use OSS SDKs for different programming languages.

    OSS SDK

    Sample code

    Java

    OSSV4Signer.java

    PHP

    SignerV4.php

    Node.js

    client.js

    Browser.js

    Python

    auth.py

    Go

    v4.go

    C++

    SignerV4.cc

    C

    oss_auth.c

    Calculation of the Authorization header

    Separate the signature algorithm version and signature information in the Authorization header with a space. The following table describes the components of the Authorization header.

    Component

    Description

    Signature algorithm version

    The algorithm that is used to calculate the signature. Valid value: OSS4-HMAC-SHA256.

    Signature information

    The parameters used to calculate the signature. The signature information is in the form of key-value pairs. Separate key-value pairs with commas (,), and connect keys and values with equal signs (=). The keys in the signature information include two required fields (Credential and Signature) and one optional field (AdditionalHeaders).

    • Credential: the AccessKey ID and the scope information, which are separated by forward slashes (/).

    • Signature: the calculated signature.

    • AdditionalHeaders: optional request headers that are used to calculate the signature. If you specify multiple headers, separate them with semicolons (;). Header keys are not case-sensitive and must be sorted lexicographically.

    • Format

      Authorization: "OSS4-HMAC-SHA256 Credential=" + AccessKeyId + "/" + SignDate + "/" + SignRegion + "/oss/aliyun_v4_request, " + [ "AdditionalHeaders=" + AdditionalHeadersVal + ", " ] + "Signature=" + SignatureVal

    • Example

      Authorization: OSS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20231203/cn-hangzhou/oss/aliyun_v4_request, AdditionalHeaders=host;userdefine, Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7
    Note

    When you send a request by using the temporary access credentials obtained from Security Token Service (STS), you must add the obtained security token to the request headers by specifying the x-oss-security-token:security-token header. For more information about how to obtain a security token, see AssumeRole.

    Signature calculation process

    image

    Step 1: Create a canonical request

    Convert the content of your request to the canonical format.

    Format

    HTTP Verb + "\n" +
Canonical URI + "\n" +
Canonical Query String + "\n" +
Canonical Headers + "\n" +
Additional Headers + "\n" +
Hashed PayLoad

    The following table describes the preceding parameters.

    Parameter

    Type

    Required

    Example

    Description

    HTTP Verb

    Enumeration

    Yes

    PUT

    The method of the HTTP request, which can be PUT, GET, POST, HEAD, DELETE, or OPTIONS.

    Canonical URI

    String

    Yes

    /examplebucket/exampleobject

    A URI-encoded string. Do not encode the forward slash (/) in the absolute path.

    • The URI starts with a forward slash (/) that follows the domain name and up to the end of the string if query string parameters are not included.

    • The URI starts with a forward slash (/) that follows the domain name and ends with a question mark (?) if query string parameters are included.

    The following items describe how to specify a canonical URI based on the resources included in the request URI:

    • If the request URI contains both a bucket name and an object name, the canonical URI is in the following format:

      /examplebucket/exampleobject.

    • If the request URI contains only a bucket name, the canonical URI is in the following format: /examplebucket/.

    • If the requested URI contains only an object name, the canonical URI is set to /.

    Canonical Query String

    String

    Yes

    UriEncode("marker") + "=" + UriEncode("someMarker") + "&" + UriEncode("max-keys") + "=" + UriEncode("20") + "&" + UriEncode("prefix") + "=" + UriEncode("somePrefix")

    The URI-encoded query string parameters. You need to URI-encode each key and value individually.

    • Sort the parameters in the canonical query string alphabetically by key name. The sorting occurs after encoding. If identical keys exist, sort the keys in chronological order based on the time when they were added.

    • If a key does not have a value, add only the key.

    • If a request does not include a query string, set the canonical query string to an empty string (""). You must add a line break at the end.

    Canonical Headers

    String

    Yes

    host:cname.com
x-oss-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-oss-date:20231203T121212Z

    A string that contains the list of request headers and their values. The headers are separated by \n.

    • A header key and value are separated by a colon (:), and headers are separated by a line feed.

    • Header keys must be in lowercase letters and sorted in alphabetical order. Leading or trailing spaces in the header values must be trimmed.

    • The request time is specified by the x-oss-date header. The time follows the ISO 8601 standard and is displayed in UTC. Example: 20231203T121212Z.

    Canonical Headers are divided into two types:

    • Headers that must exist and are used for signature calculation:

      • x-oss-content-sha256 (Valid value: UNSIGNED-PARYLOAD)

      • The headers specified by Additional Headers and used for signature calculation:

    • Headers that must be added to Canonical Headers if they are in the request:

      • Content-Type

      • Content-MD5

      • x-oss-*

    Additional Headers

    String

    Yes

    content-length;host

    The headers to be added to calculate the signature, except for the Content-Type, Content-MD5, and x-oss-* headers. All headers must be in lowercase letters and sorted in alphabetical order.

    Hashed PayLoad

    String

    Yes

    UNSIGNED-PAYLOAD

    Valid value: UNSIGNED-PAYLOAD.

    Example

    "GET" | "PUT" | ... + "\n" +
UriEncode(<Resource>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<Value>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" + "\n"
Lowercase(<AdditionalHeaderName1>) + ";" + Lowercase(<AdditionalHeaderName2>) + "\n" +
UNSIGNED-PAYLOAD

    Step 2: Create a string to sign

    Concatenate the following strings to create a string to sign.

    • Format

      "OSS4-HMAC-SHA256" + "\n" +
TimeStamp + "\n" +
Scope + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

      The following table describes the preceding parameters.

      Parameter

      Type

      Required

      Example

      Description

      OSS4-HMAC-SHA256

      Enumeration

      Yes

      OSS4-HMAC-SHA25

      The algorithm used to create the hash of the canonical request. Valid value: OSS4-HMAC-SHA256.

      TimeStamp

      String

      Yes

      20231203T121212Z

      The current time in UTC. The time must follow the ISO 8601 standard.

      Scope

      String

      Yes

      20231203/cn-hangzhou/oss/aliyun_v4_request

      The scope information. This restricts the resulting signature to the specified region and service. Format:

      <SigningDate>/<SigningRegion>/oss/aliyun_v4_request

      • SigningDate: the date when the request is initiated.

      • SigningRegion: the region in which the requested resource resides.

      • oss: the name of the requested service. Valid value: oss.

      • aliyun_v4_request: the description of the signature version in the request. Valid value: aliyun_v4_request.

      CanonicalRequest

      String

      Yes

      PUT

      /examplebucket/exampleobject

      content-md5:eB5eJF1ptWaXm4bijSPyxw

      content-type:text/html

      host:examplebucket.oss-cn-hangzhou.aliyuncs.com

      x-oss-content-sha256:UNSIGNED-PAYLOAD

      x-oss-date:20231203T121212Z

      x-oss-meta-author:alice

      x-oss-meta-magic:abracadabra

      host

      UNSIGNED-PAYLOAD

      The string constructed in Step 1.

    • Example

      "OSS4-HMAC-SHA256" + "\n" +
FormatISO8601 + "\n" +
20231203/cn-hangzhou/oss/aliyun_v4_request + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

    Step 3: Calculate the signature

    After you derive the signing key, calculate the signature by performing a keyed hash operation on the string to sign. Use the derived signing key as the hash key for this operation.

    1. Calculate the signing key. 

      HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("aliyun_v4" + SK, Date), Region), "oss"), "aliyun_v4_request");

    2. Calculate the signature. 

      HEX(HMAC-SHA256(SigningKey, StringToSign))

    Signature calculation example

    In this example, PutObject is used to describe how to include a V4 signature in the Authorization header.

    • Parameters

      Parameter

      Example

      AccessKeyId

      accesskeyid

      AccessKeySecret

      accesskeysecret

      Timestamp

      20231203T121212Z

      Bucket

      examplebucket

      Object

      exampleobject

      Region

      cn-hangzhou

    • PutObject

      PUT /exampleobject HTTP/1.1
Content-MD5: eB5eJF1ptWaXm4bijSPyxw
Content-Type: text/html
Date: Sun, 03 Dec 2023 12:12:12 GMT
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureToBeCalculated
x-oss-date: 20231203T121212Z 
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra
x-oss-content-sha256: UNSIGNED-PAYLOAD

    To include a V4 signature in the Authorization header, perform the following steps:

    1. Create a canonical request. 

      PUT
/examplebucket/exampleobject

content-md5:eB5eJF1ptWaXm4bijSPyxw
content-type:text/html
host:examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-content-sha256:UNSIGNED-PAYLOAD
x-oss-date:20231203T121212Z
x-oss-meta-author:alice
x-oss-meta-magic:abracadabra

host
UNSIGNED-PAYLOAD

    2. Create a string to sign. 

      OSS4-HMAC-SHA256
20231203T121212Z
20231203/cn-hangzhou/oss/aliyun_v4_request
129b14df88496f434606e999e35dee010ea1cecfd3ddc378e5ed4989609c1db3

    3. Calculate the signature.

      1. Calculate the signing key.

        Note

        For readability, the following example shows the Base64-encoded value of the signing key. 

        WVjaYR8lCj9YC5PUS2RSZQANYbuh9DhMFxjU1NtZKfc=

      2. Calculate the signature. 

        4b663e424d2db9967401ff6ce1c86f8c83cabd77d9908475239d9110642c63fa

    4. Add the signature to the Authorization header. 

      OSS4-HMAC-SHA256 Credential=accesskeyid/20231203/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=4b663e424d2db9967401ff6ce1c86f8c83cabd77d9908475239d9110642c63fa