Kebijakan OAuthV2

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

Apa

OAuthV2 adalah kebijakan multifaset untuk menjalankan operasi jenis pemberian izin OAuth 2.0. Ini adalah kebijakan utama yang digunakan untuk mengonfigurasi endpoint OAuth 2.0 di Apigee Edge.

Tips: Jika ingin mempelajari OAuth di Apigee Edge lebih lanjut, lihat halaman beranda OAuth. Menyediakan link ke referensi, sampel, video, dan lain-lain. Lihat kursus lanjutan Contoh OAuth di GitHub untuk menunjukkan cara kerja kebijakan ini dalam aplikasi.

Contoh

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

Lihat juga "Dasar pengkodean kredensial autentikasi".

Referensi elemen

Referensi kebijakan menjelaskan elemen dan atribut kebijakan OAuthV2.

Kebijakan contoh yang ditampilkan di bawah adalah salah satu dari banyak kemungkinan konfigurasi. Sampel ini menunjukkan Kebijakan OAuthV2 yang dikonfigurasi untuk operasi GenerateAccessToken. Hal ini mencakup persyaratan yang diperlukan dan elemen opsional. Lihat deskripsi elemen di bagian ini untuk detailnya.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> atribut

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

&lt;DisplayName&gt; elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

&lt;AccessToken&gt; elemen

<AccessToken>request.header.access_token</AccessToken>

Secara default, VerifyAccessToken mengharapkan token akses dikirim di Authorization {i>header<i}. Anda dapat mengubah default tersebut menggunakan elemen ini. Sebagai contoh request.queryparam.access_token menunjukkan bahwa token akses harus ada sebagai parameter kueri yang bernama access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

&lt;AccessTokenPrefix&gt; elemen

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Secara default, VerifyAccessToken mengharapkan token akses dikirim dalam header Otorisasi sebagai Token pemilik. Contoh:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Saat ini, Bearer adalah satu-satunya awalan yang didukung.

&lt;AppEndUser&gt; elemen

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Dalam hal di mana ID pengguna akhir aplikasi harus dikirim ke server otorisasi, elemen ini memungkinkan tentukan di mana Edge harus mencari ID pengguna akhir. Misalnya, dapat dikirim sebagai kueri atau di header HTTP.

Misalnya, request.queryparam.app_enduser menunjukkan bahwa AppEndUser harus ada sebagai parameter kueri, sebagaimana, untuk contoh, ?app_enduser=ntesla@theramin.com. Untuk mewajibkan AppEndUser di HTTP misalnya, tetapkan nilai ini ke request.header.app_enduser.

Menyediakan setelan ini memungkinkan Anda menyertakan ID pengguna akhir aplikasi dalam token akses. Ini berguna jika Anda ingin dapat mengambil atau mencabut token akses OAuth 2.0 pada akhir ID pengguna. Untuk informasi selengkapnya, lihat Mengaktifkan pengambilan dan pencabutan token akses OAuth 2.0 berdasarkan ID pengguna akhir, ID aplikasi, atau keduanya.

&lt;Attributes/Attribute&gt;

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Gunakan elemen ini untuk menambahkan atribut khusus ke token akses atau kode otorisasi. Sebagai misalnya, Anda mungkin ingin menyematkan ID pengguna atau pengenal sesi dalam token akses yang dapat diekstrak dan diperiksa pada saat runtime.

Elemen ini memungkinkan Anda menentukan nilai dalam variabel alur atau dari string literal. Jika Anda menentukan variabel dan string, nilai yang ditetapkan dalam variabel flow akan digunakan. Jika variabel tidak dapat di-resolve, maka stringnya adalah default-nya.

Untuk informasi selengkapnya tentang penggunaan elemen ini, lihat Menyesuaikan Token dan Kode Otorisasi.

Menampilkan atau menyembunyikan atribut khusus di respons

Perlu diingat bahwa jika Anda menetapkan elemen GenerateResponse kebijakan ini ke true, representasi JSON token yang lengkap akan ditampilkan dalam respons, termasuk respons yang Anda tetapkan. Pada beberapa kasus, Anda mungkin ingin menyembunyikan beberapa atau semua dalam respons sehingga tidak terlihat oleh aplikasi klien.

