Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan cakupan OAuth2

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X. info

Topik ini membahas cara menggunakan cakupan OAuth 2.0 di Apigee Edge.

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 Edge 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, Edge dapat menetapkan cakupan ke token tersebut. Untuk memahami bagaimana ini terjadi, Anda harus terlebih dahulu memahami entitas Apigee Edge 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 Edge 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" : "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 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.

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

Saat aplikasi klien meminta token akses dari Apigee Edge, aplikasi tersebut dapat secara opsional menentukan cakupan yang ingin dikaitkan dengan token tersebut. Misalnya, permintaan berikut meminta untuk ruang lingkup "A". Yaitu, klien meminta agar server otorisasi (Edge) 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 http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

Apa yang terjadi?

Ketika menerima permintaan ini, Edge akan mengetahui aplikasi mana yang membuat permintaan tersebut dan aplikasi yang didaftarkan klien (ID klien dan kunci rahasia klien dienkode dalam header autentikasi dasar). Karena parameter kueri scope disertakan, Edge 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.

Bagaimana jika klien tidak melampirkan parameter cakupan? Dalam hal ini, Edge 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 Edge 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 Edge, 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.

Dalam contoh ini, kebijakan hanya akan berhasil jika token akses menyertakan cakupan "A". Jika ini <Scope> 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 http://wwitman-test.apigee.net/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" : "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"
}

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 http://wwitman-test.apigee.net/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 'http://myorg-test.apigee.net/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 http://wwitman-test.apigee.net/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 Edge 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 Edge (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 Edge 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 Edge tidak mempertimbangkan cakupan (elemen <Scope> tidak ada dari kebijakan VerifyAccessToken atau data tersebut kosong).