OAuth2 स्कोप के साथ काम करना

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

इस विषय में, Apigee Edge पर OAuth 2.0 स्कोप इस्तेमाल करने के तरीके के बारे में बताया गया है.

OAuth2 स्कोप क्या है?

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

इस विषय में, हम चर्चा करेंगे कि टोकन ऐक्सेस करने के लिए स्कोप कैसे असाइन किए जाते हैं और Apigee Edge OAuth 2.0 स्कोप कैसे लागू करता है. इस विषय को पढ़ने के बाद, आपको स्कोप का इस्तेमाल भरोसे के साथ किया जा सकेगा.

टोकन ऐक्सेस करने के लिए स्कोप कैसे असाइन किए जाते हैं?

जब Edge कोई ऐक्सेस टोकन जनरेट करता है, तो वह उस टोकन के लिए एक स्कोप असाइन कर सकता है. ऐसा करने का तरीका जानने के लिए, आपको सबसे पहले Apigee Edge की इन इकाइयों के बारे में जानकारी होनी चाहिए: एपीआई प्रॉडक्ट, डेवलपर, और डेवलपर ऐप्लिकेशन. परिचय के लिए, पब्लिश करने के बारे में जानकारी देखें. हमारा सुझाव है कि अगर ज़रूरत हो, तो जारी रखने से पहले, आप इस कॉन्टेंट की समीक्षा कर लें.

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

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

टोकन के मेटाडेटा में असल ऐक्सेस टोकन स्ट्रिंग, समयसीमा खत्म होने की जानकारी, डेवलपर ऐप्लिकेशन की पहचान, डेवलपर, और टोकन से जुड़े प्रॉडक्ट शामिल होते हैं. आपको यह भी दिखेगा कि मेटाडेटा में "दायरा" भी शामिल है.

टोकन को इसका दायरा कैसे मिलता है?

दायरा समझने के लिए सबसे पहले यह याद रखें कि डेवलपर ऐप्लिकेशन में हर प्रॉडक्ट के लिए शून्य या उससे ज़्यादा स्कोप असाइन किए जा सकते हैं. प्रॉडक्ट बनाते समय, ये स्कोप असाइन किए जा सकते हैं या उन्हें बाद में जोड़ा जा सकता है. ये नाम की सूची के तौर पर मौजूद होते हैं और हर प्रॉडक्ट के "मेटाडेटा" में शामिल होते हैं.

डेवलपर ऐप्लिकेशन बनाने और उसमें प्रॉडक्ट जोड़ने के बाद, Edge डेवलपर ऐप्लिकेशन में मौजूद सभी प्रॉडक्ट देखता है. साथ ही, वह उन प्रॉडक्ट के लिए सभी दायरों की सूची बनाता है. यह सूची, ऐप्लिकेशन के मास्टर या ग्लोबल स्कोप की सूची होती है. यह सूची, मान्यता पाने वाले सभी दायरों को मिलाकर बनाई जाती है.

जब कोई क्लाइंट ऐप्लिकेशन, Apigee Edge से ऐक्सेस टोकन का अनुरोध करता है, तो वह वैकल्पिक तौर पर यह तय कर सकता है कि उस टोकन से कौनसे दायरे जुड़े होने चाहिए. उदाहरण के लिए, नीचे दिया गया अनुरोध "A" दायरे के बारे में पूछता है. इसका मतलब है कि क्लाइंट, पुष्टि करने वाले सर्वर (Edge) से "A" स्कोप वाला ऐक्सेस टोकन जनरेट करने के लिए कहता है. यह स्कोप "A" वाले एपीआई को कॉल करने की अनुमति देकर, ऐप्लिकेशन को अनुमति देता है. ऐप्लिकेशन इस तरह का पोस्ट अनुरोध भेजता है:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

क्या होगा?

