すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:V4 署名を Authorization ヘッダーに含める (推奨)

最終更新日:Apr 15, 2025

OSS へのリクエストを開始する際は、認証を成功させるために V4 署名 を含む Authorization リクエストヘッダーを含める必要があります。 SDK には高度な V4 署名アルゴリズムが既に統合されているため、リクエストを開始するには、OSS 提供の SDK の使用を優先してください。 SDK を使用できない場合にのみ、このドキュメントを参照して V4 署名アルゴリズムを手動で実装してください。

OSS SDK を使用して V4 署名を自動的に実装する

V4 署名アルゴリズムを実装する必要がある場合は、OSS SDK の V4 署名の実装を参照することをお勧めします。

SDK

実装

Java

OSSV4Signer.java

Python

v4.py

Go

v4.go

JavaScript

client.js

PHP

SignerV4.php

C#

SignerV4.cs

Android

OSSV4Signer.java

iOS

OSSV4Signer.m

C++

SignerV4.cc

C

oss_auth.c

Authorization リクエストヘッダー

OSS へのリクエストを開始する際は、Authorization ヘッダーに署名を実装して、リクエストを検証する必要があります。

Authorization ヘッダーの構文は次のとおりです。

Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request, AdditionalHeaders=<AdditionalHeadersVal>, Signature=<SignatureVal>

Authorization ヘッダーの説明は次のとおりです。

コンポーネント

説明

OSS4-HMAC-SHA256

署名の計算に使用されるアルゴリズムを指定します。この文字列は、署名バージョンと署名アルゴリズム (HMAC-SHA256) を指定します。V4 署名が認証に使用される場合は、OSS4-HMAC-SHA256 の値が必要です。

Credential

AccessKey ID とスコープを指定します。スコープには、署名の計算に使用される日付、リージョン、クラウド サービスが含まれます。V4 署名が認証に使用される場合は、このフィールドが必要です。

構文は次のとおりです。

<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request

各項目の説明は次のとおりです。

  • AccessKeyId: リクエスターの ID を検証するために使用される一意の識別子である、AccessKey ID。

  • SignDate: YYYYMMDD 形式の署名日付。

  • SignRegion: リクエストに使用される リージョン ID。例: cn-hangzhou。

  • oss: リクエストされているサービスを Alibaba Cloud Object Storage Service (OSS) として識別する固定文字列。

  • aliyun_v4_request: 署名バージョンを V4 として指定する固定文字列。

AdditionalHeaders

署名計算に含まれるオプションのリクエストヘッダーを指定します (署名計算に含める必要がある必須ヘッダーを指定する必要はありません)。このフィールドには、小文字のヘッダー名のみが含まれ、辞書式順序でソートされ、セミコロン (;) で区切られます。

例は次のとおりです。

content-disposition;content-length

Signature

計算された署名。V4 署名が認証に使用される場合は、このフィールドが必要です。

次のサンプル コードは、64 個の小文字の 16 進数で表される 256 ビット署名値の例を示しています。

3938**********************************dcdc

署名計算

リクエストを受信すると、OSS は署名を計算し、Authorization リクエストヘッダーの署名と比較します。一致する場合、リクエストは成功します。一致しない場合、リクエストは失敗します。

署名計算プロセス

次の図は、署名計算プロセスを示しています。

署名計算プロセスは、次の 3 つのステップで構成されます。

  1. 正規化リクエストの構築: OSS 署名仕様に従ってリクエストをフォーマットし、正規化リクエストを生成します。

  2. StringToSign の構築: 正規化リクエストを連結して、StringToSign を導出します。

  3. 署名の計算: AccessKey Secret に対して複数のハッシュ操作を実行して派生キーを生成し、派生キーを使用してStringToSign を計算して、最終的な署名を取得します。AccessKey Secret に対して複数ステップの HMAC-SHA256 操作を実行することにより、StringToSign の HMAC-SHA256 ハッシュを計算するための派生キーが生成され、最終的な署名が生成されます。

