इस रेफ़रंस पेज में, उन एपीआई एंडपॉइंट के बारे में बताया गया है जिन्हें आपकी सेवा को लागू करना होगा. इससे Google के साथ खाता लिंक करने की सुविधा काम करेगी. इसमें OAuth पर आधारित खाता लिंक करना, आसान तरीके से खाता लिंक करना, और ऐप्लिकेशन फ़्लिप शामिल हैं.
ज़रूरी शर्तें और स्टैंडर्ड
इन एंडपॉइंट को लागू करने के लिए, आपकी सेवा को इन मानकों का पालन करना होगा:
- OAuth 2.0: RFC 6749 के मुताबिक.
- टोकन रद्द करना: आरएफ़सी 7009 के मुताबिक होना चाहिए.
- JSON Web Tokens (JWT): 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. |
टोकन एक्सचेंज एंडपॉइंट
यह एंडपॉइंट, ऑथराइज़ेशन कोड को टोकन के लिए एक्सचेंज करने और समयसीमा खत्म हो चुके ऐक्सेस टोकन को रीफ़्रेश करने के लिए ज़िम्मेदार होता है.
- यूआरएल: इसे 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 |
वही रीडायरेक्ट यूआरआई जिसका इस्तेमाल शुरुआती अनुरोध में किया गया था. |
रीफ़्रेश टोकन को ऐक्सेस टोकन के लिए एक्सचेंज करना
ऐक्सेस टोकन को रीफ़्रेश करते समय, इन पैरामीटर का इस्तेमाल किया जाता है.
अनुरोध के पैरामीटर
| पैरामीटर | ब्यौरा |
|---|---|
client_id |
Google को असाइन किया गया क्लाइंट आईडी. |
client_secret |
वह क्लाइंट सीक्रेट जिसे आपने Google को असाइन किया है. |
grant_type |
refresh_token होना चाहिए. |
refresh_token |
Google को पहले जारी किया गया रीफ़्रेश टोकन. |
जवाब (JSON)
HTTPS रिस्पॉन्स के मुख्य हिस्से में JSON ऑब्जेक्ट के साथ, सही रिस्पॉन्स दिखाएं.
- एचटीटीपी स्टेटस:
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 खाता (डिकोड किए गए JWT असर्शन में 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 वगैरह शामिल होते हैं.
अगर उपयोगकर्ता पहले से मौजूद है, तो एचटीटीपी 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>