توقيع طلب HTTP باستخدام رمز مصادقة الرسالة المستندة إلى التجزئة (HMAC)

توضح هذه المقالة كيفية توقيع طلب HTTP مع توقيع رمز مصادقة الرسالة المستندة إلى التجزئة (HMAC).

Note

نوصي باستخدام Azure SDKs لتوقيع طلب HTTP. النهج الموضح في هذه المقالة هو خيار احتياطي إذا تعذر استخدام Azure SDKs لأي سبب من الأسباب.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إنشاء رسالة طلب.
• إنشاء تجزئة محتوى.
• حساب توقيع.
• إنشاء سلسلة رأس تخويل.
• إضافة رؤوس.

Prerequisites

• إنشاء حساب في Azure باستخدام اشتراك نشط. إذا لم يكن لديك اشتراك Azure، فشاهد إنشاء حساب مجانا.
• قم بتثبيت Visual Studio.
• أنشئ مورد خدمات اتصالات Azure. إذا لم يكن لديك مورد، فشاهد إنشاء مورد Communication Services. تحتاج إلى تسجيل معلمات و resourceEndpointresourceAccessKey لهذا البرنامج التعليمي.

توقيع طلب HTTP باستخدام C#‎

تستخدم مصادقة مفتاح الوصول مفتاحًا سريًا مشتركًا لإنشاء توقيع HMAC لكل طلب HTTP. يتم إنشاء هذا التوقيع باستخدام خوارزمية SHA256 ويتم إرساله في رأس Authorization باستخدام المخطط HMAC-SHA256. على سبيل المثال:

Authorization: "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=<hmac-sha256-signature>"

يتكون hmac-sha256-signature من:

• فعل HTTP (على سبيل المثال، GET أو PUT)
• مسار طلب HTTP
• x-ms-date
• Host
• x-ms-content-sha256

إعداد عنوان التخويل

أكمل الخطوات التالية لإنشاء عنوان التخويل.

إنشاء تطبيق C# جديد

في نافذة وحدة التحكم، مثل cmd أو PowerShell أو Bash، استخدم الأمر dotnet new لإنشاء تطبيق وحدة تحكم جديد بالاسمSignHmacTutorial. يقوم هذا الأمر بإنشاء مشروع "Hello World" بسيط بلغة C# باستخدام ملف مصدر واحد: Program.cs.

dotnet new console -o SignHmacTutorial

غيّر دليلك إلى مجلد التطبيق المنشأ حديثاً. لتجميع التطبيق الخاص بك، استخدم dotnet build الأمر .

cd SignHmacTutorial
dotnet build

تثبيت الحزمة

قم بتثبيت الحزمة Newtonsoft.Json المستخدمة لتسلسل النص الأساسي.

dotnet add package Newtonsoft.Json

قم بتحديث إعلان الطريقة Main لدعم التعليمة البرمجية غير المتزامنة. استخدم التعليمة البرمجية التالية للبدء.

using System;
using System.Globalization;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
namespace SignHmacTutorial
{
    class Program
    {
        static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Sign an HTTP request Tutorial");
            // Tutorial code goes here.
        }
    }
}

إنشاء رسالة طلب

على سبيل المثال، يمكنك توقيع طلب لإنشاء هوية جديدة باستخدام واجهة برمجة تطبيقات مصادقة خدمات الاتصالات (الإصدار 2021-03-07).

أضف التعليمات البرمجية التالية إلى الأسلوب Main.

string resourceEndpoint = "resourceEndpoint";
// Create a uri you are going to call.
var requestUri = new Uri($"{resourceEndpoint}/identities?api-version=2021-03-07");
// Endpoint identities?api-version=2021-03-07 accepts list of scopes as a body
var body = new
    {
        createTokenWithScopes = new[] { "chat" }
    };

var serializedBody = JsonConvert.SerializeObject(body);

var requestMessage = new HttpRequestMessage(HttpMethod.Post, requestUri)
{
    Content = new StringContent(serializedBody, Encoding.UTF8, "application/json")
};

استبدل resourceEndpoint بقيمة نقطة نهاية المورد الحقيقية.

قم بإنشاء تجزئة المحتوى

تجزئة المحتوى هي جزء من توقيع HMAC الخاص بك. استخدم التعليمة البرمجية التالي لحساب تجزئة المحتوى. يمكنك إضافة هذه الطريقة إلى Program.cs بالطريقة Main.

static string ComputeContentHash(string content)
{
    using var sha256 = SHA256.Create();
    byte[] hashedBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToBase64String(hashedBytes);
}

حساب التوقيع

استخدم التعليمة البرمجية التالية لإنشاء طريقة لحساب توقيع HMAC الخاص بك.

static string ComputeSignature(string stringToSign)
{
    string secret = "resourceAccessKey";
    using var hmacsha256 = new HMACSHA256(Convert.FromBase64String(secret));
    var bytes = Encoding.UTF8.GetBytes(stringToSign);
    var hashedBytes = hmacsha256.ComputeHash(bytes);
    return Convert.ToBase64String(hashedBytes);
}