1. 正規化リクエストの構築

正規化リクエストの構文は次のとおりです。

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

次の表は、正規化リクエストのパラメーターについて説明しています。

パラメーター

説明

HTTP Verb

HTTP リクエストメソッド。PUT、GET、POST、HEAD、DELETE、OPTIONS など。

Canonical URI

URI エンコードされたリソースパス。リソースパスにはクエリ文字列は含まれず、スラッシュ (/) のエンコードは不要です。

  • リクエストターゲットが OSS の場合、リソースパスは / で、URI エンコードされたリソースパスは UriEncode("/") です。

  • リクエストターゲットがバケットの場合、リソースパスは /examplebucket/ で、URI エンコードされたリソースパスは UriEncode("/examplebucket/") です。

  • リクエストターゲットがバケット内のオブジェクトの場合、リソースパスは /examplebucket/exampleobject で、URI エンコードされたリソースパスは UriEncode("/examplebucket/exampleobject") です。

Canonical Query String

辞書式順序でソートされた、URI エンコードされたクエリパラメーター。

  • クエリパラメーターにパラメーター名と値の両方が含まれている場合は、各パラメーターの名前と値を個別に URI エンコードし、エンコードされた名前基づいてパラメーターを辞書式順序でソートします。ソートはエンコード後に行われることに注意してください。= を使用してエンコードされた名前と値を接続し、& を使用して異なるパラメーターを連結します。

    • クエリパラメーター: prefix=somePrefix&marker=someMarker&max-keys=20

    • 正規化されたクエリパラメーター:

      UriEncode("marker")+"="+UriEncode("someMarker")+"&"+UriEncode("max-keys")+"="+UriEncode("20")+"&"+UriEncode("prefix")+"="+UriEncode("somePrefix")
  • クエリパラメーターにパラメーター名のみが含まれている場合は、パラメーター名に対して URI エンコードを実行し、parameter name= 形式でフォーマットされたクエリを構築します。

    • クエリパラメーター: ?acl

    • 正規化されたクエリパラメーター: UriEncode("acl") + "=" + ""

  • クエリパラメーターがない場合、つまり、リクエスト URI に ? が含まれていない場合、正規化されたクエリ文字列は空の文字列 ("") に設定されます。

Canonical Headers

リクエストヘッダーのリスト。

リクエストヘッダーは、次の 3 つのカテゴリに分類されます。

  • リクエストに存在し、署名計算に含まれる必要があるヘッダー:

    • x-oss-content-sha256: UNSIGNED-PAYLOAD のみがサポートされています。

  • リクエストに存在する場合、署名計算に含める必要があるヘッダー:

    • Content-Type

    • Content-MD5

    • x-oss-*: x-oss- で始まるその他のリクエストヘッダー。たとえば、STS AK を介してアクセスする場合、SecurityToken は x-oss-security-token:security-token を介して記述されます。たとえば、リクエスト時間は x-oss-date を介して記述され、構文は 20231203T121212Z などの ISO8601 標準時間形式である必要があります。

  • AdditionalHeaders で指定されたオプションのリクエストヘッダー。

構文は次のとおりです。

Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n"
Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n"
...
Lowercase(<HeaderNameN>) + ":" + Trim(<value>) + "\n"

次のサンプル コードは例を示しています。

content-disposition:attachment
content-length:3
content-md5:ICy5YqxZB1uWSwcVLSNLcA==
content-type:text/plain
x-oss-content-sha256:UNSIGNED-PAYLOAD
x-oss-date:20250328T101048Z

Additional Headers

署名計算に含まれるオプションのリクエストヘッダーを指定します (署名計算に含める必要がある必須ヘッダーを指定する必要はありません)。このフィールドには、小文字のヘッダー名のみが含まれ、辞書式順序でソートされ、セミコロン (;) で区切られます。AdditionalHeaders と一致します。

