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 pada suatu akses sebelumnya yang benar. Misalnya, token akses yang dikeluarkan ke aplikasi klien dapat diberi akses BACA dan TULIS ke sumber daya yang dilindungi, atau hanya akses BACA. Anda dapat menerapkan API untuk menerapkan cakupan atau kombinasi cakupan yang Anda inginkan. Jadi, jika klien menerima token yang memiliki cakupan {i>READ<i}, dan mencoba memanggil endpoint API yang memerlukan akses TULIS, panggilan tersebut akan gagal.

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

Bagaimana cakupan ditetapkan ke token akses?

Saat membuat token akses, Apigee dapat menetapkan cakupan ke token tersebut. Untuk memahami bagaimana ini terjadi, Anda harus terlebih dahulu memahami entitas Apigee ini: produk API, developer, dan aplikasi developer. Untuk pengantar, lihat Pengantar publikasi. Saran dari kami Anda perlu meninjau kembali materi ini sebelum melanjutkan.

Token akses adalah string panjang berisi karakter yang terlihat acak yang memungkinkan Apigee untuk memverifikasi permintaan API yang masuk (anggap saja sebagai pengganti untuk kredensial nama pengguna/sandi). Secara teknis, token adalah kunci yang mengacu pada kumpulan {i>metadata<i} 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 tersebut. Anda akan perhatikan juga bahwa {i>metadata <i}juga menyertakan "{i>scope<i}".

Bagaimana cara token mendapatkan cakupannya?

Kunci pertama untuk memahami ruang lingkup adalah mengingat bahwa setiap produk dalam aplikasi pengembang dapat memiliki nol atau beberapa cakupan yang ditetapkan untuknya. Cakupan ini dapat ditetapkan ketika produk dibuat, atau dapat ditambahkan nanti. Nama tersebut tersedia sebagai daftar nama dan termasuk dalam "metadata" yang terkait dengan setiap produk.

Praktik terbaik:

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

Pelajari URN di RFC3986 lebih lanjut.

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

Catatan: Ada kasus ketika daftar master diganti. Penting dapat digunakan untuk membuat aplikasi developer menggunakan Apigee API. Dengan menggunakan API, Anda dapat menentukan aplikasi. Cakupan khusus aplikasi menggantikan daftar master cakupan yang diambil dari produk yang disertakan dalam aplikasi. Untuk mengetahui informasi tentang API, lihat Membuat Aplikasi Developer. Perlu diperhatikan bahwa UI Apigee tidak mengizinkan Anda menentukan cakupan khusus aplikasi. Hal ini hanya dapat dilakukan jika Anda menggunakan API untuk membuat aplikasi.

Saat aplikasi klien meminta token akses dari Apigee, aplikasi tersebut dapat menentukan cakupan yang ingin dikaitkan dengan token tersebut. Misalnya, permintaan berikut meminta untuk ruang lingkup "A". Yaitu, klien meminta server otorisasi (Apigee) untuk membuat token akses yang memiliki cakupan "A" (memberikan otorisasi kepada aplikasi untuk memanggil API yang memiliki cakupan "A"). Aplikasi mengirimkan 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?

Ketika menerima permintaan ini, Apigee akan mengetahui aplikasi mana yang membuat permintaan tersebut dan Apigee mengetahui aplikasi mana yang aplikasi yang didaftarkan klien (ID klien dan kunci rahasia klien dienkode dalam 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, token akses akan dibuat dengan cakupan "A". Cara lain untuk melihat ini adalah bahwa ruang lingkup parameter kueri adalah jenis filter. Jika aplikasi developer mengenali cakupan "A, B, X", dan parameter kueri menentukan "scope=X Y Z", maka hanya cakupan "X" akan ditugaskan ke sebelumnya yang benar.

Catatan:

• Jika nilai parameter cakupan cocok dengan tidak ada parameter yang dikenali cakupan, maka token masih akan dihasilkan; 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 dalam produk yang terkait dengan aplikasi developer, maka 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 penting untuk dipahami bahwa perilaku {i>default<i} adalah mengembalikan token akses yang berisi gabungan dari 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 aplikasi cakupan. Bisa jadi satu produk dalam 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 token ini menentukan parameter cakupan tanpa nilai), 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 kasus lagi di mana perilaku {i>default<i} adalah mengembalikan token akses dengan semua yang dikenali, dan saat itulah kebijakan GenerateAccessToken (kebijakan Apigee yang menghasilkan token akses) tidak menentukan elemen <Scope>. Misalnya, berikut adalah kebijakan GenerateAccessToken tempat <Scope> ditetapkan. Jika elemen <Scope> tersebut tidak ada (atau jika elemen ada tetapi kosong), maka perilaku default akan dieksekusi.

