การทำงานกับขอบเขต OAuth2

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่ เอกสารประกอบของ Apigee X info

หัวข้อนี้จะอธิบายวิธีใช้ขอบเขต OAuth 2.0 ใน Apigee Edge

ขอบเขต OAuth2 คืออะไร

ขอบเขต OAuth 2.0 เป็นวิธีจำกัดระดับการเข้าถึงที่มอบให้กับโทเค็นเพื่อการเข้าถึง ตัวอย่างเช่น โทเค็นเพื่อการเข้าถึงที่ออกให้กับแอปของไคลเอ็นต์อาจได้รับสิทธิ์เข้าถึงแบบอ่านและเขียนทรัพยากรที่ได้รับการปกป้อง หรือเพียงสิทธิ์เข้าถึงแบบอ่านเท่านั้น คุณสามารถใช้ API เพื่อบังคับใช้ขอบเขตหรือ การผสมผสานขอบเขตที่ต้องการได้ ดังนั้น หากไคลเอ็นต์ได้รับโทเค็นที่มีขอบเขต READ และมัน พยายามเรียกใช้ปลายทาง API ที่ต้องใช้สิทธิ์เข้าถึง WRITE การเรียกใช้จะไม่สำเร็จ

ในหัวข้อนี้ เราจะพูดถึงวิธีกำหนดขอบเขตให้กับโทเค็นเพื่อการเข้าถึงและวิธีที่ Apigee Edge บังคับใช้ขอบเขต OAuth 2.0 หลังจากอ่านหัวข้อนี้แล้ว คุณจะใช้ขอบเขตได้อย่างมั่นใจ

ระบบกำหนดขอบเขตให้กับโทเค็นเพื่อการเข้าถึงอย่างไร

เมื่อ Edge สร้างโทเค็นเพื่อการเข้าถึง ระบบอาจกำหนดขอบเขตให้กับโทเค็นนั้น หากต้องการทำความเข้าใจว่า เหตุการณ์นี้เกิดขึ้นได้อย่างไร คุณต้องทำความคุ้นเคยกับเอนทิตี Apigee Edge ต่อไปนี้ก่อน ได้แก่ ผลิตภัณฑ์ API, นักพัฒนาแอป และแอปของนักพัฒนาแอป โปรดดูข้อมูลเบื้องต้นที่หัวข้อข้อมูลเบื้องต้นเกี่ยวกับการเผยแพร่ เราขอแนะนำ ให้คุณอ่านเนื้อหานี้หากจำเป็นก่อนดำเนินการต่อ

โทเค็นเพื่อการเข้าถึง คือสตริงยาวของอักขระที่ดูเหมือนสุ่ม ซึ่ง ช่วยให้ Edge ยืนยันคำขอ API ขาเข้าได้ (คิดว่าเป็นข้อมูลเข้าสู่ระบบแทนข้อมูลเข้าสู่ระบบทั่วไปของผู้ใช้/รหัสผ่าน) ในทางเทคนิคแล้ว โทเค็นคือคีย์ที่อ้างอิงถึงคอลเล็กชันของ ข้อมูลเมตาที่มีลักษณะดังนี้

{
  "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"
}

ข้อมูลเมตาของโทเค็นประกอบด้วยสตริงโทเค็นเพื่อการเข้าถึงจริง ข้อมูลการหมดอายุ การระบุแอปของนักพัฒนาแอป นักพัฒนาแอป และผลิตภัณฑ์ที่เชื่อมโยงกับโทเค็น นอกจากนี้ คุณจะเห็นว่าข้อมูลเมตายังมี "ขอบเขต" ด้วย

โทเค็นได้รับขอบเขตมาได้อย่างไร

สิ่งสำคัญประการแรกในการทำความเข้าใจขอบเขตคือการจดจำว่าผลิตภัณฑ์แต่ละรายการในแอปของนักพัฒนาแอปสามารถ มีขอบเขตตั้งแต่ 0 รายการขึ้นไปกำหนดไว้ คุณกำหนดขอบเขตเหล่านี้ได้เมื่อสร้างผลิตภัณฑ์ หรือเพิ่มในภายหลัง ขอบเขตจะอยู่ในรูปแบบรายการชื่อและรวมอยู่ใน "ข้อมูลเมตา" ที่เชื่อมโยงกับผลิตภัณฑ์แต่ละรายการ

