Sign inGet Started

mTLS

Available on requestContact your Bird representative to enable it for your organization.

म्यूचुअल TLS (mTLS) TLS हैंडशेक में दोनों दिशाओं में सर्टिफ़िकेट की जाँच जोड़ता है। हर दिशा की अपनी सेटिंग होती हैं। आप एक दिशा या दोनों दिशाएँ सेट कर सकते हैं।

दिशाTLS क्लाइंटTLS सर्वरसेटिंग
API अनुरोधआपके सिस्टमmTLS एंडपॉइंटWorkspace settings > mTLS
वेबहुक डिलीवरीहमआपके रिसीवरWebhooks > mTLS

हर पक्ष अपनी निजी कुंजियाँ अपने पास रखता है। API अनुरोधों के लिए, आप हमें अपने सर्टिफ़िकेट प्राधिकरण (CA) का सार्वजनिक सर्टिफ़िकेट देते हैं। वेबहुक डिलीवरी के लिए, हम आपको एक सर्टिफ़िकेट हस्ताक्षर अनुरोध (CSR) देते हैं, और आप हस्ताक्षरित सार्वजनिक सर्टिफ़िकेट हमें लौटाते हैं।

शुरू करने से पहले

  • अपने संगठन के लिए API mTLS, वेबहुक mTLS या दोनों चालू करवाने के लिए अपने Bird प्रतिनिधि से संपर्क करें। हर दिशा अलग से चालू की जाती है।
  • वर्कस्पेस में access_restrictions स्कोप पर लिखने की अनुमति वाली भूमिका लें। वेबहुक टेस्ट इवेंट भेजने के लिए, webhooks स्कोप पर भी लिखने की अनुमति लें।
  • API अनुरोधों के लिए, उस CA का PEM सर्टिफ़िकेट लें जो आपके क्लाइंट सर्टिफ़िकेट जारी करता है। रूट CA के बजाय जारी करने वाले CA को प्राथमिकता दें, क्योंकि चेन की जाँच हर उस सर्टिफ़िकेट को स्वीकार करती है जिसकी चेन किसी पंजीकृत CA तक पहुँचती है। इसलिए रूट CA जोड़ने पर उसके दूसरे जारी करने वाले CA के सर्टिफ़िकेट भी जाँच में पास हो जाते हैं। हर सर्टिफ़िकेट को फिर भी बाकी जाँचों में पास होना होता है, जैसे clientAuth विस्तारित कुंजी उपयोग।
  • वेबहुक डिलीवरी के लिए, ऐसा CA तैयार रखें जो clientAuth विस्तारित कुंजी उपयोग के साथ CSR पर हस्ताक्षर कर सके।

API अनुरोधों पर क्लाइंट सर्टिफ़िकेट अनिवार्य करें

हर क्षेत्र का एक mTLS एंडपॉइंट है। यह मानक एंडपॉइंट वाले ही ऑपरेशन देता है और हर क्लाइंट से सर्टिफ़िकेट माँगता है।

क्षेत्रमानक एंडपॉइंटmTLS एंडपॉइंट
eu1https://eu1.platform.bird.comhttps://mtls.eu1.platform.bird.com
us1https://us1.platform.bird.comhttps://mtls.us1.platform.bird.com

क्लाइंट प्रमाणपत्र आपके क्रेडेंशियल की जगह नहीं लेता। हर अनुरोध को अब भी Authorization हेडर में एक API कुंजी, एक OAuth टोकन या सर्विस अकाउंट टोकन भेजना होता है।

मोड वर्कस्पेस की एक सेटिंग है। यह तय करता है कि कौन-सा एंडपॉइंट इस वर्कस्पेस के लिए API कुंजी, OAuth टोकन या सर्विस अकाउंट टोकन वाले अनुरोध स्वीकार करता है।

