Edge API को ऐक्सेस करने के लिए OAuth2 का इस्तेमाल करना

यहां Apigee Edge के दस्तावेज़ देखे जा रहे हैं.
पर जाएं Apigee X दस्तावेज़. info

Apigee Edge की मदद से, Edge API कॉल किए जा सकते हैं. इनकी पुष्टि OAuth2 टोकन से की जाती है. क्लाउड खातों के लिए, Edge पर OAuth2 की सुविधा डिफ़ॉल्ट रूप से चालू रहती है. अगर Private Cloud के लिए Edge का इस्तेमाल किया जा रहा है, तो पहले SAML सेट अप किए बिना या LDAP के बिना OAuth2 का इस्तेमाल नहीं किया जा सकता.

Apigee Edge API के साथ OAuth2 कैसे काम करता है

Apigee Edge API को कॉल करने के लिए, पुष्टि करना ज़रूरी है. इससे हमें यह पक्का करने में मदद मिलती है कि आप वही हैं जो आपने दावा किया है. आपकी पुष्टि करने के लिए, हमें OAuth2 ऐक्सेस टोकन की ज़रूरत होती है. यह टोकन, एपीआई को ऐक्सेस करने के आपके अनुरोध के साथ भेजा जाना चाहिए.

उदाहरण के लिए, अगर आपको Edge पर किसी संगठन के बारे में जानकारी चाहिए, तो आपको इस तरह के यूआरएल पर अनुरोध भेजना होगा:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

हालांकि, हमें अपनी पहचान बताए बिना, सिर्फ़ यह अनुरोध नहीं भेजा जा सकता. ऐसा करने पर, कोई भी आपके संगठन की जानकारी देख सकता है.

यहां OAuth2 काम आता है: आपकी पुष्टि करने के लिए, हमें उस अनुरोध में ऐक्सेस टोकन भी भेजना होगा. ऐक्सेस टोकन से हमें आपकी पहचान पता चलती है. इससे हमें यह पक्का करने में मदद मिलती है कि आपको संगठन की जानकारी देखने की अनुमति है.

अच्छी बात यह है कि Edge OAuth2 सेवा को अपने क्रेडेंशियल भेजकर, टोकन हासिल किया जा सकता है. सेवा, ऐक्सेस और रीफ़्रेश टोकन के साथ जवाब देती है.

OAuth2 फ़्लो: शुरुआती अनुरोध

पहली बार Edge API को ऐक्सेस करने पर, OAuth2 फ़्लो यहां दिखाया गया है:

OAuth फ़्लो: पहला अनुरोध
पहली इमेज: OAuth फ़्लो: पहला अनुरोध

पहली इमेज में दिखाया गया है कि Edge API को शुरुआती अनुरोध करते समय:

  1. ऐक्सेस टोकन का अनुरोध किया जाता है. यह काम, Edge API, acurl या get_token की मदद से किया जा सकता है. उदाहरण के लिए: 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. Edge OAuth2 सेवा, ऐक्सेस टोकन के साथ जवाब देती है और इसे stdout पर प्रिंट करती है; उदाहरण के लिए: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    acurl और get_token यूटिलिटी, ऐक्सेस और रीफ़्रेश टोकन को चुपचाप ~/.sso-cli में सेव कर लेती हैं. रीफ़्रेश टोकन को stdout में नहीं लिखा जाता. अगर टोकन पाने के लिए, Edge OAuth2 सेवा का इस्तेमाल किया जाता है, तो आपको उन्हें बाद में इस्तेमाल करने के लिए सेव करना होगा.

  3. Edge API को ऐक्सेस टोकन के साथ अनुरोध भेजा जाता है. acurl अटैच कर लेता है टोकन को अपने-आप. उदाहरण के लिए: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    अगर किसी दूसरे एचटीटीपी क्लाइंट का इस्तेमाल किया जाता है, तो पक्का करें कि ऐक्सेस टोकन जोड़ा गया हो. उदाहरण के लिए:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API, आपके अनुरोध को पूरा करता है और आम तौर पर, डेटा के साथ जवाब देता है.

OAuth2 फ़्लो: बाद के अनुरोध

बाद के अनुरोधों के लिए, आपको अपने क्रेडेंशियल को टोकन के लिए एक्सचेंज करने की ज़रूरत नहीं होती. इसके बजाय, आपके पास पहले से मौजूद ऐक्सेस टोकन को शामिल किया जा सकता है. हालांकि, यह तब तक किया जा सकता है, जब तक उसकी समयसीमा खत्म न हुई हो:

OAuth फ़्लो: बाद के अनुरोध
दूसरी इमेज: OAuth फ़्लो: बाद के अनुरोध