เมื่อคุณสร้างแอปของนักพัฒนาแอปและเพิ่มผลิตภัณฑ์ลงในแอป Edge จะดูผลิตภัณฑ์ทั้งหมดใน แอปของนักพัฒนาแอปและสร้างรายการขอบเขตทั้งหมดสำหรับผลิตภัณฑ์เหล่านั้น (รายการขอบเขตหลักหรือ ส่วนกลางของแอป ซึ่งเป็นการรวมขอบเขตที่รู้จักทั้งหมด)

เมื่อแอปของไคลเอ็นต์ขอโทเค็นเพื่อการเข้าถึงจาก Apigee Edge แอปสามารถระบุขอบเขตที่ต้องการเชื่อมโยงกับโทเค็นนั้นได้โดยไม่บังคับ ตัวอย่างเช่น คำขอต่อไปนี้ขอ ขอบเขต "A" นั่นคือ ไคลเอ็นต์ขอให้เซิร์ฟเวอร์การให้สิทธิ์ (Edge) สร้างโทเค็นเพื่อการเข้าถึงที่มีขอบเขต "A" (ให้สิทธิ์แอปในการเรียกใช้ API ที่มีขอบเขต "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 จึงต้อง ตัดสินใจว่าผลิตภัณฑ์ API ใดที่เชื่อมโยงกับแอปของนักพัฒนาแอปมีขอบเขต "A" หรือไม่ หากมี ระบบจะสร้างโทเค็นเพื่อการเข้าถึงที่มีขอบเขต "A" อีกวิธีหนึ่งในการดูข้อมูลนี้คือ พารามิเตอร์การค้นหาขอบเขต เป็นตัวกรองประเภทหนึ่ง หากแอปของนักพัฒนาแอปรู้จักขอบเขต "A, B, X" และพารามิเตอร์การค้นหาระบุ "scope=X Y Z" ระบบจะกำหนดขอบเขต "X" ให้กับ โทเค็นเท่านั้น

จะเกิดอะไรขึ้นหากไคลเอ็นต์ไม่ได้แนบพารามิเตอร์ขอบเขต ในกรณีนี้ Edge จะสร้างโทเค็น ที่มีขอบเขตทั้งหมด ที่แอปของนักพัฒนาแอปรู้จัก คุณควรเข้าใจว่าลักษณะการทำงานเริ่มต้นคือการแสดงผลโทเค็นเพื่อการเข้าถึงที่มีการ รวมขอบเขตทั้งหมดสำหรับผลิตภัณฑ์ทั้งหมดที่รวมอยู่ในแอปของนักพัฒนาแอป

หากไม่มีผลิตภัณฑ์ใดที่เชื่อมโยงกับแอปของนักพัฒนาแอประบุขอบเขต และโทเค็นมี ขอบเขต การเรียกใช้ที่ทำด้วยโทเค็นนั้นจะไม่สำเร็จ

สมมติว่าแอปของนักพัฒนาแอปรู้จักขอบเขตต่อไปนี้ A B C D นี่คือรายการขอบเขตหลักของแอป ผลิตภัณฑ์หนึ่งในแอปอาจมีขอบเขต A และ B และผลิตภัณฑ์ที่ 2 มีขอบเขต C และ D หรือการผสมผสานอื่นๆ หากไคลเอ็นต์ไม่ได้ระบุพารามิเตอร์ scope (หรือหาก ระบุพารามิเตอร์ขอบเขตโดยไม่มีค่า) โทเค็นจะได้รับขอบเขตทั้ง 4 รายการ ได้แก่ 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> นี้หรือองค์ประกอบนี้ไม่มีค่า นโยบายจะละเว้นขอบเขตของโทเค็นเพื่อการเข้าถึง

ตอนนี้เมื่อมีความสามารถในการตรวจสอบโทเค็นเพื่อการเข้าถึงตามขอบเขตแล้ว คุณสามารถออกแบบ API เพื่อ บังคับใช้ขอบเขตที่เฉพาะเจาะจงได้ คุณทำได้โดยออกแบบโฟลว์ที่กำหนดเองโดยแนบนโยบาย VerifyAccessToken ที่รับรู้ขอบเขตไว้

สมมติว่า API ของคุณมีโฟลว์ที่กำหนดไว้สำหรับปลายทาง /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>

สรุปได้ว่านักพัฒนาแอป API มีหน้าที่รับผิดชอบในการออกแบบการบังคับใช้ขอบเขตใน API ของตน โดยทำได้โดยสร้างโฟลว์ที่กำหนดเองเพื่อจัดการขอบเขตที่เฉพาะเจาะจง และแนบนโยบาย VerifyAccessToken เพื่อบังคับใช้ขอบเขตเหล่านั้น

ตัวอย่างโค้ด

สุดท้ายนี้ ลองดูตัวอย่างการเรียกใช้ API เพื่อช่วยแสดงให้เห็นว่าโทเค็นได้รับ ขอบเขตอย่างไรและระบบบังคับใช้ขอบเขตอย่างไร

กรณีเริ่มต้น

สมมติว่าคุณมีแอปของนักพัฒนาแอปที่มีผลิตภัณฑ์ และการรวมขอบเขตของผลิตภัณฑ์เหล่านั้น คือ A, B และ C การเรียก API นี้ขอโทเค็นเพื่อการเข้าถึง แต่ไม่ได้ระบุพารามิเตอร์การค้นหาขอบเขต

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"
}

