API को प्रमाणित अनुरोध भेजने की तैयारी
एक service account बनाने और कॉन्फ़िगर करने के बाद, आपके एप्लिकेशन को निम्नलिखित चरण पूरे करने होंगे:
- एक JSON Web Token (JWT) बनाएं, जिसमें header, payload, और signature शामिल हों;
- OAuth2 प्रमाण ीकरण प्लेटफ़ॉर्म से एक access token (
AccessToken) का अनुरोध करें; - प्रमाणीकरण प्लेटफ़ॉर्म द्वारा लौटाई गई JSON प्रतिक्रिया को हैंडल करें।
यदि प्रतिक्रिया में एक access token शामिल है, तो आप इसका उपयोग Unico के उन प्रोडक्ट APIs के लिए अनुरोध करने में कर सकते हैं जिनके लिए service account के पास access permissions हैं। (यदि प्रतिक्रिया में access token शामिल नहीं है, तो हो सकता है कि आपका JWT और token अनुरोध गलत हो, या service account के पास अनुरोधित संसाधनों तक पहुंचने के लिए आवश्यक permissions न हों।)
ऊपर बताए गए अनुरोध में जनरेट किया गया access token डिफ़ॉल्ट रूप से 3600 सेकंड के लिए वैध होता है, लेकिन यह आपकी कंपनी के लिए सेट किए गए सुरक्षा कॉन्फ़िगरेशन के आधार पर भिन्न हो सकता है। जब access token समाप्त हो जाए, तो आपके एप्लिकेशन को एक नया JWT जनरेट करना चाहिए, उसे साइन करना चाहिए, और प्रमाणीकरण प्लेटफ़ॉर्म से एक नए access token का अनुरोध करना चाहिए।
1 — JWT बनाना
एक JWT में तीन भाग होते हैं: एक header, एक payload, और एक signature। header और payload JSON ऑब्जेक्ट होते हैं। इन JSON ऑब्जेक्ट्स को UTF-8 में सीरियलाइज़ किया जाता है और फिर Base64url एन्कोडिंग¹ का उपयोग करके एन्कोड किया जाता है। यह एन्कोडिंग बार-बार एन्कोडिंग ऑपरेशन किए जाने की स्थिति में एन्कोडिंग परिवर्तनों के विरुद्ध लचीलापन प्रदान करती है। header, payload, और signature को एक पीरियड (.) कैरेक्टर के साथ जोड़ा जाता है।
एक JWT इस प्रकार बनाया जाता है:
{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}
signature के लिए आधार टेक्स्ट इस प्रकार बनाया जाता है:
{Header in Base64url}.{Payload in Base64url}
1.1 — JWT Header बनाना
header में दो फ़ील्ड होते हैं जो साइनिंग एल्गोरिदम और token फ़ॉर्मेट निर्दिष्ट करते हैं। दोनों फ़ील्ड अनिवार्य हैं, और प्रत्येक फ़ील्ड का केवल एक ही मान होता है। Service accounts RSA SHA-256 एल्गोरिदम और JWT token फ़ॉर्मेट पर निर्भर करते हैं। परिणामस्वरूप, header का JSON प्रतिनिधित्व इस प्रकार है:
{"alg":"RS256","typ":"JWT"}
Base64url प्रतिनिधित्व इस प्रकार है:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
1.2 — JWT Payload बनाना
JWT payload में JWT के बारे में जानकारी होती है, जिसमें अनुरोधित permissions (scopes), access का अनुरोध करने वाला अकाउंट, issuer, वह समय जब token जारी किया गया था, और token की lifetime शामिल होती है। अधिकांश फ़ील्ड अनिवार्य हैं। JWT header की तरह ही, payload भी एक JSON ऑब्जेक्ट है और इसका उपयोग signature की संरचना में किया जाता है।
1.3 — अनिवार्य फ़ील्ड
JWT में अनिवार्य फ़ील्ड नीचे दी गई तालिका में दिखाए गए हैं। ये payload के भीतर किसी भी क्रम में दिखाई दे सकते हैं।
| Name | Description |
|---|---|
iss | कंपनी के भीतर service account का आइडेंटिफायर। |
scope | उन permissions की एक स्पेस-डिलिमिटेड या प्लस साइन (+) सूची जिनका एप्लिकेशन अनुरोध कर रहा है। यदि अकाउंट की सभी permissions आवश्यक हैं, तो इसके लिए एस्टेरिस्क (*) सिंबल का उपयोग करें। |
aud | access token जारी करने वाले प्रमाणीकरण प्लेटफ़ॉर्म का पता। यह मान हमेशा बिल्कुल https://identityhomolog.acesso.io होना चाहिए। सामान्य समस्याएं जो काम नहीं करतीं: ट्रेलिंग स्लैश जोड़ना (https://identityhomolog.acesso.io/), या HTTPS के बजाय HTTP का उपयोग करना। |
exp | token की समाप्ति समय, 1 जनवरी, 1970, 00:00:00 UTC से सेकंड में निर्दिष्ट। इस मान की अधिकतम अवधि JWT जारी करने के समय के 1 घंटे बाद तक है। यह numeric होना चाहिए — "1524161193" जैसा quoted मान एक string है और काम नहीं करेगा; 1524161193 एक number है और काम करेगा। |
iat | JWT जारी करने का समय, 1 जनवरी, 1970, 00:00:00 UTC से सेकंड में निर्दिष्ट। यह मान numeric होना चाहिए, exp के समान नियम। |
iat फ़ील्ड को आवश्यक फ़ॉर्मेट में वर्तमान समय को दर्शाना चाहिए, और exp फ़ील्ड को निम्नलिखित गणना का पालन करना चाहिए:
exp = iat + 3600
JWT payload में अनिवार्य JSON फ़ील्ड का प्रतिनिधित्व इस प्रकार है:
{
"iss": "service_account_name@tenant_id.iam.acesso.io",
"aud": "https://identityhomolog.acesso.io",
"scope": "*",
"exp": 1626296976,
"iat": 1626293376
}
1.4 — Signature की गणना करना
**JSON Web Signature (JWS)**² विनिर्देश वह तंत्र है जो JWT के लिए signature की गणना का मार्गदर्शन करता है। signature गणना के लिए इनपुट कंटेंट निम्नलिखित कंटेंट का बाइट array है:
{Header in Base64url}.{Payload in Base64url}
signature की गणना के लिए JWT header में निर्दिष्ट उसी एल्गोरिदम का उपयोग किया जाना चाहिए। OAuth2 प्रमाणीकरण प्लेटफ़ॉर्म द्वारा समर्थित एकमात्र signature एल्गोरिदम SHA-256 का उपयोग करते हुए RSA है, जिसे JWT header के alg फ़ील्ड में RS256 के रूप में व्यक्त किया जाता है।
इनपुट कंटेंट के UTF-8 प्रतिनिधित्व को SHA256withRSA (जिसे SHA-256 हैश के साथ RSASSA-PKCS1-V1_5-SIGN भी कहा जाता है) का उपयोग करके उस private key से साइन करें जो service account के लिए बनाई और जुड़ी गई थी (ईमेल द्वारा प्राप्त अनुरोध से जनरेट की गई .key.pem फ़ाइल)। आउटपुट कंटेंट एक बाइट array होगा।
फिर signature को Base64url में एन्कोड किया जाना चाहिए। header, payload, और signature को एक पीरियड कैरेक्टर के साथ जोड़ा जाना चाहिए। परिणाम JWT होता है।
JWT बनाने के लिए पूर्व-स्थापित लाइब्रेरी का उपयोग करना भी संभव है। संदर्भ के लिए, आप jwt.io वेबसाइट पर लाइब्रेरी की एक सूची पा सकते हैं।
2 — access token के लिए अनुरोध करना
signed JWT जनरेट करने के बाद, एक एप्लिकेशन इसका उपयोग access token का अनुरोध करने के लिए कर सकता है। access token अनुरोध एक POST HTTPS अनुरोध है, और body को URL एन्कोडेड होना चाहिए। URL नीचे दिखाया गया है:
https://identityhomolog.acesso.io/oauth2/token
POST HTTPS अनुरोध में निम्नलिखित पैरामीटर अनिवार्य हैं:
| Name | Description |
|---|---|
grant_type | निम्नलिखित टेक्स्ट का उपयोग करें, आवश्यक हो तो URL-एन्कोडेड: urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | signature सहित JWT। |
POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>
3 — प्रमाणीकरण प्लेटफ़ॉर्म की प्रतिक्रिया को हैंडल करना
यदि JWT और access token अनुरोध सही ढंग से बनाए गए हैं, और service account के पास आवश्यक permissions हैं, तो प्रमाणीकरण प्लेटफ़ॉर्म एक access token युक्त JSON ऑब्जेक्ट लौटाएगा:
{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": "3600"
}
JSON ऑब्जेक्ट के access_token फ़ील्ड में लौटाया गया access token भी एक JWT token है जिसका उपयोग Unico के Products के APIs में किया जाना चाहिए। यदि अनुरोध में कोई त्रुटि होती है, तो प्रमाणीकरण त्रुटियां में त्रुटि प्रकार जांचें।
4 — Access Token की अवधि
access token की अवधि परिवर्तनशील होती है। इसकी अवधि expires_in फ़ील्ड में निर्दिष्ट होती है, जो access token के साथ लौटाई जाती है। products के सभी API calls के लिए उसी access token का उपयोग उसकी पूरी वैधता अवधि के दौरान किया जाना चाहिए।
वर्तमान token की वैधता समाप्त होने के करीब आने तक नए access token का अनुरोध न करें। हम 600 सेकंड (10 मिनट) के मार्जिन की सलाह देते हैं:
new Date((token.exp - 600) * 1000)
जहां token.exp token की समाप्ति का timestamp है।
डिफ़ॉल्ट रूप से, कंपनी को भेजा गया token 1 घंटे तक चलता है, लेकिन इसे बदला जा सकता है। सिफारिश यह है कि हमेशा expires_in को आधार के रूप में उपयोग करें और नया token अनुरोध करने के लिए इसमें से 600s घटाएं।
उदाहरण:
Standard scenario:
expires_in: 3600 (1h) - Token generated at 14:42
Request a new token only at 15:32, that is, 14:42 + (3600 - 600)
Scenario with modified duration:
expires_in: 7200 (2h) - Token generated at 14:42
Request a new token only at 16:32, that is, 14:42 + (7200 - 600)
token प्राप्त करने के लिए एक निश्चित समय का उपयोग न करें, क्योंकि प्राप्त token की अवधि स्थापित समय से कम हो सकती है, जिससे सेवाओं का उपयोग करते समय विफलताएं हो सकती हैं।
¹ BaseN एन्कोडिंग के लिए RFC 4648 के अनुसार, Base64url फ़ॉर्मेट Base64 के समान है, सिवाय इसके कि = कैरेक्टर हटा दिया जाता है, और + तथा / कैरेक्टर को क्रमशः - और _ से बदल दिया जाता है।
² JSON Web Signature: https://tools.ietf.org/html/rfc7515।