जब Edge को यह अनुरोध मिलता है, तो उसे पता चलता है कि कौनसा ऐप्लिकेशन अनुरोध कर रहा है. साथ ही, उसे पता चलता है कि क्लाइंट ने किस डेवलपर ऐप्लिकेशन को रजिस्टर किया है (क्लाइंट आईडी और क्लाइंट सीक्रेट कुंजियां, पुष्टि करने वाले बेसिक हेडर में कोड में बदले जाते हैं). scope क्वेरी पैरामीटर शामिल है, इसलिए Edge को यह तय करना होगा कि डेवलपर ऐप्लिकेशन से जुड़े किसी भी एपीआई प्रॉडक्ट का स्कोप "A" है या नहीं. अगर ऐसा होता है, तो "A" स्कोप के साथ ऐक्सेस टोकन जनरेट किया जाता है. इसे देखने का एक और तरीका यह है कि स्कोप क्वेरी पैरामीटर एक तरह का फ़िल्टर है. अगर डेवलपर ऐप्लिकेशन स्कोप "A, B, X" की पहचान करता है और क्वेरी पैरामीटर में "scope=X Y Z" है, तो टोकन को सिर्फ़ स्कोप "X" असाइन किया जाएगा.

अगर क्लाइंट कोई स्कोप पैरामीटर अटैच नहीं करता है, तो क्या होगा? इस मामले में, Edge एक टोकन जनरेट करता है, जिसमें डेवलपर ऐप्लिकेशन से पहचाने गए सभी दायरे शामिल होते हैं. यह समझना ज़रूरी है कि डिफ़ॉल्ट व्यवहार एक ऐसा ऐक्सेस टोकन देता है जिसमें डेवलपर ऐप्लिकेशन में शामिल सभी प्रॉडक्ट के लिए सभी दायरों का यूनियन शामिल होता है.

अगर डेवलपर ऐप्लिकेशन से जुड़े किसी भी प्रॉडक्ट में स्कोप की जानकारी नहीं दी गई है और टोकन का स्कोप तय नहीं है, तो उस टोकन की मदद से किए गए कॉल कनेक्ट नहीं हो पाएंगे.

मान लें कि कोई डेवलपर ऐप्लिकेशन इन दायरों की पहचान करता है: A B C D. यह स्कोप की ऐप्लिकेशन की मास्टर सूची है. ऐसा हो सकता है कि ऐप्लिकेशन में एक प्रॉडक्ट के लिए स्कोप A और B हो, जबकि दूसरे प्रॉडक्ट में स्कोप C और D या इन दोनों का मिला-जुला रूप मौजूद हो. अगर क्लाइंट, scope पैरामीटर के बारे में जानकारी नहीं देता या वह बिना वैल्यू वाले स्कोप पैरामीटर के बारे में बताता है, तो टोकन को ये चारों स्कोप मिल जाएंगे: A, B, C, और D. साथ ही, टोकन में स्कोप का एक सेट होता है जो उन सभी दायरों को मिलाकर बनाया जाता है जिनकी पहचान डेवलपर ऐप्लिकेशन करता है.

एक और मामला है जिसमें डिफ़ॉल्ट रूप से, पहचाने गए सभी स्कोप के साथ ऐक्सेस टोकन दिखाना होता है. ऐसा तब होता है, जब generateAccessToken नीति (ऐक्सेस टोकन जनरेट करने वाली Apigee Edge नीति) <Scope> एलिमेंट के बारे में जानकारी नहीं देती. उदाहरण के लिए, यहां generateAccessToken नीति दी गई है, जिसमें <Scope> की जानकारी दी गई है. अगर वह <Scope> एलिमेंट मौजूद नहीं है (या वह मौजूद है, लेकिन खाली है), तो डिफ़ॉल्ट तरीका लागू किया जाता है.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

स्कोप कैसे लागू किए जाते हैं?

सबसे पहले, याद रखें कि Apigee Edge पर, ऐक्सेस टोकन की पुष्टि OAuthV2 नीति के ज़रिए की जाती है. आम तौर पर, इसे प्रॉक्सी फ़्लो की शुरुआत में रखा जाता है. इस नीति में VerificationAccessToken कार्रवाई के बारे में बताया जाना ज़रूरी है. आइए, इस नीति के बारे में जानें:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