Secara default, atribut khusus muncul dalam respons. Jika Anda ingin menyembunyikannya, Anda dapat mengatur parameter display ke false. Contoh:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Nilai atribut display bukan dipertahankan. Katakanlah Anda membuat token akses dengan atribut khusus yang ingin Anda sembunyikan di respons yang dihasilkan. Menetapkan display=false akan mencapai sasaran tersebut. Namun, jika model token akses dibuat nanti menggunakan token refresh, atribut khusus asli dari token akses akan muncul di respons token refresh. Hal ini karena Edge tidak mengingat bahwa Atribut display awalnya ditetapkan ke false dalam kebijakan pembuatan token akses, hanya merupakan bagian dari metadata token akses.

Anda akan melihat perilaku yang sama jika menambahkan atribut khusus ke kode otorisasi--saat token akses dibuat menggunakan kode tersebut, atribut khusus tersebut akan muncul di token akses yang dihasilkan. Sekali lagi, ini mungkin bukan perilaku yang Anda inginkan.

Untuk menyembunyikan opsi kustom, dalam kasus ini, Anda memiliki pilihan berikut:

• Reset atribut khusus secara eksplisit dalam kebijakan token refresh dan tetapkan tampilannya ke {i>false<i}. Dalam hal ini, Anda mungkin perlu mengambil nilai kustom asli dari versi aslinya token akses menggunakan kebijakan GetOAuthV2Info.
• Gunakan kebijakan JavaScript pascapemrosesan untuk mengekstrak atribut khusus yang tidak Anda miliki secara manual kita lihat dalam respons.

Lihat juga Menyesuaikan Token dan Kode Otorisasi.

&lt;ClientId&gt; elemen

<ClientId>request.formparam.client_id</ClientId>

Dalam beberapa kasus, aplikasi klien harus mengirim ID klien ke server otorisasi. Ini memungkinkan Anda menentukan di mana Edge harus mencari ID klien. Satu-satunya yang valid yang dapat Anda tetapkan adalah variabel flow request.formparam.client_id. Menyetel ClientId ke variabel lain tidak didukung. Lihat juga Meminta token akses dan otorisasi kode tersebut.

&lt;Code&gt; elemen

<Code>request.queryparam.code</Code>

Di alur jenis pemberian otorisasi, klien harus mengirimkan kode otorisasi ke server otorisasi (Apigee Edge). Elemen ini memungkinkan Anda menentukan di mana Edge harus mencari kode otorisasi Anda. Misalnya, URL dapat dikirim sebagai parameter kueri, header HTTP, atau formulir (default).

Variabel, request.queryparam.auth_code menunjukkan bahwa kode otorisasi harus ada sebagai parameter kueri, misalnya untuk contoh, ?auth_code=AfGlvs9. Untuk mewajibkan kode otorisasi dalam misalnya, tetapkan nilai ini ke request.header.auth_code. Lihat juga Meminta token akses dan kode otorisasi Google.

&lt;ExpiresIn&gt; elemen

<ExpiresIn>10000</ExpiresIn> 

Menerapkan waktu habis masa berlaku token akses dan kode otorisasi dalam milidetik. (Untuk token refresh, gunakan <RefreshTokenExpiresIn>.) Nilai waktu masa berlaku adalah nilai yang dihasilkan sistem ditambah nilai <ExpiresIn>. Jika <ExpiresIn> disetel ke -1, masa berlaku token atau kode akan berakhir sesuai masa berlaku token akses OAuth maksimum. Jika <ExpiresIn> tidak ditentukan, sistem akan menerapkan untuk nilai default yang dikonfigurasi di tingkat sistem.

Waktu habis masa berlaku juga dapat disetel saat runtime menggunakan nilai default hard code atau dengan yang merujuk ke variabel flow. Misalnya, Anda dapat menyimpan nilai habis masa berlaku token di nilai kunci memetakan, mengambilnya, menetapkan variabel, dan mereferensikannya dalam kebijakan. Contoh, kvm.oauth.expires_in.