मोडमानक एंडपॉइंटmTLS एंडपॉइंट
disabledअनुरोध स्वीकार करता हैअनुरोध अस्वीकार करता है
evaluatingअनुरोध स्वीकार करता हैमान्य क्लाइंट प्रमाणपत्र वाले अनुरोध स्वीकार करता है
enforcedअनुरोध अस्वीकार करता हैमान्य क्लाइंट प्रमाणपत्र वाले अनुरोध स्वीकार करता है

मोड इस ट्रैफ़िक पर लागू होता है। बाकी सब कुछ हर मोड में काम करता रहता है।

ट्रैफ़िकenforced मोड
API कुंजी, OAuth टोकन या सर्विस अकाउंट टोकन वाले API अनुरोधमानक एंडपॉइंट उन्हें E02090 के साथ अस्वीकार करता है।
SMTP सबमिशनअस्वीकार किया जाता है। SMTP क्लाइंट सर्टिफ़िकेट प्रस्तुत नहीं कर सकता।
होस्ट किया गया MCP सर्वरवर्कस्पेस तक नहीं पहुँच सकता। यह आपका क्लाइंट सर्टिफ़िकेट प्रस्तुत नहीं कर सकता।
डैशबोर्ड सत्रकोई असर नहीं।
Automationsइस पर कोई असर नहीं पड़ता।
संगठन के ऑपरेशनों पर संगठन क्रेडेंशियल वाले अनुरोधइनकी जाँच नहीं होती। मोड किसी वर्कस्पेस का होता है, और इन अनुरोधों में किसी वर्कस्पेस का नाम नहीं होता।
SIP ट्रंकइन पर कोई असर नहीं पड़ता। ट्रंक बिना सर्टिफ़िकेट के, अनुमत API कुंजी से कॉल का प्रमाणीकरण करता रहता है।

मोड में बदलाव नए अनुरोधों पर तुरंत लागू होता है। खुले SMTP सत्र पर नया मोड उसके अगले संदेश से लागू होता है।

मान्य क्लाइंट प्रमाणपत्र की शृंखला वर्कस्पेस के किसी CA तक पहुँचती है, वह अपनी वैधता अवधि के भीतर होता है और उसमें clientAuth विस्तारित कुंजी उपयोग होता है। यदि आप आवश्यक सब्जेक्ट अल्टरनेटिव नेम (SAN) सेट करते हैं, तो प्रमाणपत्र में वह भी होना चाहिए। हम DNS नामों और URI की तुलना करते हैं। हम कॉमन नेम का उपयोग नहीं करते।

अपना प्रमाणपत्र प्राधिकरण जोड़ें

  1. Workspace settings > mTLS खोलें।
  2. Certificate authorities में Add certificate authority चुनें।
  3. अपने CA का PEM प्रमाणपत्र पेस्ट करें, या कोई फ़ाइल चुनें।
  4. Add certificate authority चुनें।

प्रमाणपत्र में CA:true बेसिक कंस्ट्रेंट और keyCertSign कुंजी उपयोग होना चाहिए, और उसकी समय-सीमा समाप्त नहीं होनी चाहिए। एक वर्कस्पेस में दो CA हो सकते हैं।

यदि आपका CA दूसरे पक्षों को भी प्रमाणपत्र जारी करता है, तो Required subject alternative name को उस पहचान पर सेट करें जो आपके क्लाइंट प्रमाणपत्रों में होती है।

मूल्यांकन मोड में परीक्षण करें

  1. Mode में Evaluating चुनें, फिर Save चुनें।
  2. अपने क्लाइंट को इस तरह कॉन्फ़िगर करें कि वह अपना प्रमाणपत्र प्रस्तुत करे। यदि क्लाइंट प्रमाणपत्र पर कोई मध्यवर्ती CA हस्ताक्षर करता है, तो मध्यवर्ती प्रमाणपत्र भी भेजें।
  3. अपने क्लाइंट का बेस URL बदलकर mTLS एंडपॉइंट करें।
  4. एक परीक्षण अनुरोध भेजें:
कोड उदाहरण
curl https://mtls.eu1.platform.bird.com/v1/workspace \
  --cert client.pem \
  --key client.key \
  -H "Authorization: Bearer $BIRD_API_KEY"

401 के अलावा कोई भी प्रतिक्रिया दिखाती है कि प्रमाणपत्र की जाँच सफल रही। 401 प्रतिक्रिया में एक त्रुटि कोड होता है। समस्या निवारण में हर कोड का कारण दिया गया है।

जिन कॉलर को enforced मोड अस्वीकार कर देगा, उन्हें खोजने के लिए वर्कस्पेस के अनुरोध लॉग को mTLS missing पर फ़िल्टर करें। अनुरोध लॉग लिखने वाले अनुरोध दर्ज करते हैं, जैसे POST, PATCH और DELETE अनुरोध, और SMTP सबमिशन। वे पढ़ने वाले अनुरोध दर्ज नहीं करते, इसलिए केवल पढ़ने वाले क्लाइंट की जाँच अलग से करें: enforced मोड उन्हें भी अस्वीकार करता है।

mTLS लागू करें

  1. हर इंटीग्रेशन को mTLS एंडपॉइंट पर ले जाएँ।
  2. Mode में Enforced चुनें, फिर Save चुनें।

इसके बाद मानक एंडपॉइंट इस वर्कस्पेस के लिए API कुंजी, OAuth टोकन या सर्विस अकाउंट टोकन वाले अनुरोधों को E02090 के साथ अस्वीकार करता है।

होस्ट किया गया MCP सर्वर वर्कस्पेस तक नहीं पहुँच सकता। इसके बजाय Bird CLI का स्थानीय MCP सर्वर उपयोग करें।

SMTP एंडपॉइंट 535 5.7.8 वाले वर्कस्पेस के लिए AUTH अस्वीकार करता है। खुले SMTP सत्र को अगले संदेश पर 530 5.7.0 मिलता है। इसके बजाय mTLS एंडपॉइंट पर API के ज़रिए ईमेल भेजें।

CA या आवश्यक SAN में किया गया बदलाव हर अनुरोध पर लागू होने में 15 मिनट तक ले सकता है।

Bird CLI का उपयोग करें

Bird CLI और उसका स्थानीय MCP सर्वर (bird mcp) इन सेटिंग के साथ आपका क्लाइंट सर्टिफ़िकेट प्रस्तुत करते हैं:

सेटिंगफ़्लैगएनवायरनमेंट वेरिएबल
सर्टिफ़िकेट चेन, PEM, लीफ़ सबसे पहले--client-certBIRD_CLIENT_CERT
निजी कुंजी, PEM, एन्क्रिप्ट न की हुई--client-keyBIRD_CLIENT_KEY
अनुरोध mTLS एंडपॉइंट पर भेजें--mtlsBIRD_MTLS=1
कोड उदाहरण
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls

OAuth लॉगिन के साथ ये सेटिंग सहेजे रखने के लिए, तीनों फ़्लैग bird auth login को दें। प्रोफ़ाइल फ़ाइल पाथ सहेजती है, और बाद के कमांड बिना फ़्लैग के mTLS एंडपॉइंट का उपयोग करते हैं। bird auth status सर्टिफ़िकेट का SHA-256 फ़िंगरप्रिंट और उसकी समाप्ति तिथि दिखाता है।

SDK का उपयोग करें

SDK को अपनी सर्टिफ़िकेट चेन (PEM, लीफ़ सबसे पहले) और उसकी निजी कुंजी (PEM, एन्क्रिप्ट न की हुई) के पाथ दें। SDK हर अनुरोध पर सर्टिफ़िकेट प्रस्तुत करता है और अनुरोध आपकी API कुंजी के क्षेत्र के mTLS एंडपॉइंट पर भेजता है। अगर आप बेस URL सेट करते हैं, तो SDK उसी URL का उपयोग करता है।

