Account Linking API

इस रेफ़रंस पेज में, उन एपीआई एंडपॉइंट के बारे में बताया गया है जिन्हें आपकी सेवा को लागू करना होगा. इससे Google के साथ खाता लिंक करने की सुविधा काम करेगी. इसमें OAuth लिंक करना, आसान तरीके से खाता लिंक करना, और ऐप्लिकेशन फ़्लिप करना शामिल है.

ज़रूरी शर्तें और स्टैंडर्ड

इन एंडपॉइंट को लागू करने के लिए, आपकी सेवा को इन मानकों का पालन करना होगा:

  • OAuth 2.0: RFC 6749 के मुताबिक.
  • टोकन रद्द करना: आरएफ़सी 7009 के मुताबिक होना चाहिए.
  • JSON वेब टोकन (जेडब्ल्यूटी): RFC 7519 के मुताबिक होने चाहिए. यह स्ट्रीमलाइन लिंकिंग के लिए ज़रूरी है.
  • HTTPS: सभी एंडपॉइंट को सुरक्षित एचटीटीपीएस कनेक्शन के ज़रिए ऐक्सेस किया जाना चाहिए.

ऑथराइज़ेशन एंडपॉइंट

ऑथराइज़ेशन एंडपॉइंट, उपयोगकर्ताओं की पुष्टि करने और उनके खातों को Google से लिंक करने के लिए उनकी सहमति लेने के लिए ज़िम्मेदार होता है.

  • यूआरएल: इसे Actions Console या Google Cloud Console में कॉन्फ़िगर किया जाता है.
  • तरीका: GET

अनुरोध के पैरामीटर

पैरामीटर ब्यौरा
client_id Google को असाइन किया गया क्लाइंट आईडी.
redirect_uri वह यूआरएल जिस पर आपको इस अनुरोध का जवाब भेजना है.
state यह हिसाब-किताब की ऐसी वैल्यू होती है जिसे रीडायरेक्ट यूआरआई में बिना बदलाव किए, Google को वापस भेज दिया जाता है.
response_type ऑथराइज़ेशन कोड फ़्लो के लिए, code होना ज़रूरी है.
scope (ज़रूरी नहीं) Google जिस डेटा का अनुरोध कर रहा है उसके लिए, स्पेस से अलग की गई स्कोप की सूची.
user_locale (ज़रूरी नहीं) Google खाते की भाषा की सेटिंग.इसे BCP-47 भाषा के टैग का इस्तेमाल करके तय किया जाता है. उदाहरण के लिए, en-US.
code_challenge (OAuth 2.1 के लिए ज़रूरी है) यह कोड वेरिफ़ायर से मिला चैलेंज होता है.
code_challenge_method (ज़रूरी नहीं) चुनौती पाने के लिए इस्तेमाल किया गया तरीका (जैसे, S256).

टोकन एक्सचेंज एंडपॉइंट

यह एंडपॉइंट, ऑथराइज़ेशन कोड को टोकन के लिए एक्सचेंज करने और समयसीमा खत्म हो चुके ऐक्सेस टोकन को रीफ़्रेश करने के लिए ज़िम्मेदार होता है.

  • यूआरएल: इसे Actions Console या Google Cloud Console में कॉन्फ़िगर किया जाता है.
  • तरीका: POST
  • Content-Type: application/x-www-form-urlencoded

टोकन के लिए ऑथराइज़ेशन कोड बदलना

टोकन एक्सचेंज के शुरुआती अनुरोध में इन पैरामीटर का इस्तेमाल किया जाता है.

अनुरोध के पैरामीटर

पैरामीटर ब्यौरा
client_id Google को असाइन किया गया क्लाइंट आईडी.
client_secret वह क्लाइंट सीक्रेट जिसे आपने Google को असाइन किया है.
grant_type authorization_code होना चाहिए.
code ऑथराइज़ेशन एंडपॉइंट से मिला ऑथराइज़ेशन कोड.
redirect_uri वही रीडायरेक्ट यूआरआई जिसका इस्तेमाल शुरुआती अनुरोध में किया गया था.
code_verifier (PKCE के लिए ज़रूरी है) ओरिजनल क्रिप्टोग्राफ़िक रैंडम स्ट्रिंग.