Dengan Apigee Edge for Public Cloud, Edge mempertahankan entity berikut dalam cache minimal selama 180 detik setelah entity diakses.

• Token akses OAuth. Artinya, token yang dicabut mungkin masih berhasil hingga tiga menit, hingga batas {i>cache<i} kedaluwarsa.
• Entitas Key Management Service (KMS) (Aplikasi, Developer, Produk API).
• Atribut khusus pada token OAuth dan entity KMS.

Stanza berikut menentukan variabel alur dan nilai default juga. Perhatikan bahwa alur nilai variabel lebih diprioritaskan daripada nilai default yang ditentukan.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge tidak mendukung cara memaksa habis masa berlaku token setelah dibuat. Jika Anda perlu memaksakan akhir masa berlaku token (misalnya, berdasarkan suatu kondisi), solusi yang dapat dilakukan adalah dijelaskan di postingan Komunitas Apigee ini.

Secara default, token akses yang sudah tidak berlaku akan dihapus dari Apigee Sistem Edge otomatis 3 hari setelah masa berlaku habis. Lihat juga Menghapus akses token

Private Cloud: Untuk penginstalan Edge untuk Private Cloud, setelan default ditetapkan oleh properti conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Untuk menetapkan properti ini:

1. Buka file message-processor.properties di editor. Jika file tidak ada, buat file tersebut:

   vi /opt/apigee/customer/application/message-processor.properties

2. Tetapkan properti sesuai keinginan:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Pastikan file properti dimiliki oleh "apigee" pengguna:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Mulai ulang Pemroses Pesan.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

&lt;ExternalAccessToken&gt; elemen

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Memberi tahu Apigee Edge tempat menemukan token akses eksternal (token akses yang tidak dibuat oleh Apigee Edge).

Variabel request.queryparam.external_access_token menunjukkan bahwa token akses eksternal harus ada sebagai parameter kueri, seperti untuk contoh, ?external_access_token=12345678. Untuk mewajibkan token akses eksternal di header HTTP, misalnya, tetapkan nilai ini ke request.header.external_access_token. Lihat juga Menggunakan OAuth Pihak Ketiga Token.

&lt;ExternalAuthorization&gt; elemen

<ExternalAuthorization>true</ExternalAuthorization>

Jika elemen ini salah atau tidak ada, Edge memvalidasi client_id dan client_secret biasanya terhadap penyimpanan otorisasi Apigee Edge. Gunakan elemen ini ketika Anda ingin bekerja dengan token OAuth pihak ketiga. Untuk detail tentang cara menggunakan elemen ini, lihat Menggunakan OAuth Pihak Ketiga Token.

&lt;ExternalAuthorizationCode&gt; elemen

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Memberi tahu Apigee Edge tempat menemukan kode autentikasi eksternal (kode autentikasi yang tidak dibuat oleh Apigee Edge).

Variabel request.queryparam.external_auth_code menunjukkan bahwa kode autentikasi eksternal harus ada sebagai parameter kueri, sebagaimana, contoh, ?external_auth_code=12345678. Untuk mewajibkan autentikasi eksternal kode di header HTTP, misalnya, tetapkan nilai ini ke request.header.external_auth_code. Lihat juga Menggunakan OAuth Pihak Ketiga Token.

&lt;ExternalRefreshToken&gt; elemen

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Memberi tahu Apigee Edge tempat menemukan token refresh eksternal (token refresh yang tidak dibuat oleh Apigee Edge).

Variabel request.queryparam.external_refresh_token menunjukkan bahwa token refresh eksternal harus ada sebagai parameter kueri, misalnya contoh, ?external_refresh_token=12345678. Untuk mewajibkan token refresh eksternal di header HTTP, misalnya, tetapkan nilai ini ke request.header.external_refresh_token. Lihat juga Menggunakan OAuth Pihak Ketiga Token.

&lt;GenerateResponse&gt; elemen

<GenerateResponse enabled='true'/>