अगर आप सर्टिफ़िकेट के साथ अपना HTTP क्लाइंट भी देते हैं, तो SDK उसे अस्वीकार करता है। अपना HTTP क्लाइंट इस्तेमाल करने के लिए, उस क्लाइंट पर सर्टिफ़िकेट कॉन्फ़िगर करें और बेस URL को mTLS एंडपॉइंट पर सेट करें।

// Node.js only. Install the optional undici dependency if your package manager skipped it.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  clientCertificate: { cert: "client.pem", key: "client.key" },
});

const workspace = await bird.workspace.get();
console.log(workspace.id);

वेबहुक डिलीवरी पर क्लाइंट प्रमाणपत्र प्रस्तुत करें

हम एक RSA 2048 कुंजी जोड़ी और CN=<workspace ID>, O=Bird विषय वाला एक CSR बनाते हैं। निजी कुंजी हमारे पास रहती है। आपका CA इस CSR पर हस्ताक्षर करता है, और जब आपका रिसीवर प्रमाणपत्र माँगता है, तब हम हस्ताक्षरित प्रमाणपत्र प्रस्तुत करते हैं।

हम वेबहुक सब्सक्रिप्शन और सीधे कॉलबैक पर, फिर से प्रयासों सहित, प्रमाणपत्र प्रस्तुत करते हैं। इन डिलीवरी में प्रमाणपत्र प्रस्तुत नहीं किया जाता:

  • realtime.* इवेंट
  • कनेक्टर एंडपॉइंट
  • MCP Events सब्सक्रिप्शन
मोडडिलीवरी का व्यवहार
disabledहम कोई सर्टिफ़िकेट प्रस्तुत नहीं करते।
evaluatingरिसीवर के माँगने पर हम सर्टिफ़िकेट प्रस्तुत करते हैं। अगर रिसीवर उसे अस्वीकार करता है, तो हम उसके बिना फिर से डिलीवर करते हैं।
enforcedहम सर्टिफ़िकेट प्रस्तुत करते हैं। अगर रिसीवर उसे नहीं माँगता या अस्वीकार करता है, तो डिलीवरी का प्रयास विफल हो जाता है।

सर्टिफ़िकेट पर हस्ताक्षर करवाएँ और उसे अपलोड करें

  1. Webhooks > mTLS खोलें।
  2. Certificate में Create signing request चुनें।
  3. Signing request में Download चुनें।
  4. अपने CA से CSR को clientAuth एक्सटेंडेड की यूसेज के साथ साइन करवाएँ।
  5. Upload certificate चुनें।
  6. पहले साइन किया गया प्रमाणपत्र पेस्ट करें, फिर हर मध्यवर्ती प्रमाणपत्र क्रम से। आप फ़ाइल भी चुन सकते हैं।
  7. Upload certificate चुनें।

हम जाँचते हैं कि प्रमाणपत्र साइनिंग अनुरोध की कुंजी से मेल खाता है, उसमें clientAuth एक्सटेंडेड की यूसेज है और वह अपनी वैधता अवधि के भीतर है। इसके बाद Certificate सेक्शन उसका सब्जेक्ट, जारीकर्ता, सीरियल नंबर, SHA-256 फ़िंगरप्रिंट और वैधता अवधि दिखाता है।

अपने रिसीवर कॉन्फ़िगर करें

  1. TLS हैंडशेक के दौरान क्लाइंट प्रमाणपत्र का अनुरोध करें।
  2. उस CA पर भरोसा करें जिसने हमारा प्रमाणपत्र साइन किया है।
  3. किसी सार्वजनिक रूप से भरोसेमंद CA का ऐसा सर्वर प्रमाणपत्र प्रस्तुत करें जो रिसीवर के होस्टनेम से मेल खाता हो।

केवल हमारा प्रमाणपत्र स्वीकार करने और आपके CA के किसी दूसरे प्रमाणपत्र को अस्वीकार करने के लिए, सब्जेक्ट CN=<workspace ID> या SHA-256 फ़िंगरप्रिंट का मिलान करें।