<Scope> एलिमेंट पर ध्यान दें. इसका इस्तेमाल यह तय करने के लिए किया जाता है कि नीति किन दायरे को स्वीकार करेगी.

इस उदाहरण में, यह नीति सिर्फ़ तब लागू होगी, जब ऐक्सेस टोकन में स्कोप "A" शामिल हो. अगर इस <Scope> एलिमेंट को हटाया जाता है या इसका कोई मान नहीं होता है, तो नीति, ऐक्सेस टोकन के दायरे को अनदेखा कर देती है.

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

मान लें कि आपके एपीआई में, एंडपॉइंट /resourceA के लिए फ़्लो तय किया गया है:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

जब यह फ़्लो ट्रिगर होता है (पाथ के सफ़िक्स में /resourceA के साथ कोई अनुरोध आता है), तो OAuthV2-VerifyAccessTokenA नीति को तुरंत कॉल किया जाता है. इस नीति से पुष्टि की जाती है कि ऐक्सेस टोकन मान्य है या नहीं. साथ ही, इससे यह पता चलता है कि टोकन के साथ कौनसे स्कोप के साथ काम करता है. अगर इस नीति को नीचे दिए गए उदाहरण के तौर पर, <Scope>A</Scope> के साथ कॉन्फ़िगर किया जाता है, तो यह नीति सिर्फ़ तब सफल होगी, जब ऐक्सेस टोकन का स्कोप "A" हो. ऐसा न करने पर, गड़बड़ी का मैसेज दिखेगा.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

कम शब्दों में कहें, तो अपने एपीआई में, नीति उल्लंघन ठीक करने के तरीके (एनफ़ोर्समेंट) को तय करने की ज़िम्मेदारी एपीआई डेवलपर की है. इसके लिए, वे खास दायरों को हैंडल करने के लिए कस्टम फ़्लो बनाते हैं. साथ ही, उन दायरों को लागू करने के लिए, पुष्टि करने के लिए AccessToken नीतियां लागू करते हैं.

कोड के उदाहरण

आखिर में, आइए कुछ एपीआई कॉल के उदाहरण देखते हैं. इससे यह समझने में मदद मिलेगी कि टोकन को स्कोप कैसे मिलते हैं और स्कोप कैसे लागू किए जाते हैं.

डिफ़ॉल्ट केस

मान लें कि आपके पास प्रॉडक्ट वाला एक डेवलपर ऐप्लिकेशन है और उन प्रॉडक्ट के दायरे A, B, और C हैं. यह एपीआई कॉल, ऐक्सेस टोकन का अनुरोध करता है, लेकिन कोई स्कोप क्वेरी पैरामीटर तय नहीं करता.

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

इस मामले में, जनरेट किए गए टोकन को स्कोप A, B, और C (डिफ़ॉल्ट बिहेवियर) दिए जाएंगे. टोकन का मेटाडेटा कुछ ऐसा दिखेगा:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

अब मान लें कि आपके पास एक ऐसा एपीआई एंडपॉइंट है जिसका स्कोप "A" है. इसका मतलब है कि VerifyAccessToken के लिए, स्कोप "A" की ज़रूरत है. यह रही पुष्टि के लिए AccessToken की नीति:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

यहां कॉल टू और एंडपॉइंट का एक सैंपल दिया गया है, जो स्कोप A को लागू करता है:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA 

यह जीईटी कॉल हो गया:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

यह इसलिए काम करता है, क्योंकि एंडपॉइंट को कॉल करने पर पुष्टि करने के लिए इस्तेमाल की जाने वाली ऐसी नीति का इस्तेमाल किया जाता है जिसे स्कोप A की ज़रूरत होती है और ऐक्सेस टोकन को स्कोप A, B, और C दिया जाता है. यह डिफ़ॉल्ट तरीका है.

