Azure コスモス DB SQL API でのアクセス制御Access control in the Azure Cosmos DB SQL API

Azure Cosmos DB は、複数の API をサポートするグローバルに分散されたマルチモデル データベースです。Azure Cosmos DB is a globally distributed multi-model database with support for multiple APIs. この記事では、Azure Cosmos DB 用の SQL API について説明します。This article covers the SQL API for Azure Cosmos DB. SQL API のリソースへのアクセスは、マスター キー トークンまたはリソース トークンで制御します。Access to resources in the SQL API is governed by a master key token or a resource token. リソースにアクセスするために、選択されたトークンは、承認文字列の一部として REST の Authorization ヘッダーに含められます。To access a resource, the selected token is included in the REST authorization header, as part of the authorization string.

マスターキートークンMaster key tokens

マスターキートークンは、ユーザーが特定のアカウントでCosmos DBリソースをフルコントロールできるすべてのアクセスキートークンです。The master key token is the all access key token that allows users to have full control of Cosmos DB resources in a particular account. マスター キーは、アカウントの作成時に作成されます。The master key is created during the creation of an account. マスター キーには、プライマリ キーとセカンダリ キーの 2 種類があります。There are two sets of master keys, the primary key and the secondary key. アカウントの管理者は、セカンダリ キーを使用してキーをローテーションさせることができます。The administrator of the account can then exercise key rotation using the secondary key. さらに、必要に応じてキーを再生成することもできます。In addition, the account administrator can also regenerate the keys as needed. キーの再生成とローリングの手順については、「Azure Cosmos DB アカウントを管理する方法」を参照してください。For instructions on regenerating and rolling keys, see How to manage an Azure Cosmos DB account.

リソース トークンResource tokens

リソース トークンは、データベース内のユーザーが、リソース (アクセス許可リソースとも呼ばれます) に対するアクセス制御を正確に行うためのアクセス許可を設定したときに作成されます。Resource tokens are created when users in a database are set up with access permissions for precise access control on a resource, also known as a permission resource. アクセス許可リソースには、ユーザーがアクセスできるリソース パスとアクセスの種類に関する情報を使用して構築されたハッシュ リソース トークンが含まれます。A permission resource contains a hash resource token constructed with the information regarding the resource path and access type a user has access to. アクセス許可リソース トークンには期限があり、有効期間はオーバーライドできます。The permission resource token is time bound and the validity period can be overridden. アクセス許可リソースがアクション (POST、GET、PUT) に基づいて実行されると、新しいリソース トークンが生成されます。When a permission resource is acted upon on (POST, GET, PUT), a new resource token is generated. アクセス許可とリソース トークンの詳細については、「Cosmos DB アクセス許可に対する操作」を参照してください。For information on permissions and resource tokens, see Operations on Cosmos DB Permissions.

Authorization header (Authorization ヘッダー)Authorization header

マスター キー トークンまたはリソース トークンを使用している場合でも、すべての REST 操作は、リソースとやり取りするために承認文字列と共に承認ヘッダーを含める必要があります。All REST operations, whether you're using a master key token or resource token, must include the authorization header with the authorization string in order to interact with a resource. 承認文字列の形式は次のとおりです。The authorization string has the following format:

type={typeoftoken}&ver={tokenversion}&sig={hashsignature}  

認証文字列は次の例のようになります。An authorization string looks like this example:

type=master&ver=1.0&sig=5mDuQBYA0kb70WDJoTUzSBMTG3owkC0/cEN4fqa18/s=  
  

角かっこで囲まれた部分は、次のとおりです。The parts enclosed in brackets are as follows:

  • {typeoftoken} は、トークンの種類 (マスターまたはリソース) を示します。{typeoftoken} denotes the type of token: master or resource.

  • {tokenversion} は、トークンのバージョンを示します(現在は 1.0)。{tokenversion} denotes the version of the token, currently 1.0.

  • {ハッシュ署名} は、ハッシュされたトークン署名を示します。{hashsignature} denotes the hashed token signature.

承認文字列は、無効な文字を含まないようにするために、REST 要求に追加する前にエンコードする必要があります。The authorization string should be encoded before adding it to the REST request to ensure that it contains no invalid characters. MIME RFC2045 を使用して Base64 エンコードされていることを確認します。Ensure that it's Base64 encoded using MIME RFC2045. また、ハッシュ署名で使用されるマスターキーは、Base64 でエンコードされているため、MIME RFC2045 を使用してデコードする必要があります。Also, the master key used in the hashsignature should be decoded using MIME RFC2045 as it's Base64 encoded.

マスタートークンのハッシュトークン署名の作成Constructing the hashed token signature for a master token

マスター キー トークンのハッシュ署名は、のパラメータから作成できます。 ResourceType ResourceLinkThe hash signature for the master key token can be constructed from the following parameters: Verb, ResourceType, ResourceLink, and Date.