वेबहुक mTLS लागू करें

  1. Mode में Evaluating चुनें, फिर Save चुनें।
  2. POST /v1/webhooks/{webhook_id}/test से हर वेबहुक पर एक टेस्ट इवेंट भेजें। पक्का करें कि client_certificate का मान presented है। not_requested का अर्थ है कि रिसीवर ने सर्टिफ़िकेट नहीं माँगा, और rejected का अर्थ है कि उसने सर्टिफ़िकेट स्वीकार नहीं किया।
  3. SMS कॉलबैक URL के लिए, जिनकी कोई वेबहुक ID नहीं होती, options.callback_url को रिसीवर पर सेट करके एक SMS भेजें। रिसीवर के लॉग देखें और पक्का करें कि कॉलबैक हमारा सर्टिफ़िकेट प्रस्तुत करता है। evaluating में अस्वीकार किया गया सर्टिफ़िकेट GET /v1/webhook-callbacks/attempts में भी failure_reason के साथ विफल प्रयास के रूप में दिखता है।
  4. Mode में Enforced चुनें, फिर Save चुनें।

enforced मोड में अस्वीकार किया गया सर्टिफ़िकेट वेबहुक के डिलीवरी प्रयासों में विफल प्रयास के रूप में दिखता है।

रद्दीकरण की जाँच करें

सर्टिफ़िकेट रद्दीकरण सूचियों (CRL) से रद्दीकरण की जाँच करने के लिए Certificate revocation list check को Full chain पर सेट करें।

  • API अनुरोधों पर हम क्लाइंट सर्टिफ़िकेट और आपके CA के नीचे के हर इंटरमीडिएट सर्टिफ़िकेट की जाँच करते हैं।
  • वेबहुक डिलीवरी पर हम आपके रिसीवर के सर्वर सर्टिफ़िकेट और उसके रूट के नीचे के हर इंटरमीडिएट सर्टिफ़िकेट की जाँच करते हैं।

हम सर्टिफ़िकेट के हर CRL डिस्ट्रिब्यूशन पॉइंट की जाँच करते हैं। एक डिस्ट्रिब्यूशन पॉइंट के http और https URI एक ही CRL की प्रतियाँ हैं, और जो प्रति पहले जवाब देती है, हम उसी का उपयोग करते हैं। जिस डिस्ट्रिब्यूशन पॉइंट में http या https URI नहीं है, वह जाँच में विफल होता है। जिस सर्टिफ़िकेट में कोई CRL डिस्ट्रिब्यूशन पॉइंट नहीं है, उसकी जाँच नहीं होती। हम हर CRL के हस्ताक्षर का सत्यापन करते हैं। अगर हमें मान्य CRL नहीं मिलती, तो हम अनुरोध अस्वीकार कर देते हैं या डिलीवरी प्रयास विफल कर देते हैं।

सीमामान
CRL डाउनलोड समयहर डाउनलोड के लिए 5 सेकंड, हर अनुरोध के लिए 10 सेकंड
CRL का आकार10 MiB
हर वर्कस्पेस के लिए CRLAPI अनुरोधों के लिए 10 और वेबहुक डिलीवरी के लिए 10

सर्टिफ़िकेट बदलें

किसी CA या वेबहुक क्लाइंट सर्टिफ़िकेट की समय-सीमा खत्म होने से 30 दिन और 7 दिन पहले हम वर्कस्पेस के संपर्कों को ईमेल भेजते हैं।

API अनुरोधों के लिए CA बदलने के लिए:

  1. नया CA जोड़ें। अब वर्कस्पेस दोनों CA पर भरोसा करता है।
  2. हर इंटीग्रेशन को नए CA से जारी क्लाइंट सर्टिफ़िकेट पर ले जाएँ।
  3. पुराना CA हटाएँ।