रीफ़्रेश टोकन को ऐक्सेस टोकन के लिए एक्सचेंज करना

ऐक्सेस टोकन को रीफ़्रेश करते समय, इन पैरामीटर का इस्तेमाल किया जाता है.

अनुरोध के पैरामीटर

पैरामीटर ब्यौरा
client_id Google को असाइन किया गया क्लाइंट आईडी.
client_secret वह क्लाइंट सीक्रेट जिसे आपने Google को असाइन किया है.
grant_type refresh_token होना चाहिए.
refresh_token Google को पहले जारी किया गया रीफ़्रेश टोकन.

जवाब (JSON)

HTTPS रिस्पॉन्स के मुख्य हिस्से में JSON ऑब्जेक्ट के साथ, सही रिस्पॉन्स दिखाएं.

OpenAPI 3.1 स्कीमा

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • एचटीटीपी स्टेटस: 200 OK
  • Content-Type: application/json;charset=UTF-8
फ़ील्ड ब्यौरा
token_type ज़रूरी है. bearer होना चाहिए.
access_token ज़रूरी है. यह कम समय के लिए इस्तेमाल किया जाने वाला टोकन है. इसका इस्तेमाल, आपकी सेवा के एपीआई को ऐक्सेस करने के लिए किया जाता है.
refresh_token authorization_code grant_type के लिए ज़रूरी है. यह लंबे समय तक चलने वाला टोकन है. इसका इस्तेमाल नए ऐक्सेस टोकन पाने के लिए किया जाता है.
expires_in ज़रूरी है. ऐक्सेस टोकन की बची हुई लाइफ़टाइम, सेकंड में.

गड़बड़ी के रिस्पॉन्स

अगर टोकन एंडपॉइंट का अनुरोध पूरा नहीं होता है, तो HTTP 400 Bad Request गड़बड़ी का मैसेज दिखाएं. साथ ही, JSON रिस्पॉन्स में ये फ़ील्ड शामिल करें:

  • एचटीटीपी स्टेटस: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
गड़बड़ी वाले फ़ील्ड (JSON) ब्यौरा
error ज़रूरी है. invalid_grant होना चाहिए.
error_description (ज़रूरी नहीं) ऐसा टेक्स्ट जिसे इंसान पढ़ सकें और जिसमें ज़्यादा जानकारी दी गई हो.

लिंक करने के आसान तरीके से जुड़े इंटेंट मैनेज करना

अगर आपकी सेवा आसान तरीके से खाता लिंक करने ('Google से साइन इन करें' सुविधा के साथ OAuth) की सुविधा देती है, तो आपके टोकन एक्सचेंज एंडपॉइंट को JSON Web Token (JWT) के दावे भी स्वीकार करने चाहिए. साथ ही, check, create, और get इंटेंट लागू करने चाहिए.

इन अनुरोधों में इन पैरामीटर का इस्तेमाल किया जाता है:

अनुरोध के पैरामीटर

पैरामीटर ब्यौरा
intent स्ट्रीमलाइन की गई लिंकिंग के लिए अनुरोध किया गया खास इंटेंट: check, get या create.
grant_type इन अनुरोधों के लिए, इस पैरामीटर की वैल्यू हमेशा urn:ietf:params:oauth:grant-type:jwt-bearer होती है.
assertion JSON Web Token (JWT), जो Google उपयोगकर्ता की पहचान के बारे में हस्ताक्षर किया गया दावा दिखाता है. JWT में ऐसी जानकारी होती है जिसमें उपयोगकर्ता का Google खाता आईडी, नाम, और ईमेल पता शामिल होता है.

आपके सर्वर को JWT की पुष्टि करना सेक्शन में दी गई शर्तों के हिसाब से, इस JWT की पुष्टि ज़रूर करनी चाहिए.
client_id Google को असाइन किया गया क्लाइंट आईडी.
client_secret वह क्लाइंट सीक्रेट जिसे आपने Google को असाइन किया है.
scope ज़रूरी नहीं: ऐसे स्कोप जिन्हें आपने Google को उपयोगकर्ताओं से अनुरोध करने के लिए कॉन्फ़िगर किया है. आम तौर पर, get और create इंटेंट के दौरान मौजूद होता है.
response_type create इंटेंट के लिए ज़रूरी है: इसे token पर सेट किया जाना चाहिए.