署名計算に含まれるオプションのヘッダー (必須ヘッダーを除く) を指定します。小文字のヘッダー名のみが含まれ、辞書式順序でソートされます。セミコロン (;) で区切られ、AdditionalHeaders と一致します。

次のサンプル コードは例を示しています。

content-disposition;content-length

Hashed PayLoad

リクエストペイロードの SHA256 ハッシュ値の 16 進数表現。UNSIGNED-PAYLOAD の値のみがサポートされています。

2. StringToSign の構築

StringToSign の構文は次のとおりです。

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

次の表は、StringToSign のパラメーターについて説明しています。

パラメーター

説明

OSS4-HMAC-SHA256

署名のハッシュアルゴリズム。値は OSS4-HMAC-SHA256 である必要があります。

TimeStamp

現在の UTC 時間。構文は 20250320T083322Z などの ISO8601 である必要があります。

Scope

派生キーを取得/検索するためのパラメーターセット。このパラメーターセットは、日付、リージョン、サービスを指定します。したがって、派生キーを使用して計算された署名は、指定された日付、リージョン、サービスに対してのみ有効です。

構文は次のとおりです。

<SignDate>/<SignRegion>/oss/aliyun_v4_request

各項目の説明は次のとおりです。

  • SignDate: 署名に含まれる、YYYYMMDD 形式の日付。

  • SignRegion: 署名に使用される リージョン ID。たとえば、cn-hangzhou など。

  • oss: 署名に含まれるサービス名。oss として固定。

  • aliyun_v4_request: 署名に含まれるバージョン。aliyun_v4_request として固定。

CanonicalRequest

構築された正規化リクエスト。

3. 署名の計算

署名の計算には、次の 2 つのステップが含まれます。

  1. SigningKey を計算します。

    DateKey = HMAC-SHA256("aliyun_v4" + SK, Date);
    DateRegionKey = HMAC-SHA256(DateKey, Region);
    DateRegionServiceKey = HMAC-SHA256(DateRegionKey, "oss");
    SigningKey = HMAC-SHA256(DateRegionServiceKey, "aliyun_v4_request");
    • SK: 署名に含まれる AccessKey Secret。

    • Date: 署名に含まれる YYYYMMDD 形式の日付。StringToSign の SignDate と一致する必要があります。

    • Region: 署名に使用される リージョン ID。たとえば、cn-hangzhou など。StringToSign の SignRegion と一致する必要があります。

  2. SigningKey と StringToSign を使用して Signature を計算します。

    Signature = HEX(HMAC-SHA256(SigningKey, StringToSign))

署名計算の例

次の例は、PutObject 操作を呼び出すことによって署名を計算する方法を示しています。

署名計算のパラメーター

パラメーター

AccessKeyId

LTAI****************

AccessKeySecret

yourAccessKeySecret

Timestamp

20250411T064124Z

Bucket

examplebucket

Object

exampleobject

Region

cn-hangzhou

署名計算の例

  1. 正規化リクエストを構築します。

    PUT
    /examplebucket/exampleobject
    
    content-disposition:attachment
    content-length:3
    content-md5:ICy5YqxZB1uWSwcVLSNLcA==
    content-type:text/plain
    x-oss-content-sha256:UNSIGNED-PAYLOAD
    x-oss-date:20250411T064124Z
    
    content-disposition;content-length
    UNSIGNED-PAYLOAD
  2. StringToSign を構築します。

    OSS4-HMAC-SHA256
    20250411T064124Z
    20250411/cn-hangzhou/oss/aliyun_v4_request
    c46d96390bdbc2d739ac9363293ae9d710b14e48081fcb22cd8ad54b63136eca
  3. 署名を計算します。

    1. SigningKey を計算します。

      説明

      読みやすくするために、以下の SigningKey は 16 進数形式で表示されています。

      3543b7686e65eda71e5e5ca19d548d78423c37e8ddba4dc9d83f90228b457c76
    2. Signature を計算します。

      053edbf550ebd239b32a9cdfd93b0b2b3f2d223083aa61f75e9ac16856d61f23