<?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 ditetapkan. 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>. Alat ini digunakan untuk menentukan cakupan kebijakan terima.

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

Dalam contoh ini, kebijakan hanya akan berhasil jika token akses menyertakan cakupan "A". Jika ini &lt;Scope&gt; dihilangkan atau jika tidak memiliki nilai, maka kebijakan akan mengabaikan ruang lingkup token masing-masing.

Kini, dengan kemampuan untuk memvalidasi token akses berdasarkan cakupan, Anda dapat mendesain API untuk menerapkan cakupan tertentu. Anda dapat melakukannya dengan mendesain alur kustom menggunakan VerifyAccessToken berbasis cakupan kebijakan yang melekat 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 jalurnya akhiran), kebijakan OAuthV2-VerifyAccessTokenA akan segera dipanggil. Kebijakan ini memverifikasi bahwa token akses valid dan ingin mengetahui cakupan yang didukung token tersebut. Jika kebijakan tersebut dikonfigurasi seperti contoh di bawah, dengan <Scope>A</Scope>, kebijakan hanya akan berhasil jika token akses memiliki cakupan "A". Jika tidak, akan muncul error.

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

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

Contoh kode

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

Kasus default

Misalnya Anda memiliki aplikasi developer dengan produk, dan gabungan dari produk-produk tersebut cakupan adalah: A, B, dan C. Panggilan API ini meminta token akses, tetapi tidak menentukan 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 dihasilkan akan diberi cakupan A, B, dan C (perilaku default). Tujuan 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" (yakni, 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 dan 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"
 }

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

Kasus pemfilteran

Misalnya Anda memiliki aplikasi developer dengan produk yang memiliki cakupan A, B, C, dan X. Anda meminta token akses dan sertakan 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 diberikan cakupan A dan X, karena A dan X adalah dan valid. Ingat bahwa aplikasi developer mengenali cakupan A, B, C, dan X. Dalam kasus ini, Anda memfilter daftar produk API berdasarkan cakupan ini. Jika suatu produk memiliki cakupan A atau X, Anda dapat mengonfigurasi endpoint API yang akan menerapkan cakupan ini. Jika produk tidak memiliki cakupan A atau X (katakanlah 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>

Pemicu panggilan GET berhasil dan menampilkan respons. Contoh:

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

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

Ringkasan

Penting untuk memahami bagaimana Apigee menangani cakupan OAuth 2.0. Berikut adalah hal penting yang bisa dipelajari poin:

• Aplikasi developer "mengenali" gabungan dari semua cakupan yang ditentukan untuk semua produknya.
• Ketika sebuah aplikasi meminta token akses, aplikasi memiliki kesempatan untuk menentukan cakupan mana yang akan ingin dimiliki. Apigee (server otorisasi) bertanggung jawab untuk menentukan cakupan mana yang akan menetapkan token akses berdasarkan (a) cakupan yang diminta dan (b) ID yang dikenali oleh aplikasi developer.
• Jika Apigee tidak dikonfigurasi untuk memeriksa cakupan (elemen <Scope> tidak ada di kebijakan VerifyAccessToken atau kosong), maka panggilan API akan berhasil sebagai asalkan cakupan yang disematkan dalam token akses cocok dengan cakupan yang dikenali oleh aplikasi developer terdaftar (salah satu cakupan dalam daftar cakupan "master" aplikasi).
• Jika token akses tidak memiliki lingkup yang terkait dengannya, maka token tersebut hanya akan berhasil jika Apigee tidak mempertimbangkan cakupan (elemen <Scope> tidak ada dari kebijakan VerifyAccessToken atau data tersebut kosong).