JWT की पुष्टि करना

लिंक करने की प्रोसेस को आसान और सुरक्षित बनाने के लिए, आपके सर्वर को इन शर्तों के आधार पर assertion (JWT) की पुष्टि करनी होगी:

  • हस्ताक्षर: Google की सार्वजनिक कुंजियों के हिसाब से हस्ताक्षर की पुष्टि करें. ये कुंजियां, Google के JWK एंडपॉइंट पर उपलब्ध हैं.
  • सर्टिफ़िकेट जारी करने वाला (iss): यह https://accounts.google.com होना चाहिए.
  • ऑडियंस (aud): यह आपके इंटिग्रेशन को असाइन किए गए Google API क्लाइंट आईडी से मेल खाना चाहिए.
  • खत्म होने की तारीख (exp): यह तारीख, आने वाले समय की होनी चाहिए.

check इंटेंट के लिए जवाब

intent=check के साथ किए गए अनुरोध से यह पुष्टि की जाती है कि Google खाता (डिकोड किए गए जेडब्लयूटी दावे में sub या email के तौर पर पहचाना गया) आपके उपयोगकर्ता डेटाबेस में मौजूद है या नहीं.

  • एचटीटीपी स्टेटस: 200 OK (खाता मिला) या 404 Not Found (खाता नहीं मिला)
  • Content-Type: application/json;charset=UTF-8
फ़ील्ड ब्यौरा
account_found ज़रूरी है. true अगर खाता मौजूद है, false अगर खाता मौजूद नहीं है.

get इंटेंट के लिए जवाब

intent=get वाला अनुरोध, किसी मौजूदा Google खाते के लिए ऐक्सेस टोकन का अनुरोध करता है.

  • एचटीटीपी स्टेटस: 200 OK
  • Content-Type: application/json;charset=UTF-8

सफल रिस्पॉन्स JSON ऑब्जेक्ट का स्ट्रक्चर, स्टैंडर्ड टोकन एक्सचेंज के सफल रिस्पॉन्स के स्ट्रक्चर जैसा ही होता है. इसमें access_token, refresh_token वगैरह शामिल होते हैं.

अगर खाता लिंक नहीं किया जा सकता, तो एचटीटीपी 401 गड़बड़ी का मैसेज दिखता है.

  • एचटीटीपी स्टेटस: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
गड़बड़ी वाले फ़ील्ड (JSON) ब्यौरा
error ज़रूरी है. linking_error होना चाहिए.
login_hint (ज़रूरी नहीं) उपयोगकर्ता का ईमेल पता, जिसे OAuth लिंकिंग के फ़ॉलबैक फ़्लो में पास किया जाता है.

create इंटेंट के लिए जवाब

intent=create वाले अनुरोध में, JWT में दी गई जानकारी का इस्तेमाल करके नया उपयोगकर्ता खाता बनाने का अनुरोध किया जाता है.

  • एचटीटीपी स्टेटस: 200 OK
  • Content-Type: application/json;charset=UTF-8

सफल रिस्पॉन्स JSON ऑब्जेक्ट का स्ट्रक्चर, स्टैंडर्ड टोकन एक्सचेंज के सफल रिस्पॉन्स के स्ट्रक्चर जैसा ही होता है. इसमें access_token, refresh_token वगैरह शामिल होते हैं.

अगर उपयोगकर्ता पहले से मौजूद है, तो HTTP 401 गड़बड़ी का मैसेज दिखता है. इससे उपयोगकर्ता को अपना मौजूदा खाता लिंक करने के लिए कहा जाता है.

  • एचटीटीपी स्टेटस: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
गड़बड़ी वाले फ़ील्ड (JSON) ब्यौरा
error ज़रूरी है. linking_error होना चाहिए.
login_hint उपयोगकर्ता का ईमेल पता, जिसे फ़ॉलबैक OAuth लिंकिंग फ़्लो में पास किया जाता है.

UserInfo एंडपॉइंट (ज़रूरी नहीं)

इस कुकी का इस्तेमाल, लिंक किए गए उपयोगकर्ता की प्रोफ़ाइल की बुनियादी जानकारी को वापस पाने के लिए किया जाता है. यह जानकारी, OpenID Connect Core 1.0 स्पेसिफ़िकेशन में दी गई है. यह "आसानी से लिंक करना" या "एक टैप में साइन इन करना" जैसी सुविधाओं के लिए ज़रूरी है.

  • तरीका: GET
  • पुष्टि करना: Authorization: Bearer ACCESS_TOKEN

