ऑथेंटिकेशन

Markdown ChatGPT Claude

सभी 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)}।

Header

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

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 घंटे से ज़्यादा नहीं हो सकता

{
  "iss": "[email protected]",
  "aud": "https://identity.acesso.io",
  "scope": "*",
  "iat": 1738086000,
  "exp": 1738089600
}

Signature

Unico द्वारा दी गई .pem प्राइवेट key के साथ RS256 (RSA + SHA-256) का इस्तेमाल करके header + payload पर हस्ताक्षर करें।

अतिरिक्त claim न जोड़ें

ऊपर सूचीबद्ध न किया गया कोई भी फ़ील्ड (जैसे 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`

Request

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(
  {
    iss: '[email protected]',
    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(
    {
        "iss": "[email protected]",
        "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"]

Response

{
  "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 के प्रोडक्ट पोर्टल में ऑथेंटिकेट करें

क्रेडेंशियल प्राप्त करना​

JWT असर्शन बनाना​

टोकन का अनुरोध करना​

टोकन का इस्तेमाल करना​

टोकन का नवीनीकरण​

API संदर्भ​

त्रुटि कोड​

आगे क्या​