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

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

หัวข้อนี้จะกล่าวถึงวิธีใช้ขอบเขต OAuth 2.0 ใน Apigee Edge

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

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

ในหัวข้อนี้ เราจะพูดถึงการกำหนดขอบเขตสำหรับเข้าถึงโทเค็นและวิธีที่ 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"
}

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

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

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

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

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

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

สมมติว่าแอปนักพัฒนาแอปรู้จักขอบเขตเหล่านี้ คือ ก ข ค ง นี่คือรายการหลักของแอป ขอบเขต เป็นไปได้ว่าผลิตภัณฑ์หนึ่งในแอปมีขอบเขต A และ B และผลิตภัณฑ์ที่สองมีขอบเขต C และ D หรือผสมกันอย่างไรก็ได้ ในกรณีที่ไคลเอ็นต์ไม่ได้ระบุพารามิเตอร์ scope (หรือหาก จะระบุพารามิเตอร์ขอบเขตที่ไม่มีค่า) โทเค็นจะได้รับสิทธิ์ทั้ง 4 ขอบเขต ได้แก่ A, B, C และ ง. ขอย้ำอีกครั้งว่าโทเค็นจะได้รับชุดของขอบเขตซึ่งเป็นการรวมของขอบเขตทั้งหมดที่รู้จัก จากแอปของนักพัฒนาซอฟต์แวร์

ยังมีอีกกรณีหนึ่งที่ลักษณะการทำงานเริ่มต้นคือการส่งคืนโทเค็นเพื่อการเข้าถึงที่มี ขอบเขตที่รู้จัก ซึ่งเป็นกรณีที่นโยบาย 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 แบบ Context-Aware ที่แนบมาด้วย

สมมติว่า 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 เพื่อช่วยอธิบายวิธีรับโทเค็น ขอบเขตและวิธีบังคับใช้ขอบเขต

ตัวพิมพ์เริ่มต้น

สมมติว่าคุณมีแอปนักพัฒนาซอฟต์แวร์ที่มีผลิตภัณฑ์ และรวมผลิตภัณฑ์เหล่านี้เข้าด้วยกัน ขอบเขต ได้แก่ ก ข และ ค การเรียก 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 หรือเว้นว่างไว้)