फ़िल्टर करने का केस

मान लें कि आपके पास एक ऐसा डेवलपर ऐप्लिकेशन है जिसमें A, B, C, और X स्कोप वाले प्रॉडक्ट हैं. ऐक्सेस टोकन का अनुरोध करने के लिए, scope क्वेरी पैरामीटर को इस तरह से शामिल करें:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

इस मामले में, जनरेट किए गए टोकन को स्कोप A और X दिए जाएंगे, क्योंकि A और X दोनों मान्य स्कोप हैं. याद रखें कि डेवलपर ऐप्लिकेशन स्कोप A, B, C, और X की पहचान करता है. इस मामले में, इन स्कोप के आधार पर एपीआई प्रॉडक्ट की सूची फ़िल्टर की जा रही है. अगर किसी प्रॉडक्ट का स्कोप A या X है, तो इन स्कोप को लागू करने वाले एपीआई एंडपॉइंट कॉन्फ़िगर किए जा सकते हैं. अगर किसी प्रॉडक्ट का स्कोप A या X नहीं है (मान लें कि उसमें B,C, और Z है), तो स्कोप A या X को लागू करने वाले एपीआई को टोकन की मदद से कॉल नहीं किया जा सकता.

एपीआई को नए टोकन के साथ कॉल करने पर:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

ऐक्सेस टोकन की पुष्टि एपीआई प्रॉक्सी से होती है. उदाहरण के लिए:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

जीईटी कॉल ट्रिगर हो जाता है और वह जवाब देता है. उदाहरण के लिए:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }
 

पुष्टि हो गई है, क्योंकि पुष्टि करने के लिए ऐक्सेस टोकन नीति के तहत, स्कोप A या X का इस्तेमाल करना ज़रूरी है. साथ ही, ऐक्सेस टोकन में स्कोप A और X का इस्तेमाल किया गया है. हालांकि, अगर <Scope> एलिमेंट को "B" पर सेट किया गया, तो यह कॉल फ़ेल हो जाएगा.

खास जानकारी

यह समझना ज़रूरी है कि Apigee Edge, OAuth 2.0 स्कोप को कैसे हैंडल करता है. सीखने वाली अहम बातें यहां दी गई हैं:

• डेवलपर ऐप्लिकेशन अपने सभी प्रॉडक्ट के लिए तय किए गए सभी दायरों को "पहचानता" है.
• जब कोई ऐप्लिकेशन ऐक्सेस टोकन का अनुरोध करता है, तो उसके पास यह तय करने का मौका होता है कि उसे किस स्कोप का इस्तेमाल करना है. यह पता लगाना Apigee Edge (ऑथराइज़ेशन सर्वर) पर निर्भर करता है कि वह असल में, ऐक्सेस टोकन को कौनसे स्कोप (a) अनुरोध किए गए दायरे और (b) डेवलपर ऐप्लिकेशन की ओर से पहचाने गए दायरे के आधार पर असाइन करेगा.
• अगर Apigee Edge को जांच करने के दायरे की जांच करने के लिए कॉन्फ़िगर नहीं किया गया है (यह <Scope> एलिमेंट, पुष्टि करने के लिए इस्तेमाल होने वाली टोकन नीति में मौजूद नहीं है या वह खाली है), तो एपीआई कॉल तब तक पूरा होगा, जब तक ऐक्सेस टोकन में जोड़ा गया स्कोप, रजिस्टर किए गए डेवलपर ऐप्लिकेशन की पहचान वाले दायरे से मेल खाता है.
• अगर किसी ऐक्सेस टोकन में कोई स्कोप नहीं है, तो यह सिर्फ़ उन मामलों में सफल होगा जहां Edge स्कोप को शामिल नहीं करता है (जैसे कि पुष्टि करने के लिए ऐक्सेस टोकन नीति में <Scope> एलिमेंट मौजूद नहीं होता है या वह खाली होता है).