マスターキートークンのハッシュ署名を作成する場合は、次の点に注意してください。When constructing the hash signature for the master key token, keep these things in mind:

  1. 文字列の動詞部分は、HTTP 動詞 (GET、POST、PUT など) です。The Verb portion of the string is the HTTP verb, such as GET, POST, or PUT.

  2. 文字列のResourceType部分は、要求が対象となるリソースの種類を識別します。The ResourceType portion of the string identifies the type of resource that the request is for, Eg. "dbs","colls","docs"。"dbs", "colls", "docs".

  3. 文字列のResourceLink部分は、要求の対象となるリソースの ID プロパティです。The ResourceLink portion of the string is the identity property of the resource that the request is directed at. リソースリンクは、リソースの ID に対する大文字/小文字の設定を維持する必要があります。ResourceLink must maintain its case for the ID of the resource. コレクションの例は、"dbs/MyDatabase/colls/MyCollection" のように見えます。Example, for a collection it looks like: "dbs/MyDatabase/colls/MyCollection".

  4. 文字列のDate部分は、メッセージが送信された UTC の日付と時刻(RFC 7231 日付/時刻形式で定義されている "HTTP-date" 形式) ですTue, 01 Nov 1994 08:12:31 GMTThe Date portion of the string is the UTC date and time the message was sent (in "HTTP-date" format as defined by RFC 7231 Date/Time Formats), for example, Tue, 01 Nov 1994 08:12:31 GMT. C# では、DateTime.UtcNow 値の "R" 書式指定子を使用して取得できます。In C#, it can be obtained by using the "R" format specifier on the DateTime.UtcNow value. 同じ日付 (同じ形式) も、要求でx-ms-dateヘッダーとして渡す必要があります。This same date(in same format) also needs to be passed as x-ms-date header in the request.

  5. 最後の空の文字列(")を含む署名文字列内に、表示されているすべての改行文字 (\n) が必要です。All new line characters (\n) shown are required within the signature string including the last empty string("").

Cosmos DB に対する要求の署名文字列をエンコードするには、次の形式を使用します。To encode the signature string for a request against Cosmos DB, use the following format:

文字列ToSign = 動詞.toLowerCase() + "\n" + リソースタイプ.toLowerCase() + "\n" + リソースリンク + "\n" + 日付.toLowerCase() + "\n" + "" + "n" ;StringToSign = Verb.toLowerCase() + "\n" + ResourceType.toLowerCase() + "\n" + ResourceLink + "\n" + Date.toLowerCase() + "\n" + "" + "\n";

有効な承認ヘッダーを生成する [C#] メソッドの例:Example [C#] method to generate a valid Authorization header:

このメソッドの使用方法、および各タイプの操作の各パラメーターに渡す値の例については、For examples on how to use this method, and what values should be passed for each parameter for each type of operation, refer to
NET クライアントからの REST の使用Using REST from a .NET client

  
string GenerateAuthToken(string verb, string resourceType, string resourceId, string date, string key, string keyType, string tokenVersion)  
{  
    var hmacSha256 = new System.Security.Cryptography.HMACSHA256 { Key = Convert.FromBase64String(key) };  
    
    verb = verb ?? "";  
    resourceType = resourceType ?? "";
    resourceId = resourceId ?? "";
  
    string payLoad = string.Format(System.Globalization.CultureInfo.InvariantCulture, "{0}\n{1}\n{2}\n{3}\n{4}\n",  
            verb.ToLowerInvariant(),  
            resourceType.ToLowerInvariant(),  
            resourceId,  
            date.ToLowerInvariant(),  
            ""  
    );  
  
    byte[] hashPayLoad = hmacSha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(payLoad));  
    string signature = Convert.ToBase64String(hashPayLoad);  
  
    return System.Web.HttpUtility.UrlEncode(String.Format(System.Globalization.CultureInfo.InvariantCulture, "type={0}&ver={1}&sig={2}",  
        keyType,  
        tokenVersion,  
        signature));  
}  
  

例 [Node.js]:Example [Node.js]:

  
var crypto = require("crypto");  
  
function getAuthorizationTokenUsingMasterKey(verb, resourceType, resourceId, date, masterKey) {  
    var key = new Buffer(masterKey, "base64");  
  
    var text = (verb || "").toLowerCase() + "\n" +   
               (resourceType || "").toLowerCase() + "\n" +   
               (resourceId || "") + "\n" +   
               date.toLowerCase() + "\n" +   
               "" + "\n";  
  
    var body = new Buffer(text, "utf8");  
    var signature = crypto.createHmac("sha256", key).update(body).digest("base64");  
  
    var MasterToken = "master";  
  
    var TokenVersion = "1.0";  
  
    return encodeURIComponent("type=" + MasterToken + "&ver=" + TokenVersion + "&sig=" + signature);  
}  
  

エンコード例:Example Encoding:

引数Argument [値]Value
動詞Verb GETGET
リソースの種類Resource Type "dbs""dbs"
リソース リンクResource Link "dbs/ToDoList""dbs/ToDoList"
DateDate 木, 27 4月 2017 00:51:12 GMTThu, 27 Apr 2017 00:51:12 GMT
KeyKey dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5JiwvdsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv
W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
キーの種類Key Type mastermaster
トークンバージョンToken Version 1.01.0
出力承認文字列Output Authorization String タイプ%3dマスター%26ver%3d1.0%26シググ%3dc09PEVJrtype%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr
gp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3dgp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

リソース トークンのハッシュ署名の作成Constructing the hash signature for a resource token

リソース トークンは中間サーバーによって生成される必要があります。Resource tokens must be generated by an intermediate server. サーバーはマスターキーの保護者として機能し、Web ブラウザーなどの信頼されていないクライアントに対して時間制限のあるトークンを生成します。The server serves as the master-key guardian and generates time-constrained tokens for untrusted clients, such as web browsers.

このサーバーは、次の手順を実行します。This server performs the following steps:

  1. 新しいトークンに対する着信クライアント要求を処理します。Handles incoming client requests for new tokens.

  2. アプリケーション固有の方法でクライアント ID を検証します。Verifies client identity in an application-specific way.

  3. クライアントが正常に認証されると、Cosmos DB インターフェイス (SDK または REST) を使用して新しい時間制限トークンを生成し、クライアントに返します。If the client authenticates successfully, it uses the Cosmos DB interfaces (SDK or REST) to generate a new time-limited token and returns it to the client.

関連項目See Also