Jika disetel ke true, kebijakan akan membuat dan menampilkan respons. Misalnya, untuk GenerateAccessToken, responsnya mungkin seperti ini:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Jika false, tidak ada respons yang akan dikirim. Sebagai gantinya, kumpulan variabel alur diisi dengan nilai yang terkait dengan fungsi kebijakan. Misalnya, variabel {i>flow<i} yang disebut oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code akan diisi dengan kode auth yang dicetak. Perhatikan bahwa expires_in dinyatakan dalam detik dalam yang dihasilkan.

&lt;GenerateErrorResponse&gt; elemen

<GenerateErrorResponse enabled='true'/>

Jika disetel ke true, kebijakan akan membuat dan menampilkan respons jika Atribut ContinueOnError disetel ke benar (true). Jika false (default), tidak respons dikirim. Sebagai gantinya, kumpulan variabel alur diisi dengan nilai yang terkait dengan fungsi kebijakan.

&lt;GrantType&gt;

<GrantType>request.queryparam.grant_type</GrantType>

Memberi tahu kebijakan tempat parameter jenis pemberian izin yang diteruskan dalam permintaan. Sesuai dengan spesifikasi OAuth 2.0, jenis pemberian harus dilengkapi dengan permintaan untuk token akses dan kode otorisasi Anda. Variabel dapat berupa header, parameter kueri, atau parameter formulir (default).

Misalnya, request.queryparam.grant_type menunjukkan bahwa Sandi harus ada sebagai parameter kueri, misalnya, ?grant_type=password. Untuk mewajibkan jenis pemberian izin di header HTTP, misalnya, tetapkan nilai ini ke request.header.grant_type. Lihat juga Meminta token akses dan otorisasi kode tersebut.

&lt;Operation&gt; elemen

<Operation>GenerateAuthorizationCode</Operation>

Operasi OAuth 2.0 yang dijalankan oleh kebijakan.

&lt;PassWord&gt; elemen

<PassWord>request.queryparam.password</PassWord>

Elemen ini digunakan dengan jenis pemberian sandi saja. Dengan jenis pemberian sandi, kredensial pengguna (sandi dan nama pengguna) harus disediakan untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel di mana Edge dapat menemukan nilai-nilai ini. Jika elemen-elemen ini tidak ditentukan, kebijakan akan menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan menampilkan error. Anda dapat menggunakan elemen <PassWord> dan <UserName> untuk mereferensikan variabel flow yang berisi kredensial.

Misalnya, Anda dapat meneruskan sandi dalam permintaan token menggunakan parameter kueri dan menyetel atribut seperti ini: <PassWord>request.queryparam.password</PassWord>. Hingga memerlukan sandi di header HTTP, tetapkan nilai ini ke request.header.password.

Kebijakan OAuthV2 tidak melakukan apa pun terhadap nilai kredensial ini; Edge sederhana yang memverifikasi keberadaan mereka. Terserah pengembang API untuk mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Meminta token akses dan kode otorisasi.

&lt;RedirectUri&gt; elemen

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Menentukan tempat Edge harus mencari parameter redirect_uri di kolom permintaan.

Tentang URI pengalihan

URI pengalihan digunakan dengan kode otorisasi dan jenis pemberian implisit. Pengalihan URI memberi tahu server otorisasi (Edge) tujuan pengiriman kode otorisasi (untuk kode autentikasi jenis pemberian) atau token akses (untuk jenis pemberian implisit). Penting untuk dipahami kapan ini dilakukan parameter wajib diisi, kapan opsional, dan bagaimana parameter tersebut digunakan:

• (wajib) Jika URL Callback terdaftar dengan aplikasi developer yang dikaitkan dengan kunci klien permintaan, dan jika redirect_uri ada dalam permintaan, maka keduanya harus sama persis. Jika tidak cocok, pesan error akan muncul. Untuk informasi tentang mendaftarkan aplikasi developer di Edge dan menentukan URL Callback, lihat Mendaftarkan aplikasi dan mengelola API .

• (opsional) Jika URL Callback terdaftar, dan redirect_uri tidak ada dari permintaan, lalu Edge mengalihkan ke URL Callback yang terdaftar.
• (wajib) Jika URL Callback tidak terdaftar, berarti redirect_uri tidak diperlukan. Perhatikan bahwa dalam kasus ini, Edge akan menerima URL APA PUN. Kasus ini dapat menyajikan masalah keamanan, sehingga sebaiknya hanya gunakan dengan klien tepercaya aplikasi. Jika aplikasi klien tidak dipercaya, praktik terbaiknya adalah selalu mewajibkan pendaftaran URL Panggilan Balik.