जवाब (JSON)

HTTPS रिस्पॉन्स के मुख्य हिस्से में JSON ऑब्जेक्ट के साथ, सही रिस्पॉन्स दिखाएं.

  • एचटीटीपी स्टेटस: 200 OK
  • Content-Type: application/json;charset=UTF-8

जवाब के फ़ील्ड

फ़ील्ड ब्यौरा
sub ज़रूरी है. यह एक यूनीक आईडी होता है, जो आपके सिस्टम में उपयोगकर्ता की पहचान करता है.
email ज़रूरी है. उपयोगकर्ता का ईमेल पता.
email_verified ज़रूरी है. बूलियन वैल्यू, यह दिखाती है कि ईमेल पते की पुष्टि हुई है या नहीं.
given_name (ज़रूरी नहीं) उपयोगकर्ता का नाम.
family_name (ज़रूरी नहीं) उपयोगकर्ता का उपनाम.
name (ज़रूरी नहीं) उपयोगकर्ता का पूरा नाम.
picture (ज़रूरी नहीं) उपयोगकर्ता की प्रोफ़ाइल फ़ोटो का यूआरएल.

गड़बड़ी के रिस्पॉन्स

अगर ऐक्सेस टोकन अमान्य है या इसकी समयसीमा खत्म हो गई है, तो HTTP 401 Unauthorized गड़बड़ी दिखाएं. आपको WWW-Authenticate रिस्पॉन्स हेडर भी शामिल करना चाहिए.

खाता लिंक करने की प्रोसेस के दौरान, अगर कोई अनुरोध पूरा नहीं होता है (4xx या 5xx), तो उसे ठीक नहीं किया जा सकता. इन मामलों में, Google वापस पाए गए सभी टोकन खारिज कर देगा. साथ ही, उपयोगकर्ता को खाते लिंक करने की प्रोसेस फिर से शुरू करनी होगी.

टोकन रेवकेशन एंडपॉइंट (ज़रूरी नहीं)

इस कुकी की मदद से Google, आपकी सेवा को तब सूचना भेज सकता है, जब कोई उपयोगकर्ता अपने खाते को Google प्लैटफ़ॉर्म से अनलिंक करता है. यह एंडपॉइंट, RFC 7009 में बताई गई ज़रूरी शर्तों के मुताबिक होना चाहिए.

  • तरीका: POST
  • Content-Type: application/x-www-form-urlencoded

अनुरोध के पैरामीटर

पैरामीटर ब्यौरा
client_id यह स्ट्रिंग, अनुरोध के सोर्स की पहचान Google के तौर पर करती है. इस स्ट्रिंग को आपके सिस्टम में, Google के यूनीक आइडेंटिफ़ायर के तौर पर रजिस्टर किया जाना चाहिए.
client_secret ऐसी सीक्रेट स्ट्रिंग जिसे आपने अपनी सेवा के लिए, Google के साथ रजिस्टर किया है.
token वह टोकन जिसे रद्द करना है.
token_type_hint (ज़रूरी नहीं) रद्द किए जा रहे टोकन के टाइप के बारे में जानकारी. यह access_token या refresh_token हो सकता है. अगर कोई वैल्यू नहीं दी गई है, तो डिफ़ॉल्ट रूप से access_token लागू होता है.

जवाब

टोकन मिटा दिए जाने पर या टोकन पहले से अमान्य होने पर, पुष्टि करने वाला जवाब दिखाएं.

  • एचटीटीपी स्टेटस: 200 OK
  • Content-Type: application/json;charset=UTF-8

गड़बड़ी के रिस्पॉन्स

अगर किसी वजह से टोकन नहीं मिटाया जा सकता (जैसे, डेटाबेस उपलब्ध न होना), तो HTTP 503 गड़बड़ी दिखाएं. Google, अनुरोध को बाद में फिर से भेजेगा या Retry-After हेडर में दिए गए निर्देशों के मुताबिक भेजेगा.

  • एचटीटीपी स्टेटस: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • हेडर: Retry-After: <HTTP-date / delay-seconds>