दूसरी इमेज में दिखाया गया है कि अगर आपके पास पहले से ऐक्सेस टोकन है, तो:

  1. Edge API को ऐक्सेस टोकन के साथ अनुरोध भेजा जाता है. acurl अटैच करता है टोकन को अपने-आप. अगर दूसरे टूल का इस्तेमाल किया जाता है, तो आपको टोकन को मैन्युअल तरीके से जोड़ना होगा.
  2. Edge API, आपके अनुरोध को पूरा करता है और आम तौर पर, डेटा के साथ जवाब देता है.

OAuth2 फ़्लो: ऐक्सेस टोकन की समयसीमा खत्म होने पर

ऐक्सेस टोकन की समयसीमा खत्म होने पर (12 घंटे बाद), नया ऐक्सेस टोकन पाने के लिए, रीफ़्रेश टोकन का इस्तेमाल किया जा सकता है:

OAuth फ़्लो: ऐक्सेस टोकन रीफ़्रेश करना
तीसरी इमेज: OAuth फ़्लो: ऐक्सेस टोकन को रीफ़्रेश करना

तीसरी इमेज में दिखाया गया है कि ऐक्सेस टोकन की समयसीमा खत्म होने पर:

  1. Edge API को अनुरोध भेजा जाता है, लेकिन ऐक्सेस टोकन की समयसीमा खत्म हो चुकी होती है.
  2. Edge API, आपके अनुरोध को अनुमति न होने की वजह से खारिज कर देता है.
  3. Edge OAuth2 सेवा को रीफ़्रेश टोकन भेजा जाता है. अगर acurl का इस्तेमाल किया जा रहा है, तो यह काम अपने-आप हो जाता है.
  4. Edge OAuth2 सेवा, नए ऐक्सेस टोकन के साथ जवाब देती है.
  5. Edge API को नए ऐक्सेस टोकन के साथ अनुरोध भेजा जाता है.
  6. Edge API, आपके अनुरोध को पूरा करता है और आम तौर पर, डेटा के साथ जवाब देता है.

टोकन पाना

Edge API को ऐक्सेस टोकन भेजने के लिए, Apigee की इन यूटिलिटी के अलावा, curl जैसी किसी यूटिलिटी का इस्तेमाल किया जा सकता है:

  • get_token यूटिलिटी: Apigee के क्रेडेंशियल को ऐक्सेस और रीफ़्रेश टोकन के लिए एक्सचेंज करती है. इन टोकन का इस्तेमाल, Edge API को कॉल करने के लिए किया जा सकता है.
  • acurl यूटिलिटी: यह, स्टैंडर्ड curl कमांड के लिए रैपर की सुविधा देती है. Edge API के लिए एचटीटीपी अनुरोध बनाती है, get_token से ऐक्सेस और रीफ़्रेश टोकन हासिल करती है, और ऐक्सेस टोकन को Edge API को पास करती है.
  • Edge OAuth2 सेवा में टोकन एंडपॉइंट: Edge API को कॉल करके, Apigee के क्रेडेंशियल को ऐक्सेस और रीफ़्रेश टोकन के लिए एक्सचेंज करती है.

ये यूटिलिटी, आपके Apigee खाते के क्रेडेंशियल (ईमेल पता और पासवर्ड) को इन समयसीमा वाले टोकन के लिए एक्सचेंज करती हैं:

  • ऐक्सेस टोकन की समयसीमा 12 घंटे में खत्म हो जाती है.
  • रीफ़्रेश टोकन की समयसीमा 30 दिन में खत्म हो जाती है.

इसलिए, acurl या get_token की मदद से एपीआई कॉल करने के बाद, टोकन के जोड़े का इस्तेमाल 30 दिनों तक किया जा सकता है. समयसीमा खत्म होने के बाद, आपको अपने क्रेडेंशियल फिर से डालने होंगे और नए टोकन पाने होंगे.

OAuth2 की मदद से Edge API को ऐक्सेस करना

Edge API को ऐक्सेस करने के लिए, एपीआई एंडपॉइंट को अनुरोध भेजें और उसमें ऐक्सेस टोकन शामिल करें. यह काम, किसी भी एचटीटीपी क्लाइंट की मदद से किया जा सकता है. जैसे, curl जैसी कमांड-लाइन यूटिलिटी, Postman जैसे ब्राउज़र पर आधारित यूज़र इंटरफ़ेस (यूआई) या acurl जैसी Apigee यूटिलिटी.

acurl और curl की मदद से Edge API को ऐक्सेस करने के बारे में, आगे आने वाले सेक्शन में बताया गया है.

acurl का इस्तेमाल करना

acurl की मदद से Edge API को ऐक्सेस करने के लिए, आपके शुरुआती अनुरोध में आपके क्रेडेंशियल शामिल होने चाहिए. Edge OAuth2 सेवा, ऐक्सेस और रीफ़्रेश टोकन के साथ जवाब देती है. acurl , टोकन को स्थानीय तौर पर सेव कर लेता है.

