Menggunakan cakupan OAuth2

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Topik ini membahas cara menggunakan dan menerapkan cakupan OAuth 2.0 dengan Apigee.

Apa itu cakupan OAuth2?

Cakupan OAuth 2.0 menyediakan cara untuk membatasi jumlah akses yang diberikan ke token akses. Misalnya, token akses yang dikeluarkan untuk aplikasi klien dapat diberi akses BACA dan TULIS ke resource yang dilindungi, atau hanya akses BACA. Anda dapat menerapkan API untuk menerapkan cakupan atau kombinasi cakupan yang diinginkan. Jadi, jika klien menerima token yang memiliki cakupan READ, dan klien tersebut mencoba memanggil endpoint API yang memerlukan akses WRITE, panggilan akan gagal.

Dalam topik ini, kita akan membahas cara cakupan ditetapkan ke token akses dan cara Apigee menerapkan cakupan OAuth 2.0. Setelah membaca topik ini, Anda akan dapat menggunakan cakupan dengan percaya diri.

Bagaimana cakupan ditetapkan ke token akses?

Saat membuat token akses, Apigee dapat menetapkan cakupan ke token tersebut. Untuk memahami cara hal ini terjadi, Anda harus terlebih dahulu memahami entitas Apigee berikut: produk API, developer, dan aplikasi developer. Untuk pengantar, lihat Pengantar publikasi. Sebaiknya tinjau materi ini jika perlu sebelum melanjutkan.

Token akses adalah string panjang karakter yang terlihat acak yang memungkinkan Apigee memverifikasi permintaan API masuk (anggap saja sebagai pengganti kredensial nama pengguna/sandi yang umum). Secara teknis, token adalah kunci yang merujuk ke kumpulan metadata yang terlihat seperti ini:

{
  "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" : "[e-mail]",
  "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 token mencakup string token akses sebenarnya, informasi masa berlaku, identifikasi aplikasi developer, developer, dan produk yang terkait dengan token. Anda juga akan melihat bahwa metadata juga menyertakan "cakupan".

Bagaimana cara token mendapatkan cakupannya?

Kunci pertama untuk memahami cakupan adalah mengingat bahwa setiap produk di aplikasi developer dapat memiliki nol atau lebih cakupan yang ditetapkan untuknya. Cakupan ini dapat ditetapkan saat produk dibuat, atau dapat ditambahkan nanti. Nama tersebut ada sebagai daftar nama dan disertakan dalam "metadata" yang terkait dengan setiap produk.

Praktik terbaik:

Anda dapat memberi nama cakupan sesuai keinginan. Dalam kasus sederhana, Anda dapat menggunakan nama sederhana seperti READ, WRITE, atau DELETE. Dalam skenario yang lebih kompleks dengan beberapa produk API, masing-masing dengan beberapa resource yang masing-masing mendukung beberapa tindakan berbeda, WRITE pada satu resource tidak sama dengan WRITE pada resource lain. Dalam kasus ini, praktik terbaiknya adalah menetapkan nama unik untuk setiap cakupan, dalam bentuk URN. Contoh URN mencakup: https://www.examplecompany.com/private_catalog.readonly dan urn:examplecompany:product_price:update.

Pelajari URN lebih lanjut di RFC3986.

Saat Anda membuat aplikasi developer dan menambahkan produk ke dalamnya, Apigee akan melihat semua produk di aplikasi developer dan membuat daftar semua cakupan untuk produk tersebut (daftar cakupan global atau utama aplikasi -- gabungan dari semua cakupan yang dikenali).

Catatan: Ada kasus saat daftar utama diganti. Anda dapat membuat aplikasi developer menggunakan Apigee API. Dengan menggunakan API, Anda dapat menentukan cakupan OAuth untuk aplikasi. Cakupan khusus aplikasi menggantikan daftar utama cakupan yang diambil dari produk yang disertakan dalam aplikasi. Untuk mengetahui informasi tentang API, lihat Membuat Aplikasi Developer. Perhatikan bahwa UI Apigee tidak memungkinkan Anda menentukan cakupan khusus aplikasi. Hal ini hanya dapat dilakukan jika Anda menggunakan API untuk membuat aplikasi.

Saat meminta token akses dari Apigee, aplikasi klien dapat secara opsional menentukan cakupan yang ingin dikaitkan dengan token tersebut. Misalnya, permintaan berikut meminta cakupan "A". Artinya, klien meminta server otorisasi (Apigee) untuk membuat token akses yang memiliki cakupan "A" (memberi otorisasi aplikasi untuk memanggil API yang memiliki cakupan "A"). Aplikasi mengirim permintaan POST seperti ini:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG \
  -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A

Apa yang terjadi?

Saat menerima permintaan ini, Apigee mengetahui aplikasi mana yang membuat permintaan dan aplikasi developer mana yang didaftarkan klien (kunci ID klien dan rahasia klien dienkode di header autentikasi dasar). Karena parameter kueri scope disertakan, Apigee perlu memutuskan apakah ada produk API yang terkait dengan aplikasi developer memiliki cakupan "A". Jika ya, maka token akses dibuat dengan cakupan "A". Cara lain untuk melihat hal ini adalah bahwa parameter kueri scope adalah jenis filter. Jika aplikasi developer mengenali cakupan "A, B, X", dan parameter kueri menentukan "scope=X Y Z", maka hanya cakupan "X" yang akan ditetapkan ke token.

Catatan:

• Jika nilai parameter cakupan cocok dengan none dari cakupan yang dikenali, maka token akan tetap dibuat; namun, token tersebut tidak akan diberi cakupan apa pun (metadata cakupannya akan kosong).
• Hanya cakupan yang ditentukan dalam produk yang diizinkan. Jika tidak ada cakupan yang ditentukan di salah satu produk yang terkait dengan aplikasi developer, Anda tidak dapat membuat token yang berisi cakupan hanya dengan memintanya dalam panggilan untuk membuat token. Anda hanya dapat membuat token dengan cakupan (atau cakupan) jika aplikasi developer yang relevan menyertakan produk yang menentukan cakupan (atau cakupan) yang diminta.

Bagaimana jika klien tidak melampirkan parameter cakupan? Dalam hal ini, Apigee membuat token yang mencakup semua cakupan yang dikenali oleh aplikasi developer. Penting untuk memahami bahwa perilaku defaultnya adalah menampilkan token akses yang berisi gabungan semua cakupan untuk semua produk yang disertakan dalam aplikasi developer.

Jika tidak ada produk yang terkait dengan aplikasi developer yang menentukan cakupan, dan token memiliki cakupan, maka panggilan yang dilakukan dengan token tersebut akan gagal.

Misalkan aplikasi developer mengenali cakupan berikut: A B C D. Ini adalah daftar utama cakupan aplikasi. Bisa jadi satu produk di aplikasi memiliki cakupan A dan B, dan produk kedua memiliki cakupan C dan D, atau kombinasi apa pun. Jika klien tidak menentukan parameter scope (atau jika klien menentukan parameter cakupan tanpa nilai), token akan diberikan keempat cakupan: A, B, C, dan D. Sekali lagi, token menerima serangkaian cakupan yang merupakan gabungan dari semua cakupan yang dikenali oleh aplikasi developer.

Ada satu lagi kasus ketika perilaku defaultnya adalah menampilkan token akses dengan semua cakupan yang dikenali, yaitu saat kebijakan GenerateAccessToken (kebijakan Apigee yang menghasilkan token akses) tidak menentukan elemen <Scope>. Misalnya, berikut adalah kebijakan GenerateAccessToken dengan <Scope> yang ditentukan. Jika elemen <Scope> tersebut tidak ada (atau jika ada tetapi kosong), maka perilaku default akan dijalankan.

<?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>

Bagaimana cakupan diterapkan?

Pertama, ingat bahwa di Apigee, token akses divalidasi dengan kebijakan OAuthV2 (biasanya ditempatkan di awal alur proxy). Kebijakan harus memiliki operasi VerifyAccessToken yang ditentukan. Mari kita lihat kebijakan ini:

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

Perhatikan elemen <Scope>. Digunakan untuk menentukan cakupan yang akan diterima kebijakan.

Catatan: Jika lebih dari satu cakupan ditentukan (misalnya, <Scope>A B C</Scope>), maka kebijakan akan berhasil jika token akses menyertakan salah satu cakupan tersebut (seperti evaluasi 'OR' logis). Jika Anda ingin menerapkan operasi jenis 'AND', dengan beberapa cakupan pada token diterapkan, Anda dapat melakukannya dengan membuat beberapa kebijakan VerifyAccessToken, masing-masing dengan satu cakupan yang berbeda.

Dalam contoh ini, kebijakan hanya akan berhasil jika token akses menyertakan cakupan "A". Jika elemen <Scope> ini tidak ada atau tidak memiliki nilai, kebijakan akan mengabaikan cakupan token akses.

Sekarang, dengan kemampuan untuk memvalidasi token akses berdasarkan cakupan, Anda dapat mendesain API untuk menerapkan cakupan tertentu. Anda dapat melakukannya dengan merancang alur kustom dengan kebijakan VerifyAccessToken yang mendukung cakupan dan terlampir padanya.

Misalkan API Anda memiliki alur yang ditentukan untuk endpoint /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>

Saat alur ini dipicu (permintaan masuk dengan /resourceA di akhiran jalur), kebijakan OAuthV2-VerifyAccessTokenA akan segera dipanggil. Kebijakan ini memverifikasi bahwa token akses valid dan memeriksa cakupan yang didukung token. Jika kebijakan dikonfigurasi seperti contoh di bawah, dengan <Scope>A</Scope>, kebijakan hanya akan berhasil jika token akses memiliki cakupan "A". Jika tidak, error akan ditampilkan.

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

Singkatnya, developer API bertanggung jawab untuk mendesain penerapan cakupan ke dalam API mereka. Mereka melakukannya dengan membuat alur kustom untuk menangani cakupan tertentu, dan melampirkan kebijakan VerifyAccessToken untuk menerapkan cakupan tersebut.

Contoh kode

Terakhir, mari kita lihat beberapa contoh panggilan API untuk membantu mengilustrasikan cara token menerima cakupan dan cara cakupan diterapkan.

Kasus default

Misalnya, Anda memiliki aplikasi developer dengan produk, dan gabungan cakupan produk tersebut adalah: A, B, dan C. Panggilan API ini meminta token akses, tetapi tidak menentukan parameter kueri cakupan.

curl -X POST -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/scopecheck1/token?grant_type=client_credentials

Dalam hal ini, token yang dibuat akan diberi cakupan A, B, dan C (perilaku default). Metadata token akan terlihat seperti ini:

{
  "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" : "[e-mail]",
  "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"
}

Sekarang, misalkan Anda memiliki endpoint API yang memiliki cakupan "A" (yaitu, VerifyAccessToken memerlukan cakupan "A"). Berikut adalah kebijakan 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>

Berikut adalah contoh panggilan ke endpoint yang menerapkan cakupan A:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI \
  https://apitest.acme.com/scopecheck1/resourceA

Panggilan GET ini berhasil:

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

Permintaan berhasil karena kebijakan VerifyAccessToken yang dipicu saat endpoint dipanggil memerlukan cakupan A, dan token akses diberi cakupan A, B, dan C -- perilaku default.

Memfilter kasus

Misalkan Anda memiliki aplikasi developer dengan produk yang memiliki cakupan A, B, C, dan X. Anda meminta token akses dan menyertakan parameter kueri scope, seperti ini:

curl -i -X POST -H content-type:application/x-www-form-urlencoded \
  'https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A X'

Dalam hal ini, token yang dihasilkan akan diberi cakupan A dan X, karena A dan X adalah cakupan yang valid. Ingat bahwa aplikasi developer mengenali cakupan A, B, C, dan X. Dalam hal ini, Anda memfilter daftar produk API berdasarkan cakupan ini. Jika produk memiliki cakupan A atau X, Anda dapat mengonfigurasi endpoint API yang akan menerapkan cakupan ini. Jika produk tidak memiliki cakupan A atau X (misalnya, produk memiliki B, C, dan Z), maka API yang menerapkan cakupan A atau X tidak dapat dipanggil dengan token.

Saat Anda memanggil API dengan token baru:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG \
  https://apitest.acme.com/scopecheck1/resourceX

Token akses divalidasi oleh proxy API. Contoh:

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

Panggilan GET berhasil dan menampilkan respons. Contoh:

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

Permintaan berhasil karena kebijakan VerifyAccessToken memerlukan cakupan A atau X, dan token akses menyertakan cakupan A dan X. Tentu saja, jika elemen <Scope> disetel ke "B", panggilan ini akan gagal.

Ringkasan

Penting untuk memahami cara Apigee menangani cakupan OAuth 2.0. Berikut poin-poin pentingnya:

• Aplikasi developer "mengenali" gabungan semua cakupan yang ditentukan untuk semua produknya.
• Saat meminta token akses, aplikasi memiliki kesempatan untuk menentukan cakupan yang diinginkannya. Apigee (server otorisasi) yang akan menentukan cakupan yang benar-benar akan ditetapkan ke token akses berdasarkan (a) cakupan yang diminta dan (b) cakupan yang dikenali oleh aplikasi developer.
• Jika Apigee tidak dikonfigurasi untuk memeriksa cakupan (elemen <Scope> tidak ada dalam kebijakan VerifyAccessToken atau kosong), panggilan API akan berhasil selama cakupan yang disematkan dalam token akses cocok dengan salah satu cakupan yang dikenali oleh aplikasi developer terdaftar (salah satu cakupan dalam daftar cakupan "utama" aplikasi).
• Jika token akses tidak memiliki cakupan yang terkait dengannya, token tersebut hanya akan berhasil dalam kasus saat Apigee tidak mempertimbangkan cakupan (elemen <Scope> tidak ada dalam kebijakan VerifyAccessToken atau kosong).