जब मोड evaluating या enforced हो, तब आप आखिरी CA नहीं हटा सकते। Bird में आपके CA से जारी क्लाइंट प्रमाणपत्रों के लिए कुछ करने की ज़रूरत नहीं है।

वेबहुक क्लाइंट प्रमाणपत्र बदलने के लिए:

  1. Create new signing request चुनें।
  2. नए CSR पर हस्ताक्षर करवाएँ और प्रमाणपत्र अपलोड करें।

जब तक आप नया प्रमाणपत्र अपलोड नहीं करते, मौजूदा प्रमाणपत्र ही इस्तेमाल होता रहता है। टेस्ट भेजने में नया प्रमाणपत्र तुरंत इस्तेमाल होता है, लेकिन डिलीवरी कुछ मिनट तक पिछला प्रमाणपत्र प्रस्तुत करती रह सकती है। तब तक आपके रिसीवर को दोनों प्रमाणपत्र, CA या फ़िंगरप्रिंट के आधार पर, स्वीकार करने होंगे।

API से स्वचालित करें

डैशबोर्ड की हर कार्रवाई के लिए एक API ऑपरेशन है। ये कॉल ऐसे एंडपॉइंट पर भेजें जिसे आपका मोड स्वीकार करता हो: disabled या evaluating मोड में मानक एंडपॉइंट पर, और enforced मोड में क्लाइंट प्रमाणपत्र के साथ mTLS एंडपॉइंट पर। API कुंजी को access_restrictions स्कोप में लिखने की अनुमति चाहिए। संगठन की मास्टर कुंजियाँ इन ऑपरेशनों का उपयोग नहीं कर सकतीं।

ऑपरेशनकार्रवाई
PATCH /v1/workspace/mtls-settingsstate, expected_san या crl_check बदलें
POST /v1/workspace/mtls-certificate-authoritiesएक CA जोड़ें
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}एक CA हटाएँ
PATCH /v1/workspace/webhook-client-certificatestate या crl_check बदलें
POST /v1/workspace/webhook-client-certificate/signing-requestएक CSR बनाएँ
POST /v1/workspace/webhook-client-certificate/certificateहस्ताक्षरित प्रमाणपत्र अपलोड करें
कोड उदाहरण
curl -X PATCH https://eu1.platform.bird.com/v1/workspace/mtls-settings \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"state": "enforced", "crl_check": "full_chain"}'

समस्या निवारण

जो API अनुरोध किसी जाँच में विफल होते हैं, वे इनमें से किसी एक कोड के साथ 401 लौटाते हैं:

कोडकारण
E02086अनुरोध ने कोई क्लाइंट सर्टिफ़िकेट प्रस्तुत नहीं किया।
E02087क्लाइंट सर्टिफ़िकेट इस वर्कस्पेस के लिए मान्य नहीं है।
E02088चेन का कोई सर्टिफ़िकेट रद्द कर दिया गया है।
E02089मोड disabled है, इसलिए mTLS एंडपॉइंट अनुरोध को अस्वीकार करता है।
E02090मोड enforced है, इसलिए स्टैंडर्ड एंडपॉइंट अनुरोध को अस्वीकार करता है।
E02091हम 5 सेकंड के भीतर CRL डाउनलोड नहीं कर सके।
E02092कोई CRL 10 MiB से बड़ी है।
E02093वर्कस्पेस पहले से 10 CRL का उपयोग कर रहा है।
E02094किसी CRL का हस्ताक्षर अमान्य है या उसके अगले अपडेट का समय बीत चुका है।

सेटिंग बदलने पर इनमें से कोई कोड लौट सकता है:

  • E10027: वर्कस्पेस के लिए API mTLS चालू नहीं है। इसे चालू करवाने के लिए अपने Bird प्रतिनिधि से संपर्क करें।
  • E10028: वर्कस्पेस के लिए वेबहुक mTLS चालू नहीं है। इसे चालू करवाने के लिए अपने Bird प्रतिनिधि से संपर्क करें।

अगले चरण

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।