बाद के अनुरोधों के लिए, acurl ~/.sso-cli में सेव किए गए टोकन का इस्तेमाल करता है. इससे आपको टोकन की समयसीमा खत्म होने तक, अपने क्रेडेंशियल फिर से शामिल करने की ज़रूरत नहीं पड़ती.

यहां दिए गए उदाहरण में, "ahamilton-eval" संगठन के बारे में जानकारी पाने के लिए, acurl के शुरुआती अनुरोध को दिखाया गया है:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

संगठन के बारे में जानकारी पाने के अलावा, इस उदाहरण में दूसरा अनुरोध भी दिखाया गया है. इससे "helloworld" एपीआई प्रॉक्सी में शामिल नीतियों की सूची मिलती है. दूसरे अनुरोध में, यूआरएल में "organizations" के लिए "o" का इस्तेमाल किया गया है.

ध्यान दें कि acurl, दूसरे अनुरोध पर ऐक्सेस टोकन को अपने-आप पास कर देता है. acurl `acurl` के OAuth2 टोकन सेव करने के बाद, आपको अपने उपयोगकर्ता क्रेडेंशियल पास करने की ज़रूरत नहीं होती. बाद के कॉल के लिए, यह ~/.sso-cli से टोकन हासिल करता है.

ज़्यादा जानकारी के लिए, Edge API को ऐक्सेस करने के लिए acurl का इस्तेमाल करना लेख पढ़ें.

curl का इस्तेमाल करना

Edge API को ऐक्सेस करने के लिए, curl का इस्तेमाल किया जा सकता है. इसके लिए, आपको पहले ऐक्सेस और रीफ़्रेश टोकन पाने होंगे. इन्हें get_token जैसी किसी यूटिलिटी या Edge OAuth2 सेवा का इस्तेमाल करके पाया जा सकता है.

ऐक्सेस टोकन को सेव करने के बाद, इसे Edge API को किए जाने वाले कॉल के Authorization हेडर में पास करें. जैसा कि यहां दिए गए उदाहरण में दिखाया गया है:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

ऐक्सेस टोकन जारी होने के 12 घंटे बाद तक मान्य रहता है. ऐक्सेस टोकन की समयसीमा खत्म होने के बाद, रीफ़्रेश टोकन का इस्तेमाल 30 दिनों तक किया जा सकता है. इससे क्रेडेंशियल की ज़रूरत के बिना, दूसरा ऐक्सेस टोकन जारी किया जा सकता है. Apigee का सुझाव है कि हर एपीआई कॉल के लिए क्रेडेंशियल डालकर नया अनुरोध करने के बजाय, रीफ़्रेश टोकन की समयसीमा खत्म होने के बाद ही नए ऐक्सेस टोकन का अनुरोध करें.

टोकन की समयसीमा खत्म होना

ऐक्सेस टोकन की समयसीमा खत्म होने के बाद, रीफ़्रेश टोकन का इस्तेमाल करके नया ऐक्सेस टोकन पाया जा सकता है. इसके लिए, आपको अपने क्रेडेंशियल फिर से सबमिट करने की ज़रूरत नहीं होती.

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

  • acurl: कोई कार्रवाई ज़रूरी नहीं है. acurl ऐक्सेस टोकन को अपने-आप रीफ़्रेश कर देता है ऐसा तब होता है, जब ऐसा अनुरोध भेजा जाता है जिसमें पुराना टोकन शामिल हो.
  • get_token: ऐक्सेस टोकन को रीफ़्रेश करने के लिए, get_token को कॉल करें.
  • Edge OAuth2 सेवा: ऐसा अनुरोध भेजें जिसमें ये शामिल हों:
    • रीफ़्रेश टोकन
    • grant_type फ़ॉर्म पैरामीटर को "refresh_token" पर सेट किया गया हो

मशीन उपयोगकर्ताओं के लिए OAuth2

`acurl` और `get_token` यूटिलिटी का इस्तेमाल करके, मशीन उपयोगकर्ताओं के लिए OAuth2 पुष्टि के साथ, Edge API को अपने-आप ऐक्सेस करने के लिए स्क्रिप्ट बनाई जा सकती है. यहां दिए गए उदाहरण में, get_token का इस्तेमाल करके ऐक्सेस टोकन का अनुरोध करने और फिर curl कॉल में टोकन की वैल्यू जोड़ने का तरीका बताया गया है:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

इसके अलावा, acurl यूटिलिटी का इस्तेमाल करके, टोकन के अनुरोध और curl कॉल को एक साथ किया जा सकता है. उदाहरण के लिए:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

दोनों उदाहरणों में, -m की वैल्यू को खाली स्ट्रिंग पर सेट करने से, मशीन उपयोगकर्ता को एमएफ़ए कोड के लिए प्रॉम्प्ट नहीं किया जाएगा.