استبدل resourceAccessKey بمفتاح وصول لمورد خدمات الاتصال الحقيقي.

إنشاء سلسلة رأس التفويض

الآن يمكنك إنشاء السلسلة التي تضيفها إلى عنوان التخويل الخاص بك.

1. إعداد القيم لتوقيع الرؤوس.
   1. حدد الطابع الزمني الحالي باستخدام المنطقة الزمنية التوقيت العالمي المتفق عليه (UTC).
   2. الحصول على مرجع الطلب. استخدم اسم مضيف نظام أسماء المجالات (DNS) أو عنوان IP ورقم المنفذ.
   3. حساب تجزئة المحتوى.
2. تحضير سلسلة للتوقيع.
3. احسب التوقيع.
4. تسلسل السلسلة المستخدمة في عنوان التخويل.

أضف التعليمات البرمجية التالية إلى الأسلوب Main.

// Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard.
var date = DateTimeOffset.UtcNow.ToString("r", CultureInfo.InvariantCulture);
// Get the host name corresponding with the 'host' header.
var host = requestUri.Authority;
// Compute a content hash for the 'x-ms-content-sha256' header.
var contentHash = ComputeContentHash(serializedBody);

// Prepare a string to sign.
var stringToSign = $"POST\n{requestUri.PathAndQuery}\n{date};{host};{contentHash}";
// Compute the signature.
var signature = ComputeSignature(stringToSign);
// Concatenate the string, which will be used in the authorization header.
var authorizationHeader = $"HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature={signature}";

أضف رؤوسًا إلى requestMessage

استخدم التعليمات البرمجية التالية لإضافة العناوين المطلوبة إلى المعلمة الخاصة بك requestMessage .

// Add a date header.
requestMessage.Headers.Add("x-ms-date", date);

// Add a host header.
// In C#, the 'host' header is added automatically by the 'HttpClient'. However, this step may be required on other platforms such as Node.js.

// Add a content hash header.
requestMessage.Headers.Add("x-ms-content-sha256", contentHash);

// Add an authorization header.
requestMessage.Headers.Add("Authorization", authorizationHeader);

اختبار العميل

اتصل بنقطة النهاية باستخدام HttpClient، وتحقق من الاستجابة.

HttpClient httpClient = new HttpClient
{
    BaseAddress = requestUri
};
var response = await httpClient.SendAsync(requestMessage);
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);

Prerequisites

• إنشاء حساب في Azure باستخدام اشتراك نشط. إذا لم يكن لديك اشتراك Azure، فشاهد إنشاء حساب مجانا.
• قم بتنزيل وتثبيت Python.
• قم بتنزيل وتثبيت Visual Studio Code أو بيئة تطوير متكاملة أخرى (IDE) تدعم Python.
• أنشئ مورد خدمات اتصالات Azure. إذا لم يكن لديك مورد، فشاهد إنشاء مورد Communication Services. تحتاج إلى معلمات و resource_endpoint_nameresource_endpoint_secret لهذا المثال.

توقيع طلب HTTP باستخدام Python

تستخدم مصادقة مفتاح الوصول مفتاحًا سريًا مشتركًا لإنشاء توقيع HMAC لكل طلب HTTP. يتم إنشاء هذا التوقيع باستخدام خوارزمية SHA256 ويتم إرساله في رأس Authorization باستخدام المخطط HMAC-SHA256. على سبيل المثال:

Authorization: "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=<hmac-sha256-signature>"

يتكون hmac-sha256-signature من:

• فعل HTTP (على سبيل المثال، GET أو PUT)
• مسار طلب HTTP
• x-ms-date
• Host
• x-ms-content-sha256

إعداد عنوان التخويل

أكمل الخطوات التالية لإنشاء عنوان التخويل.

إنشاء برنامج نصي Python جديد

افتح Visual Studio Code أو IDE آخر أو محرر آخر من اختيارك. إنشاء ملف جديد يسمى sign_hmac_tutorial.py. احفظ هذا الملف في مجلد معروف.

إضافة عمليات الاستيراد الضرورية

sign_hmac_tutorial.py تحديث البرنامج النصي مع التعليمات البرمجية التالية للبدء.

import base64
import hashlib
import hmac
import json
from datetime import datetime, timezone
from urllib import request

إعداد البيانات للطلب

على سبيل المثال، يمكنك توقيع طلب لإنشاء هوية جديدة باستخدام Communication Services Authentication API (الإصدار 2021-03-07).

أضف التعليمات البرمجية sign_hmac_tutorial.py التالية إلى البرنامج النصي.

• استبدل resource_endpoint_name بقيمة اسم نقطة نهاية المورد الحقيقي. يمكنك العثور على هذه القيمة في قسم نظرة عامة في مورد خدمات الاتصالات. إنها قيمة Endpoint بعد https://.
• استبدل resource_endpoint_secret بالقيمة السرية لنقطة نهاية المورد الحقيقي. يمكنك العثور على هذه القيمة في قسم المفاتيح في مورد خدمات الاتصالات. إنها قيمة المفتاح ، وهي إما أساسية أو ثانوية.

