การใช้ OAuth2 เพื่อเข้าถึง Edge API

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

Apigee Edge ช่วยให้คุณเรียก Edge API ที่มีการตรวจสอบสิทธิ์ด้วยโทเค็น OAuth2 ได้ การรองรับ OAuth2 จะเปิดใช้โดยค่าเริ่มต้นใน Edge สำหรับบัญชีระบบคลาวด์ หากใช้ Edge สำหรับ Private Cloud คุณจะใช้ OAuth2 ไม่ได้หากไม่ตั้งค่า SAML หรือ LDAP ก่อน

วิธีการทำงานของ OAuth2 (กับ Apigee Edge API)

การเรียก Apigee Edge API ต้องมีการตรวจสอบสิทธิ์เพื่อให้เรามั่นใจว่าคุณคือใคร ในการตรวจสอบสิทธิ์ของคุณ เราต้องการให้คุณส่งโทเค็นเพื่อการเข้าถึง OAuth2 ไปพร้อมกับคำขอเข้าถึง API ของคุณ

เช่น หากต้องการรายละเอียดเกี่ยวกับองค์กรใน Edge คุณจะต้องส่งคำขอไปยัง URL ดังตัวอย่างต่อไปนี้

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

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

OAuth2 จะเข้ามามีบทบาทในการตรวจสอบสิทธิ์ของคุณ เราต้องขอให้คุณส่งโทเค็นเพื่อการเข้าถึงมาให้เราในคำขอนั้นด้วย โทเค็นเพื่อการเข้าถึงจะบอกตัวตนของคุณ เพื่อให้เรามั่นใจว่าคุณได้รับอนุญาตให้ดูรายละเอียดขององค์กร

อย่างไรก็ตาม คุณสามารถรับโทเค็นโดยส่งข้อมูลเข้าสู่ระบบของคุณไปยังบริการ Edge OAuth2 ได้ บริการจะตอบสนองด้วยโทเค็นเพื่อการเข้าถึงและรีเฟรช

ขั้นตอน OAuth2: คำขอเริ่มต้น

รูปภาพต่อไปนี้แสดงขั้นตอน OAuth2 เมื่อคุณเข้าถึง Edge API เป็นครั้งแรก

ขั้นตอน OAuth: คำขอแรก
ภาพที่ 1: โฟลว์ OAuth: คำขอแรก

ตามที่รูปที่ 1 แสดงให้เห็น เมื่อคุณส่งคำขอเริ่มต้นไปยัง 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

    หากใช้ไคลเอ็นต์ HTTP อื่น โปรดเพิ่มโทเค็นเพื่อการเข้าถึง เช่น

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. Edge API จะดำเนินการตามคำขอของคุณและโดยปกติจะตอบกลับพร้อมข้อมูล

ขั้นตอน OAuth2: คำขอลำดับต่อมา

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

ขั้นตอน OAuth: คำขอลำดับต่อมา
ภาพที่ 2: โฟลว์ OAuth: คำขอที่ตามมา

ดังที่แสดงในรูปที่ 2 เมื่อคุณมีโทเค็นเพื่อการเข้าถึงอยู่แล้ว ให้ดำเนินการดังนี้

  1. คุณส่งคำขอไปยัง Edge API พร้อมโทเค็นเพื่อการเข้าถึง acurl แนบโทเค็นโดยอัตโนมัติ หากใช้เครื่องมืออื่นๆ คุณจะต้องเพิ่มโทเค็นด้วยตนเอง
  2. Edge API จะดำเนินการตามคำขอของคุณและโดยปกติจะตอบกลับพร้อมข้อมูล

ขั้นตอน OAuth2: เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ

เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ (หลังจาก 12 ชั่วโมง) คุณสามารถใช้โทเค็นการรีเฟรชเพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ได้ โดยทำดังนี้

ขั้นตอน OAuth: การรีเฟรชโทเค็นเพื่อการเข้าถึง
ภาพที่ 3: โฟลว์ OAuth: การรีเฟรชโทเค็นเพื่อการเข้าถึง

ตามที่รูปที่ 3 แสดง เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ

  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 Ulility: มี Wrapper ความสะดวกสบายตามคำสั่ง curl มาตรฐาน สร้างคำขอ HTTP ไปยัง Edge API, รับการเข้าถึงและรีเฟรชโทเค็นจาก get_token รวมถึงส่งโทเค็นเพื่อการเข้าถึงไปยัง Edge API
  • ปลายทางของโทเค็นในบริการ Edge OAuth2: แลกเปลี่ยนข้อมูลเข้าสู่ระบบ Apigee ของโทเค็นเพื่อการเข้าถึงและรีเฟรชผ่านการเรียก Edge API