ตอนนี้สมมติว่าคุณมีปลายทาง API ที่มีขอบเขต "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, B, C และ X ในกรณีนี้ คุณกำลังกรองรายการผลิตภัณฑ์ API ตามขอบเขตเหล่านี้ หากผลิตภัณฑ์มีขอบเขต A หรือ X, คุณสามารถกำหนดค่าปลายทาง API ที่จะบังคับใช้ขอบเขตเหล่านี้ได้ หากผลิตภัณฑ์ไม่มีขอบเขต A หรือ X (สมมติว่ามีขอบเขต B, C และ Z) คุณจะไม่สามารถเรียกใช้ API ที่บังคับใช้ขอบเขต A หรือ X ด้วยโทเค็นได้

เมื่อคุณเรียกใช้ API ด้วยโทเค็นใหม่

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

พร็อกซี API จะตรวจสอบโทเค็นเพื่อการเข้าถึง ตัวอย่างเช่น

<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 (เซิร์ฟเวอร์การให้สิทธิ์) จะเป็นผู้พิจารณาขอบเขตที่จะกำหนดให้กับโทเค็นเพื่อการเข้าถึงโดยอิงตาม (ก) ขอบเขตที่ขอและ (ข) ขอบเขตที่แอปของนักพัฒนาแอปรู้จัก
• หากไม่ได้กำหนดค่า Apigee Edge ให้ตรวจสอบขอบเขต (องค์ประกอบ <Scope> หายไปจากนโยบาย VerifyAccessToken หรือว่างเปล่า) การเรียก API จะสำเร็จตราบใดที่ขอบเขตที่ฝังอยู่ในโทเค็นเพื่อการเข้าถึงตรงกับขอบเขตใดขอบเขตหนึ่งที่แอปของนักพัฒนาแอปที่ลงทะเบียนไว้รู้จัก (ขอบเขตใดขอบเขตหนึ่งในรายการขอบเขต "หลัก" ของแอป)
• หากโทเค็นเพื่อการเข้าถึงไม่มีขอบเขตที่เชื่อมโยง โทเค็นจะสำเร็จในกรณีที่ Edge ไม่พิจารณาขอบเขตเท่านั้น (องค์ประกอบ <Scope> หายไป จากนโยบาย VerifyAccessToken หรือว่างเปล่า)