Anda dapat mengirim parameter ini dalam parameter kueri atau dalam header. Tujuan variabel request.queryparam.redirect_uri menunjukkan bahwa RedirectUri harus ada sebagai parameter kueri, sebagaimana, untuk contoh, ?redirect_uri=login.myapp.com. Untuk mewajibkan RedirectUri di HTTP misalnya, tetapkan nilai ini ke request.header.redirect_uri. Lihat juga Meminta token akses dan kode otorisasi Google.

&lt;RefreshToken&gt; elemen

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Saat meminta token akses menggunakan token refresh, Anda harus memberikan token refresh di terhadap permintaan. Elemen ini memungkinkan Anda menentukan di mana Edge harus mencari token refresh. Sebagai misalnya, dapat dikirim sebagai parameter kueri, header HTTP, atau parameter formulir (default).

Variabel request.queryparam.refreshtoken menunjukkan bahwa pemuatan ulang token harus tersedia sebagai parameter kueri, misalnya untuk contoh, ?refresh_token=login.myapp.com. Untuk mewajibkan RefreshToken dalam HTTP misalnya, tetapkan nilai ini ke request.header.refresh_token. Lihat juga Meminta token akses dan kode otorisasi Google.

&lt;RefreshTokenExpiresIn&gt; elemen

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Menerapkan waktu habis masa berlaku token refresh dalam milidetik. Nilai waktu habis masa berlaku adalah sistem nilai yang dihasilkan ditambah nilai <RefreshTokenExpiresIn>. Jika <RefreshTokenExpiresIn> disetel ke -1, token refresh masa berlaku habis sesuai masa berlaku token refresh OAuth maksimum. Jika <RefreshTokenExpiresIn> tidak ditentukan, sistem menerapkan nilai {i>default<i} yang dikonfigurasi di tingkat sistem. Hubungi Dukungan Apigee Edge untuk mengetahui informasi selengkapnya informasi tentang setelan sistem default.

Waktu habis masa berlaku juga dapat disetel saat runtime menggunakan nilai default hard code atau dengan yang merujuk ke variabel flow. Misalnya, Anda dapat menyimpan nilai habis masa berlaku token di nilai kunci memetakan, mengambilnya, menetapkan variabel, dan mereferensikannya dalam kebijakan. Sebagai contoh, kvm.oauth.expires_in.

Stanza berikut menentukan variabel alur dan nilai default juga. Perhatikan bahwa alur nilai variabel lebih diprioritaskan daripada nilai default yang ditentukan.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Private Cloud: Untuk penginstalan Edge untuk Private Cloud, setelan default ditetapkan oleh properti conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Untuk menetapkan properti ini:

1. Buka file message-processor.properties di editor. Jika file tidak ada, buat file tersebut:

   vi /opt/apigee/customer/application/message-processor.properties

2. Tetapkan properti sesuai keinginan:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Pastikan file properti dimiliki oleh "apigee" pengguna:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Mulai ulang Pemroses Pesan.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

&lt;ResponseType&gt; elemen

<ResponseType>request.queryparam.response_type</ResponseType>

Elemen ini memberi tahu Edge jenis pemberian izin yang diminta aplikasi klien. Tabel ini hanya digunakan dengan alur kode otorisasi dan jenis pemberian implisit.

Secara default, Edge mencari nilai jenis respons dalam kueri response_type . Jika Anda ingin mengganti perilaku default ini, gunakan <ResponseType> elemen ke mengonfigurasi variabel alur yang berisi nilai jenis respons. Misalnya, jika Anda menyetel ke request.header.response_type, Edge mencari jenis respons yang yang diteruskan di header permintaan. Lihat juga Meminta token akses dan otorisasi kode tersebut.

&lt;ReuseRefreshToken&gt; elemen

<ReuseRefreshToken>true</ReuseRefreshToken>