host = "resource_endpoint_name"
resource_endpoint = f"https://{host}"
path_and_query = "/identities?api-version=2021-03-07"
secret = "resource_endpoint_secret"

# Create a uri you are going to call.
request_uri = f"{resource_endpoint}{path_and_query}"

# Endpoint identities?api-version=2021-03-07 accepts the list of scopes as a body.
body = { "createTokenWithScopes": ["chat"] }

serialized_body = json.dumps(body)
content = serialized_body.encode("utf-8")

قم بإنشاء تجزئة المحتوى

تجزئة المحتوى هي جزء من توقيع HMAC الخاص بك. استخدم التعليمة البرمجية التالي لحساب تجزئة المحتوى. يمكنك إضافة هذا الأسلوب إلى sign_hmac_tutorial.py البرنامج النصي.

def compute_content_hash(content):
    sha_256 = hashlib.sha256()
    sha_256.update(content)
    hashed_bytes = sha_256.digest()
    base64_encoded_bytes = base64.b64encode(hashed_bytes)
    content_hash = base64_encoded_bytes.decode('utf-8')
    return content_hash

حساب التوقيع

استخدم التعليمة البرمجية التالية لإنشاء طريقة لحساب توقيع HMAC الخاص بك.

def compute_signature(string_to_sign, secret):
    decoded_secret = base64.b64decode(secret)
    encoded_string_to_sign = string_to_sign.encode('utf-8')
    hashed_bytes = hmac.digest(decoded_secret, encoded_string_to_sign, digest=hashlib.sha256)
    encoded_signature = base64.b64encode(hashed_bytes)
    signature = encoded_signature.decode('utf-8')
    return signature

الحصول على طابع زمني UTC الحالي وفقا لمعيار RFC1123

استخدم التعليمات البرمجية التالية للحصول على تنسيق التاريخ الذي تريده مستقلا عن إعدادات الإعدادات المحلية.

def format_date(dt):
    days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
    utc = dt.utctimetuple()

    return "{}, {:02} {} {:04} {:02}:{:02}:{:02} GMT".format(
    days[utc.tm_wday],
    utc.tm_mday,
    months[utc.tm_mon-1],
    utc.tm_year,
    utc.tm_hour, 
    utc.tm_min, 
    utc.tm_sec)

إنشاء سلسلة رأس التفويض

الآن يمكنك إنشاء السلسلة التي تضيفها إلى عنوان التخويل الخاص بك.

1. إعداد القيم لتوقيع الرؤوس.
   1. حدد الطابع الزمني الحالي باستخدام المنطقة الزمنية التوقيت العالمي المتفق عليه (UTC).
   2. الحصول على مرجع الطلب. استخدم اسم مضيف نظام أسماء المجالات (DNS) أو عنوان IP ورقم المنفذ.
   3. حساب تجزئة المحتوى.
2. تحضير سلسلة للتوقيع.
3. احسب التوقيع.
4. تسلسل السلسلة المستخدمة في عنوان التخويل.

أضف التعليمات البرمجية sign_hmac_tutorial.py التالية إلى البرنامج النصي.

# Specify the 'x-ms-date' header as the current UTC timestamp according to the RFC1123 standard.
utc_now = datetime.now(timezone.utc)
date = format_date(utc_now)
# Compute a content hash for the 'x-ms-content-sha256' header.
content_hash = compute_content_hash(content)

# Prepare a string to sign.
string_to_sign = f"POST\n{path_and_query}\n{date};{host};{content_hash}"
# Compute the signature.
signature = compute_signature(string_to_sign, secret)
# Concatenate the string, which will be used in the authorization header.
authorization_header = f"HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature={signature}"

إضافة رؤوس

استخدم التعليمات البرمجية التالية لإضافة العناوين المطلوبة.

request_headers = {}

# Add a date header.
request_headers["x-ms-date"] = date

# Add a content hash header.
request_headers["x-ms-content-sha256"] = content_hash

# Add an authorization header.
request_headers["Authorization"] = authorization_header

# Add a content type header.
request_headers["Content-Type"] = "application/json"

اختبار العميل

اتصل بنقطة النهاية وتحقق من الاستجابة.

req = request.Request(request_uri, content, request_headers, method='POST')
with request.urlopen(req) as response:
  response_string = json.load(response)
print(response_string)

تنظيف الموارد

لتنظيف اشتراك Communication Services وحذفه، يمكنك حذف المورد أو مجموعة الموارد. يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا. يمكنك معرفة المزيد حول كيفية تنظيف موارد Azure Communication Servicesوتنظيف موارد Azure Functions.

المحتوى ذو الصلة

• إضافة مكالمات صوتية إلى تطبيقك
• إضافة دردشة إلى تطبيقك
• إنشاء رموز مميزة لوصول المستخدم
• التعرف على تصميم العميل والخادم
• التعرف على المصادقة