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

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

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

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

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

इस विषय में, हम यह चर्चा करेंगे कि ऐक्सेस टोकन को स्कोप कैसे असाइन किए जाते हैं और 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" स्कोप वाले एपीआई को कॉल करने की अनुमति मिल जाती है. ऐप्लिकेशन, इस तरह का POST अनुरोध भेजता है:

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 नीति की मदद से ऐक्सेस टोकन की पुष्टि की जाती है. आम तौर पर, इसे प्रॉक्सी फ़्लो की शुरुआत में रखा जाता है. नीति में, VerifyAccessToken की कार्रवाई तय की जानी चाहिए. आइए, इस नीति को देखें:

<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> एलिमेंट छोड़ा गया है या इसकी कोई वैल्यू नहीं है, तो नीति, ऐक्सेस टोकन के स्कोप को अनदेखा कर देती है.

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

मान लें कि आपके एपीआई में, /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>

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

कोड के उदाहरण

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

डिफ़ॉल्ट केस

मान लें कि आपके पास प्रॉडक्ट वाला कोई डेवलपर ऐप्लिकेशन है और उन प्रॉडक्ट के स्कोप का यूनियन है: 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" स्कोप की ज़रूरत होती है. यहां VerifyAccessToken नीति दी गई है:

<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 

यह GET कॉल सफल होता है:

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

यह इसलिए सफल होता है, क्योंकि एंडपॉइंट को कॉल करने पर ट्रिगर होने वाली VerifyAccessToken नीति के लिए स्कोप 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 मान्य स्कोप हैं. याद रखें कि डेवलपर ऐप्लिकेशन, स्कोप 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>

GET कॉल सफल होता है और इससे जवाब मिलता है. उदाहरण के लिए:

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

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

खास जानकारी

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

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