ยูทิลิตีเหล่านี้จะแลกเปลี่ยนข้อมูลเข้าสู่ระบบของบัญชี Apigee (อีเมลและรหัสผ่าน) ของคุณกับโทเค็นต่างๆ ที่มีระยะเวลาดังต่อไปนี้

  • โทเค็นเพื่อการเข้าถึงจะหมดอายุใน 12 ชั่วโมง
  • โทเค็นการรีเฟรชจะหมดอายุใน 30 วัน

ดังนั้น เมื่อเรียก API ด้วย acurl หรือ get_token สำเร็จแล้ว คุณจะใช้คู่โทเค็นต่อไปได้อีก 30 วัน หลังจากหมดอายุ คุณต้องป้อนข้อมูลเข้าสู่ระบบอีกครั้งและรับโทเค็นใหม่

เข้าถึง Edge API ด้วย OAuth2

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

เราได้อธิบายเกี่ยวกับการเข้าถึง Edge API ด้วย acurl และ curl ไว้ในส่วนถัดไป

ใช้ Acurl

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

ในคำขอที่ตามมา acurl จะใช้โทเค็นที่บันทึกไว้ใน ~/.sso-cli คุณจึงไม่ต้องใส่ข้อมูลเข้าสู่ระบบอีกครั้งจนกว่าโทเค็นจะหมดอายุ

ตัวอย่างต่อไปนี้แสดงคำขอ acurl เริ่มต้นที่ได้รับรายละเอียดสำหรับองค์กร "ahamilton-eval"

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

นอกเหนือจากการรับรายละเอียดเกี่ยวกับองค์กรแล้ว ตัวอย่างนี้ยังแสดงคำขอที่ 2 ที่ได้รับรายการนโยบายภายในพร็อกซี API "helloworld" ด้วย คำขอที่ 2 ใช้ "o" แบบย่อสำหรับ "องค์กร" ใน URL

โปรดทราบว่า acurl จะส่งโทเค็นเพื่อการเข้าถึงในคำขอที่ 2 โดยอัตโนมัติ คุณไม่จำเป็นต้องส่งข้อมูลเข้าสู่ระบบของผู้ใช้เมื่อ acurl จัดเก็บโทเค็น OAuth2 แล้ว โดยจะได้รับโทเค็นจาก ~/.sso-cli สำหรับการเรียกครั้งต่อๆ ไป

ดูข้อมูลเพิ่มเติมได้ที่การใช้ acurl เพื่อเข้าถึง Edge API

ใช้ Curl

คุณสามารถใช้ curl เพื่อเข้าถึง Edge API ได้ โดยคุณจะต้องรับโทเค็นเพื่อการเข้าถึงและรีเฟรชก่อน คุณสามารถรับรายการเหล่านี้ได้โดยใช้ยูทิลิตี เช่น get_token หรือบริการ Edge OAuth2

หลังจากที่บันทึกโทเค็นเพื่อการเข้าถึงเรียบร้อยแล้ว ให้ส่งโทเค็นนั้นในส่วนหัว Authorization ของการเรียกไปยัง Edge API ตามตัวอย่างต่อไปนี้

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

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

การหมดอายุของโทเค็น

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

วิธีรีเฟรชโทเค็นเพื่อการเข้าถึงจะขึ้นอยู่กับเครื่องมือที่คุณใช้อยู่

  • acurl: ไม่ต้องดำเนินการใดๆ acurl จะรีเฟรชโทเค็นเพื่อการเข้าถึงโดยอัตโนมัติเมื่อคุณส่งคำขอที่มีโทเค็นที่ล้าสมัย
  • get_token: โทร get_token เพื่อรีเฟรชโทเค็นเพื่อการเข้าถึง
  • บริการ Edge OAuth2: ส่งคำขอที่มีข้อมูลดังนี้
    • โทเค็นการรีเฟรช
    • ตั้งค่าพารามิเตอร์แบบฟอร์ม grant_type เป็น "refresh_token"

OAuth2 สำหรับผู้ใช้เครื่อง

คุณใช้ยูทิลิตี acurl และ get_token เพื่อเขียนสคริปต์การเข้าถึง Edge API โดยอัตโนมัติด้วยการตรวจสอบสิทธิ์ OAuth2 สำหรับผู้ใช้เครื่องได้ ตัวอย่างต่อไปนี้แสดงวิธีใช้ 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/...'

หรือจะรวมคำขอโทเค็นและการเรียกใช้ curl โดยใช้ยูทิลิตี acurl ก็ได้ เช่น

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

ในทั้ง 2 ตัวอย่างนี้ การตั้งค่า -m เป็นสตริงว่างเปล่าจะป้องกันไม่ให้ผู้ใช้เครื่องได้รับแจ้งให้ใส่รหัส MFA