Jika ditetapkan ke true, token refresh yang ada akan digunakan kembali hingga masa berlakunya habis. Jika false, token refresh baru diterbitkan oleh Apigee Edge saat token refresh yang valid disajikan.

&lt;Scope&gt; elemen

<Scope>request.queryparam.scope</Scope>

Jika elemen ini ada di salah satu GenerateAccessToken atau GenerateAuthorizationCode kebijakan, kebijakan digunakan untuk menentukan cakupan mana yang akan diberikan token atau kode. Nilai-nilai ini bersifat yang biasanya diteruskan ke kebijakan dalam permintaan dari aplikasi klien. Anda dapat mengkonfigurasi elemen ini untuk mengambil variabel alur, yang memberi Anda opsi untuk memilih cara cakupan diteruskan dalam permintaan. Di beberapa contoh berikut, request.queryparam.scope menunjukkan bahwa cakupan harus ada sebagai parameter kueri, misalnya, ?scope=READ. Untuk mewajibkan di header HTTP, misalnya, tetapkan nilai ini ke request.header.scope.

Jika elemen ini muncul dalam "VerifyAccessToken" , maka digunakan untuk menentukan cakupan yang harus diterapkan oleh kebijakan tersebut. Dalam jenis kebijakan ini, nilai harus berupa "hard code" ruang lingkup Anda tidak dapat menggunakan variabel. Contoh:

<Scope>A B</Scope>

Lihat juga Bekerja dengan OAuth2 cakupan dan Meminta token akses dan kode otorisasi.

&lt;State&gt; elemen

<State>request.queryparam.state</State>

Dalam kasus di mana aplikasi klien harus mengirimkan informasi status ke server otorisasi, elemen ini memungkinkan Anda menentukan di mana Edge harus mencari nilai-nilai status. Misalnya, dapat dikirim sebagai parameter kueri atau dalam header HTTP. Nilai status biasanya digunakan sebagai keamanan untuk mencegah serangan CSRF.

Misalnya, request.queryparam.state menunjukkan bahwa status harus ada sebagai parameter kueri, misalnya, ?state=HjoiuKJH32. Untuk mewajibkan status di header HTTP, misalnya, tetapkan nilai ini ke request.header.state. Lihat juga Lihat juga Meminta token akses dan otorisasi kode tersebut.

&lt;StoreToken&gt; elemen

 <StoreToken>true</StoreToken> 

Setel elemen ini ke true saat <ExternalAuthorization> adalah true. Elemen <StoreToken> memberi tahu Apigee Edge untuk untuk menyimpan token akses eksternal. Jika tidak, peristiwa tersebut tidak akan dipertahankan.

&lt;SupportedGrantTypes&gt;/&lt;GrantType&gt; elemen

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Menentukan jenis pemberian yang didukung oleh endpoint token OAuth di Apigee Edge. Endpoint mungkin mendukung beberapa jenis pemberian izin (yaitu, satu endpoint dapat dikonfigurasi untuk mendistribusikan akses token untuk beberapa jenis pemberian izin.) Untuk informasi selengkapnya tentang endpoint, lihat Memahami OAuth endpoint. Jenis pemberian ini diteruskan dalam permintaan token di grant_type .

Jika tidak ada jenis pemberian yang didukung, maka satu-satunya jenis pemberian yang diizinkan adalah authorization_code dan implicit. Lihat juga elemen &lt;GrantType&gt; (yang merupakan elemen tingkat lebih tinggi yang digunakan menentukan di mana Apigee Edge harus mencari parameter grant_type yang diteruskan terhadap permintaan klien. Edge akan memastikan bahwa nilai parameter grant_type cocok dengan salah satu jenis pemberian yang didukung).

&lt;Tokens&gt;/&lt;Token&gt; elemen

Digunakan dengan operasi ValidateToken dan InvalidateToken. Lihat juga Menyetujui dan mencabut token akses. <Token> mengidentifikasi variabel alur yang mendefinisikan sumber token yang akan dicabut. Jika developer diharapkan untuk mengirimkan token akses sebagai parameter kueri bernama access_token, misalnya, gunakan request.queryparam.access_token.

&lt;UserName&gt; elemen

<UserName>request.queryparam.user_name</UserName>

