ऑथेंटिकेशन
सभी IDCloud API (Web & SDK और API कॉन्ट्रैक्ट) OAuth2 with JWT Bearer Grant Type (RFC 7523) का इस्तेमाल करते हैं। आप अपने बैक-एंड पर एक अल्पकालिक JWT असर्शन जनरेट करते हैं, इसे एक Bearer टोकन के लिए एक्सचेंज करते हैं, और उस टोकन का इस्तेमाल हर आगे की कॉल में करते हैं।
JWT असर्शन केवल आपके बैक-एंड पर जनरेट होना चाहिए। अपनी प्राइवेट key को फ्रंट-एंड कोड, मोबाइल ऐप, रिपॉज़िटरी, या लॉग में कभी उजागर न करें।
क्रेडेंशियल प्राप्त करना
टोकन जनरेट करने से पहले, आपको Unico द्वारा प्रोविज़न किया गया एक सर्विस अकाउंट चाहिए। Unico सप ोर्ट से संपर्क करें और यह जानकारी दें:
- सर्विस अकाउंट का नाम (अधिकतम 12 अक्षर)
- ज़िम्मेदार व्यक्ति का नाम, ईमेल और फ़ोन (केवल ब्राज़ील, US या मेक्सिको नंबर)
आपको यह प्राप्त होगा:
- यूनीक अकाउंट नाम
- टेनेंट ID
- बेस JWT पेलोड
- प्राइवेट key फ़ाइल (
.pemफ़ॉर्मेट)
UAT और Production के लिए अलग-अलग सर्विस अकाउंट रखें।
JWT असर्शन बनाना
असर्शन कॉम्पैक्ट JWS फ़ॉर्मेट में एक JWT है: {Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}।
{
"alg": "RS256",
"typ": "JWT"
}
| Claim | Value | Notes |
|---|---|---|
iss | <account_name>@<tenant_id>.iam.acesso.io | आपके क्रेडेंशियल के साथ दिया गया |
aud | https://identityhomolog.acesso.io (UAT) या https://identity.acesso.io (Production) | टोकन एंडपॉइंट होस्ट से मेल खाना चाहिए |
scope | * | सभी परमिशन देता है |
iat | Unix टाइमस्टैंप (सेकंड) | JWT जारी होने का समय |
exp | iat + अधिकतम 3600 | iat से 1 घंटे से ज़्यादा नहीं हो सकता |
{
"aud": "https://identity.acesso.io",
"scope": "*",
"iat": 1738086000,
"exp": 1738089600
}
Unico द्वारा दी गई .pem प्राइवेट key के साथ RS256 (RSA + SHA-256) का इस्तेमाल करके header + payload पर हस्ताक्षर करें।
ऊपर सूचीबद्ध न किया गया कोई भी फ़ील्ड (जैसे sub, jti, nbf) 1.2.22 त्रुटि क ा कारण बनेगा। केवल दिखाए गए claim का इस्तेमाल करें।
टोकन का अनुरोध करना
टोकन एंडपॉइंट दोनों कॉन्ट्रैक्ट के लिए एक जैसा है:
| Environment | Endpoint |
|---|---|
| Production | POST https://identity.acesso.io/oauth2/token |
| UAT | POST https://identityhomolog.acesso.io/oauth2/token |
| Parameter | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
grant_type | urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | आपका हस्ताक्षरित JWT |
- cURL
- Node.js
- Python
curl -X POST https://identity.acesso.io/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
-d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
import jwt from 'jsonwebtoken';
import fs from 'fs';
import qs from 'querystring';
const privateKey = fs.readFileSync('./private-key.pem');
const now = Math.floor(Date.now() / 1000);
const assertion = jwt.sign(
{
aud: 'https://identity.acesso.io',
scope: '*',
iat: now,
exp: now + 3600,
},
privateKey,
{ algorithm: 'RS256' }
);
const res = await fetch('https://identity.acesso.io/oauth2/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: qs.stringify({
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion,
}),
});
const { access_token, expires_in } = await res.json();
import time
import jwt # PyJWT
import requests
with open("private-key.pem", "rb") as f:
private_key = f.read()
now = int(time.time())
assertion = jwt.encode(
{
"aud": "https://identity.acesso.io",
"scope": "*",
"iat": now,
"exp": now + 3600,
},
private_key,
algorithm="RS256",
)
response = requests.post(
"https://identity.acesso.io/oauth2/token",
data={
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": assertion,
},
)
token_data = response.json()
access_token = token_data["access_token"]
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
| Field | Type | Description |
|---|---|---|
access_token | string | JWT एक्सेस टोकन। सभी API कॉल में Authorization: Bearer <token> में इस्तेमाल करें। |
expires_in | integer | सेकंड में एक्सपायरेशन समय। उदाहरण: 3600। |
token_type | string | हमेशा Bearer। |
टोकन का इस्तेमाल करना
टोकन को हर API रिक्वेस्ट के Authorization हेडर में जोड़ें। दोनों कॉन्ट्रैक्ट के लिए हेडर एक जैसा है — जो अलग है वह है आप जिस API को कॉल क र रहे हैं उसका होस्ट और पाथ:
| Contract | Production host | UAT host |
|---|---|---|
| Web & SDK | https://api.idcloud.unico.app | https://api.idcloud.uat.unico.app |
| API | https://api.id.unico.app | https://api.id.uat.unico.app |
Web & SDK — यहाँ केवल Authorization ही ज़रूरी ऑथ हेडर है:
curl -X POST https://api.idcloud.unico.app/client/v1/process \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'
API — Authorization का इस्तेमाल APIKEY हेडर के साथ किया जाता है:
curl -X POST https://api.id.unico.app/processes/v1 \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "APIKEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ ... }'
टोकन का नवीनीकरण
टोकन 3600 सेकंड के बाद एक्सपायर हो जाते हैं। अपने बैक-एंड में सक्रिय नवीनीकरण लागू करें:
- टोकन रिस्पॉन्स से
expires_inको ट्रैक करें और एक्सपायरी टाइमस्टैंप स्टोर करें। - एक्सपायरेशन से 10 मिनट या उससे कम समय बचे रहने पर नया टोकन माँगें।
- प्रोडक्शन में नवीनीकरण ट्रिगर करने के लिए कभी भी
401का इंतज़ार न करें।
API संदर्भ
टोकन एंडपॉइंट के लिए पूरा OpenAPI स्पेसिफ़िकेशन authentication.yaml में उपलब्ध है।
| Method | Path | Description |
|---|---|---|
POST | /oauth2/token | हस्ताक्षरित JWT असर्शन को Bearer एक्सेस टोकन के लिए एक्सचेंज करें |
त्रुटि कोड
| Code | Description | Action |
|---|---|---|
1.0.1 | iss के गठन में दिया गया ID गलत है | जाँचें कि iss फ़ील्ड उस टेनेंट ID से मेल खाता है जो प्राइवेट key जनरेट होने पर दिया गया था |
1.0.14 | एप्लिकेशन सक्रिय नहीं है | प्रोजेक्ट मैनेजर से जाँचें कि इस्तेमाल किया जा रहा एप्लिकेशन सक्रिय है या नहीं |
1.1.1 | scope पैरामीटर नहीं दिया गया था | अपने JWT पेलोड में "scope": "*" जोड़ें |
1.2.4 | JWT असर्शन अमान्य | JWT असर्शन अब मान्य नहीं है। दो कारण: (a) वर्तमान समय exp से आगे निकल चुका है (JWT वाकई एक्सपायर हो चुका है — हर टोकन रिक्वेस्ट के लिए एक ताज़ा असर्शन जनरेट करें); या (b) exp, iat + 3600 से ज़्यादा है (लाइफ़टाइम बहुत लंबा है — exp को iat + 3600 पर सीमित करें)। |
1.2.5 | JWT वैलिडेशन फ़ेल हुआ | JWT को वैलिडेट नहीं किया जा सका। पैरामीटर जाँचें और सुनिश्चित करें कि इसे RS256 और सही प्राइवेट key से हस्ताक्षरित किया गया था |
1.2.6 | प्राइवेट key अब मान्य नहीं है | JWT पर हस्ताक्षर करने के लिए इस्तेमाल की गई प्राइवेट key अब स्वीकार्य नहीं है। अकाउंट के लिए नए क्रेडेंशियल का अनुरोध करें |
1.2.7 | JWT पहले ही इस्तेमाल हो चुका है | JWT अब स्वीकार्य नहीं है क्योंकि यह पहले ही इस्तेमाल हो चुका है। हर टोकन रिक्वेस्ट के लिए एक नया असर्शन जनरेट करें |
1.2.11 | अकाउंट सक्रिय नहीं है | इस्तेमाल किया गया अकाउंट सक्रिय नहीं है |
1.2.14 | अकाउंट में ज़रूरी परमिशन नहीं है | इस्तेमाल किए गए अकाउंट के पास ज़रूरी परमिशन नहीं हैं |
1.2.18 | अकाउंट अस्थायी रूप से लॉक है | अमान्य ऑथेंटिकेशन प्रयासों की संख्या पार करने के कारण अकाउंट अस्थायी रूप से लॉक कर दिया गया है |
1.2.19 | अनधिकृत यूज़र इंपर्सनेशन | JWT में एक sub claim है जो ऐसे अकाउंट की ओर इशारा करता है जिसे इंपर्सनेशन के लिए अधिकृत नहीं किया गया है। पेलोड से sub claim हटाएँ। |
1.2.20 | JWT डिकोडिंग फ़ेल हुई | JWT को डिकोड करने में विफल। टोकन का फ़ॉर्मेट जाँचें और यह कि इसे RS256 से हस्ताक्षरित किया गया था। |
1.2.21 | गलत प्राइवेट key / ऑथेंटिकेशन फ़ेल | JWT हस्ताक्षर को इस अकाउंट के लिए किसी भी ज्ञात key के मुक़ाबले वेरीफ़ाई नहीं किया जा सका। जाँचें कि आप इस सर्विस अकाउंट और एनवायरनमेंट के लिए सही .pem प्राइवेट key इस्तेमाल कर रहे हैं। |
1.2.22 | पेलोड में अस्वीकृत फ़ील्ड | JWT में अतिरिक्त पेलोड फ़ील्ड हैं जिनकी अनुमति नहीं है। इस गाइड में सूचीबद्ध न किए गए किसी भी claim (जैसे sub, jti, nbf) को हटाएँ। ध्यान दें: यदि आपने एक sub claim शामिल किया था और इसके बजाय 1.2.19 प्राप्त हुआ, तो वह त्रुटि प्राथमिकता लेती है। |
1.3.1 | IP एक्सेस प्रतिबंध | आपका IP इस अकाउंट के लिए allowlist में नहीं है |
1.3.2 | समय-आधारित एक्सेस प्रतिबंध | रिक्वेस्ट इस अकाउंट के लिए अनुमत समय विंडो से बाहर है |
आगे क्या
- Environments — sandbox बनाम production होस्ट
- Web & SDK — Create Process — ऑथेंटिकेशन के बाद पहली कॉल
- API — Create Process — ऑथेंटिकेशन के बाद पहली कॉल
- SSO / SAML — ऊपर दिए गए सर्वर-टू-सर्वर फ़्लो के बजाय, अपने ही आइडेंटिटी प्रोवाइडर के साथ अपने यूज़र को Unico के प्रोडक्ट पोर्टल में ऑथेंटिकेट करें