Elemen ini digunakan dengan jenis pemberian sandi saja. Dengan jenis pemberian sandi, kredensial pengguna (sandi dan nama pengguna) harus disediakan untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel di mana Edge dapat menemukan nilai-nilai ini. Jika elemen-elemen ini tidak ditentukan, kebijakan akan menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan menampilkan error. Anda dapat menggunakan elemen <PassWord> dan <UserName> untuk mereferensikan variabel flow yang berisi kredensial.

Misalnya, Anda dapat meneruskan nama pengguna dalam parameter kueri dan menyetel atribut <UserName> seperti ini: <UserName>request.queryparam.username</UserName>.Untuk mewajibkan nama pengguna di header HTTP, tetapkan nilai ini ke request.header.username.

Kebijakan OAuthV2 tidak melakukan apa pun terhadap nilai kredensial ini; Edge sederhana yang memverifikasi keberadaan mereka. Terserah pengembang API untuk mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Meminta token akses dan kode otorisasi.

Memverifikasi akses token

Setelah endpoint token disiapkan untuk proxy API, kebijakan OAuthV2 terkait yang menentukan operasi VerifyAccessToken yang dikaitkan ke Flow yang mengekspos resource yang dilindungi.

Misalnya, untuk memastikan bahwa semua permintaan ke API telah diotorisasi, kebijakan berikut menerapkan verifikasi token akses:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Kebijakan ini dilampirkan ke resource API yang akan dilindungi. Untuk memastikan bahwa semua permintaan ke API telah diverifikasi, lampirkan kebijakan ke PreFlow permintaan ProxyEndpoint, sebagai berikut:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Elemen opsional berikut bisa digunakan untuk mengganti pengaturan {i>default<i} untuk Operasi VerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

Lihat juga Memverifikasi akses token dan Meminta token akses dan kode otorisasi.

Menentukan lokasi variabel permintaan

Untuk setiap jenis pemberian izin, kebijakan membuat asumsi tentang lokasi atau informasi yang diperlukan dalam pesan permintaan. Asumsi tersebut didasarkan pada spesifikasi OAuth 2.0. Jika aplikasi Anda tidak sesuai dengan spesifikasi OAuth 2.0, maka Anda dapat menentukan lokasi yang diharapkan untuk setiap parameter. Misalnya, saat menangani kode otorisasi, Anda dapat menentukan lokasi kode otorisasi, ID klien, URI pengalihan, dan cakupan. Hal ini dapat ditentukan sebagai Header HTTP, parameter kueri, atau parameter formulir.

Contoh di bawah menunjukkan cara menentukan lokasi kode otorisasi yang diperlukan parameter sebagai header HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Atau, jika diperlukan untuk mendukung basis aplikasi klien, Anda dapat memadupadankan header dan kueri parameter:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Hanya satu lokasi yang dapat dikonfigurasi per parameter.

Variabel flow

Variabel alur yang ditentukan dalam tabel ini akan diisi saat kebijakan OAuth terkait dieksekusi, sehingga tersedia untuk kebijakan atau aplikasi lain yang dieksekusi di proxy API alur kerja.

Operasi VerifyAccessToken

Operasi VerifyAccessToken dijalankan, sejumlah besar variabel alur terisi dalam konteks eksekusi proxy. Variabel ini memberi Anda properti yang terkait dengan akses token, aplikasi developer, developer, dan perusahaan. Anda dapat menggunakan kebijakan Menetapkan Pesan atau JavaScript, misalnya, untuk membaca salah satu variabel ini dan menggunakannya sesuai kebutuhan nanti dalam alur. Ini variabel juga dapat berguna untuk tujuan proses debug.

Variabel khusus token

Variabel khusus aplikasi

Variabel ini terkait dengan Aplikasi Developer yang terkait dengan token.

Variabel khusus developer

Jika app.appType adalah "Company", atribut perusahaan akan diisi dan jika app.appType adalah "Developer", lalu atribut developer akan diisi.

Variabel khusus perusahaan

Jika app.appType adalah "Company", atribut perusahaan akan diisi dan jika app.appType adalah "Developer", lalu atribut developer akan diisi.

GenerateAuthorizationCode operasi

Variabel ini ditetapkan saat operasi GenerateAuthorizationCode dijalankan berhasil:

Awalan: oauthv2authcode.{policy_name}.{variable_name}

Contoh: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken dan Operasi RefreshAccessToken

Variabel ini ditetapkan ketika operasi GenerateAccessToken dan RefreshAccessToken dieksekusi memulai proyek. Perhatikan bahwa variabel token refresh tidak berlaku untuk pemberian kredensial klien {i>type flow<i} (alur jenis).

Awalan: oauthv2accesstoken.{policy_name}.{variable_name}

Contoh: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Variabel ini ditetapkan saat operasi GenerateAccessTokenImplicit berhasil dijalankan untuk alur jenis pemberian implisit.

Awalan: oauthv2accesstoken.{policy_name}.{variable_name}

Contoh: oauthv2accesstoken.RefreshTokenPolicy.access_token

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan kesalahan yang dikembalikan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu kesalahan. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Variabel kesalahan

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime.

Contoh respons error

Respons ini dikirim kembali ke klien jika <GenerateResponse> adalah true.

Jika <GenerateResponse> true, kebijakan akan menampilkan error dalam format ini untuk operasi yang menghasilkan token dan kode. Untuk daftar lengkapnya, lihat Error HTTP OAuth referensi respons.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Jika <GenerateResponse> true, kebijakan akan menampilkan error dalam format ini untuk memverifikasi dan memvalidasi operasi. Untuk daftar lengkap, lihat Error HTTP OAuth referensi respons.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Contoh aturan kesalahan

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Skema kebijakan

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, kebijakan skema tersedia di GitHub.

Bekerja dengan OAuth default konfigurasi

Setiap organisasi (bahkan organisasi uji coba gratis) di Apigee Edge disediakan dengan token OAuth endpoint. Endpoint telah dikonfigurasi sebelumnya dengan kebijakan di proxy API yang disebut oauth. Anda dapat mulai menggunakan endpoint token segera setelah Anda membuat akun di Apigee Edge. Sebagai detail, lihat Memahami OAuth endpoint.

Menghapus token akses

Secara default, token OAuth2 dihapus dari sistem Apigee Edge selama 3 hari (259.200 detik) setelah masa berlaku token akses dan token pembaruan (jika ada). Dalam beberapa kasus, Anda mungkin ingin mengubah {i>default<i} ini. Misalnya, Anda mungkin ingin mempersingkat waktu penghapusan menghemat ruang {i>disk<i} jika token yang dihasilkan dalam jumlah besar.

Jika Anda menggunakan Edge for Private Cloud, Anda dapat mengubah setelan default ini dengan menyetel seperti yang dijelaskan di bagian ini. (Penghapusan token yang sudah tidak berlaku selama 3 hari berlaku untuk Edge untuk Private Cloud versi 4.19.01 dan yang lebih baru. Untuk versi sebelumnya, interval penghapusan default adalah 180 hari.)

Memperbarui setelan penghapusan permanen untuk Edge Private Cloud 4.16.01 dan versi yang lebih baru

Catatan: Hanya token yang dibuat setelah setelan ini yang diterapkan terpengaruh; pengaturan tidak berlaku untuk token yang dihasilkan sebelumnya.

Memperbarui penghapusan permanen pengaturan Edge Private Cloud 4.15.07

Catatan: Hanya token yang dibuat setelah setelan ini diterapkan terpengaruh; pengaturan tidak berlaku untuk token yang dihasilkan sebelumnya.

Perilaku yang tidak sesuai dengan RFC

Kebijakan OAuthV2 menampilkan respons token yang berisi properti tertentu yang tidak sesuai dengan RFC. Tabel berikut menunjukkan konten yang tidak mematuhi kebijakan properti yang ditampilkan oleh kebijakan OAuthV2 dan properti yang sesuai dan terkait.

Selain itu, respons error untuk token refresh yang masa berlakunya sudah berakhir saat grant_type = refresh_token:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Namun, respons yang sesuai dengan RFC adalah:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Topik terkait

• Pengantar OAuth 2,0