Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Apa
OAuthV2 adalah kebijakan multi-faset untuk melakukan operasi jenis pemberian OAuth 2.0. Ini adalah kebijakan utama yang digunakan untuk mengonfigurasi endpoint OAuth 2.0 di Apigee Edge.
Tips: Jika Anda ingin mempelajari OAuth di Apigee Edge lebih lanjut, lihat halaman beranda OAuth. Halaman ini menyediakan link ke resource, sampel, video, dan lainnya. Lihat contoh OAuth lanjutan di GitHub untuk mengetahui demonstrasi yang baik tentang cara kebijakan ini digunakan dalam aplikasi yang berfungsi.
Contoh
VerifyAccessToken
VerifyAccessToken
Konfigurasi kebijakan OAuthV2 ini (dengan operasi VerifyAccessToken) memverifikasi bahwa token akses yang dikirimkan ke Apigee Edge valid. Saat operasi kebijakan ini dipicu, Edge akan mencari token akses yang valid dalam permintaan. Jika token akses valid, permintaan akan diizinkan untuk melanjutkan. Jika tidak valid, semua pemrosesan akan berhenti dan error ditampilkan dalam respons.
<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>
Catatan: Hanya Token Pembawa OAuth 2.0 yang didukung. Token Message Authentication Code (MAC) tidak didukung.
Contoh:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Secara default, Edge menerima token akses di header Authorization
dengan
awalan Bearer
. Anda dapat mengubah default ini dengan elemen
<AccessToken>
.
GenerateAccessToken
Membuat token akses
Untuk mengetahui contoh yang menunjukkan cara meminta token akses untuk setiap jenis pemberian yang didukung, baca Meminta token akses dan kode otorisasi. Topik ini menyertakan contoh operasi berikut:
GenerateAuthorizationCode
Buat kode otorisasi
Untuk contoh yang menunjukkan cara meminta kode otorisasi, lihat Meminta kode otorisasi.
RefreshAccessToken
Memperbarui token akses
Untuk contoh yang menunjukkan cara meminta token akses menggunakan token refresh, lihat Memperbarui token akses.
Token alur respons
Membuat token akses di alur respons
Terkadang Anda mungkin perlu membuat token akses di alur respons. Misalnya, Anda dapat melakukan ini sebagai respons terhadap beberapa validasi kustom yang dilakukan di layanan backend. Dalam contoh ini, kasus penggunaan memerlukan token akses dan token refresh, yang mengesampingkan jenis pemberian implisit. Dalam hal ini, kita akan menggunakan jenis pemberian {i>password<i} untuk membuat token. Seperti yang akan Anda lihat, trik agar proses ini berjalan adalah dengan meneruskan header permintaan Otorisasi dengan kebijakan JavaScript.
Pertama, mari kita lihat kebijakan sampel:
<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>
Jika Anda menetapkan kebijakan ini di alur respons, kebijakan akan gagal dengan error 401 UnAuthorized meskipun parameter login yang benar telah ditetapkan dalam kebijakan. Untuk mengatasi masalah ini, Anda perlu menyetel header permintaan Otorisasi.
Header Authorization harus berisi skema akses Dasar dengan client_id:client_secret berenkode Base64.
Anda dapat menambahkan header ini dengan kebijakan JavaScript yang ditempatkan tepat sebelum kebijakan OAuthV2, seperti ini. Variabel "local_clientid" dan "local_secret" harus sudah ditetapkan sebelumnya dan tersedia dalam flow:
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 "Mengenkode kredensial autentikasi dasar".
Referensi elemen
Referensi kebijakan menjelaskan elemen dan atribut kebijakan OAuthV2.
Contoh kebijakan yang ditampilkan di bawah adalah salah satu dari banyak kemungkinan konfigurasi. Contoh ini menunjukkan kebijakan OAuthV2 yang dikonfigurasi untuk operasi GenerateAccessToken. Elemen ini mencakup elemen wajib dan 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>
Atribut <OAuthV2>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Wajib |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini sudah tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Ketersediaan | Opsional |
Jenis | String |
Elemen <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
Secara default, VerifyAccessToken mengharapkan token akses dikirim dalam
header Authorization
.
Anda dapat mengubah default tersebut menggunakan elemen ini. Misalnya, request.queryparam.access_token
menunjukkan bahwa token akses harus ada sebagai parameter kueri yang bernama access_token
.
<AccessToken>request.header.access_token</AccessToken>
ditentukan:
curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"Contoh dengan
<AccessToken>request.queryparam.access_token</AccessToken>
ditentukan:
curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"
Default: |
T/A |
Kehadiran: |
Opsional |
Jenis: | String |
Digunakan dengan operasi: |
|
Elemen <AccessTokenPrefix>
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
Secara default, VerifyAccessToken mengharapkan token akses dikirim di header Otorisasi sebagai Token Pembawa. Contoh:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
Saat ini, Bearer adalah satu-satunya awalan yang didukung.
Default: |
Operator |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: |
Operator |
Digunakan dengan operasi: |
|
Elemen <AppEndUser>
<AppEndUser>request.queryparam.app_enduser</AppEndUser>
Jika ID pengguna akhir aplikasi harus dikirim ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Edge harus mencari ID pengguna akhir. Misalnya, ID tersebut dapat dikirim sebagai parameter kueri atau di header HTTP.
Misalnya, request.queryparam.app_enduser
menunjukkan bahwa AppEndUser harus ada sebagai parameter kueri, seperti, misalnya, ?app_enduser=ntesla@theramin.com
. Misalnya, untuk mewajibkan AppEndUser di header HTTP, tetapkan nilai ini ke request.header.app_enduser
.
Menyediakan setelan ini memungkinkan Anda menyertakan ID pengguna akhir aplikasi dalam token akses. Fitur ini berguna jika Anda ingin dapat mengambil atau mencabut token akses OAuth 2.0 dengan ID pengguna akhir. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan pengambilan dan pencabutan token akses OAuth 2.0 berdasarkan ID pengguna akhir, ID aplikasi, atau keduanya.
Default: |
T/A |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: |
Variabel flow apa pun yang dapat diakses oleh kebijakan saat runtime. |
Digunakan dengan jenis hibah: |
|
<Atribut/Atribut>
<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. Misalnya, Anda mungkin ingin menyematkan ID pengguna atau ID sesi dalam token akses yang dapat diekstrak dan diperiksa pada saat runtime.
Elemen ini memungkinkan Anda menentukan nilai dalam variabel flow atau dari string literal. Jika Anda menentukan variabel dan string, nilai yang ditentukan dalam variabel flow akan digunakan. Jika variabel tidak dapat di-resolve, string tersebut adalah default.
Untuk informasi selengkapnya tentang penggunaan elemen ini, lihat Menyesuaikan Token dan Kode Otorisasi.
Menampilkan atau menyembunyikan atribut khusus dalam respons
Perlu diingat bahwa jika Anda menetapkan elemen GenerateResponse kebijakan ini ke true, representasi lengkap token JSON akan ditampilkan dalam respons, termasuk atribut khusus yang Anda tetapkan. Dalam beberapa kasus, Anda mungkin ingin menyembunyikan beberapa atau semua atribut khusus dalam respons sehingga tidak terlihat oleh aplikasi klien.
Secara default, atribut khusus muncul dalam respons. Jika ingin menyembunyikannya, Anda dapat menetapkan 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
tidak
dipertahankan. Misalnya, Anda membuat token akses dengan atribut khusus yang ingin disembunyikan dalam respons yang dihasilkan. Menetapkan display=false
akan mencapai sasaran tersebut. Namun, jika token akses yang baru nantinya dibuat menggunakan token refresh, atribut khusus yang asli dari token akses tersebut akan muncul dalam respons token refresh. Hal ini karena Edge tidak mengingat bahwa
atribut display
awalnya ditetapkan ke false
dalam kebijakan buat token akses--atribut
khusus hanyalah 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 dalam respons token akses. Sekali lagi, ini mungkin bukan perilaku yang Anda inginkan.
Untuk menyembunyikan atribut khusus dalam kasus ini, Anda memiliki pilihan berikut:
- Reset atribut khusus secara eksplisit dalam kebijakan token refresh dan setel tampilannya ke false. Dalam hal ini, Anda mungkin perlu mengambil nilai kustom asli dari token akses asli menggunakan kebijakan GetOAuthV2Info.
- Gunakan kebijakan JavaScript pascapemrosesan untuk mengekstrak secara manual atribut khusus yang tidak ingin Anda lihat dalam respons.
Lihat juga Menyesuaikan Token dan Kode Otorisasi.
Default: |
|
Kehadiran: |
Opsional |
Nilai valid: |
|
Digunakan dengan jenis hibah: |
|
Elemen <ClientId>
<ClientId>request.formparam.client_id</ClientId>
Dalam beberapa kasus, aplikasi klien harus mengirim client ID ke server otorisasi. Elemen ini memungkinkan Anda menentukan di mana Edge harus mencari client ID. Satu-satunya lokasi
valid yang dapat Anda tetapkan adalah lokasi
default, variabel flow request.formparam.client_id
. Menetapkan ClientId
ke variabel lain tidak didukung.
Lihat juga Meminta token akses dan kode
otorisasi.
Default: |
request.formparam.client_id (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Variabel flow: request.formparam.client_id |
Digunakan dengan jenis hibah: |
Dapat juga digunakan dengan operasi GenerateAuthorizationCode. |
Elemen <Code>
<Code>request.queryparam.code</Code>
Dalam alur jenis pemberian otorisasi, klien harus mengirimkan kode otorisasi ke server otorisasi (Apigee Edge). Elemen ini memungkinkan Anda menentukan tempat Edge untuk mencari kode otorisasi. Misalnya, ID dapat dikirim sebagai parameter kueri, header HTTP, atau parameter formulir (default).
Variabel request.queryparam.auth_code
menunjukkan bahwa kode otorisasi harus ada sebagai parameter kueri, seperti, misalnya, ?auth_code=AfGlvs9
. Misalnya, untuk mewajibkan kode otorisasi di header HTTP, tetapkan nilai ini ke request.header.auth_code
. Lihat juga
Meminta token akses dan
kode otorisasi.
Default: |
request.formparam.code (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
opsional |
Jenis: | String |
Nilai valid: | Semua variabel flow yang dapat diakses oleh kebijakan saat runtime |
Digunakan dengan jenis hibah: | authorization_code |
Elemen <ExpiresIn>
<ExpiresIn>10000</ExpiresIn>
Menerapkan waktu habis masa berlaku token akses dan kode otorisasi dalam milidetik. (Untuk
token refresh, gunakan <RefreshTokenExpiresIn>
.) Nilai waktu habis masa berlaku adalah
nilai yang dihasilkan sistem ditambah nilai <ExpiresIn>
. Jika
<ExpiresIn>
ditetapkan ke -1, masa berlaku token atau kode akan berakhir sesuai dengan masa berlaku token akses OAuth maksimum.
Jika <ExpiresIn>
tidak ditentukan, sistem akan menerapkan
nilai default yang dikonfigurasi di tingkat sistem.
Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default hard code atau dengan
mereferensikan variabel flow. Misalnya, Anda dapat menyimpan nilai masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Contoh,
kvm.oauth.expires_in
.
Dengan Apigee Edge untuk Cloud Publik, Edge menyimpan entity berikut dalam cache selama minimal 180 detik setelah entity diakses.
- Token akses OAuth. Artinya, token yang dicabut mungkin masih berhasil selama maksimal tiga menit, sampai batas cache-nya berakhir.
- Entitas Key Management Service (KMS) (Aplikasi, Developer, Produk API).
- Atribut khusus pada token OAuth dan entitas KMS.
Stanza berikut juga menentukan variabel flow dan nilai default. Perlu diketahui bahwa nilai variabel flow lebih diutamakan daripada nilai default yang ditentukan.
<ExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </ExpiresIn>
Edge tidak mendukung cara untuk memaksa berakhirnya masa berlaku token setelah dibuat. Jika Anda perlu memaksa berakhirnya masa berlaku token (misalnya, berdasarkan kondisi), solusi yang memungkinkan dijelaskan dalam postingan Komunitas Apigee ini.
Secara default, token akses yang sudah habis masa berlakunya akan dihapus permanen dari sistem Apigee Edge secara otomatis 3 hari setelah masa berlakunya habis. Lihat juga Menghapus token akses
Private Cloud: Untuk Edge untuk penginstalan Private Cloud, nilai defaultnya ditetapkan oleh properti conf_keymanagement_oauth_auth_code_expiry_time_in_millis
.
Untuk menetapkan properti ini:
- Buka file
message-processor.properties
di editor. Jika file tidak ada, buat file tersebut:vi /opt/apigee/customer/application/message-processor.properties
- Tetapkan properti sesuai keinginan:
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- Pastikan file properti dimiliki oleh pengguna "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Mulai ulang Pemroses Pesan.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Default: |
Jika tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi pada tingkat sistem. |
Kehadiran: |
Opsional |
Jenis: | Bilangan Bulat |
Nilai valid: |
|
Digunakan dengan jenis hibah: |
Juga digunakan dengan operasi GenerateAuthorizationCode. |
Elemen <ExternalAccessToken>
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
Memberi tahu Apigee Edge tempat menemukan token akses eksternal (token akses yang tidak dihasilkan oleh Apigee Edge).
Variabel request.queryparam.external_access_token
menunjukkan bahwa
token akses eksternal harus ada sebagai parameter kueri, seperti, misalnya, ?external_access_token=12345678
. Misalnya, untuk mewajibkan token akses eksternal
di header HTTP, tetapkan nilai ini
ke request.header.external_access_token
. Lihat juga Menggunakan Token OAuth Pihak Ketiga.
Elemen <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
Jika elemen ini false atau tidak ada, Edge akan memvalidasi client_id dan client_secret secara normal terhadap penyimpanan otorisasi Apigee Edge. Gunakan elemen ini jika Anda ingin bekerja dengan token OAuth pihak ketiga. Untuk mengetahui detail tentang penggunaan elemen ini, lihat Menggunakan Token OAuth Pihak Ketiga.
Default: |
false |
Kehadiran: |
Opsional |
Jenis: | Boolean |
Nilai valid: | benar atau salah |
Digunakan dengan jenis hibah: |
|
Elemen <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Memberi tahu Apigee Edge tempat menemukan kode autentikasi eksternal (kode autentikasi yang tidak dihasilkan oleh Apigee Edge).
Variabel request.queryparam.external_auth_code
menunjukkan bahwa kode autentikasi eksternal harus ada sebagai parameter kueri, seperti, misalnya, ?external_auth_code=12345678
. Misalnya, untuk mewajibkan kode autentikasi eksternal di header HTTP, tetapkan nilai ini ke request.header.external_auth_code
. Lihat juga Menggunakan Token OAuth Pihak Ketiga.
Elemen <ExternalRefreshToken>
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
Memberi tahu Apigee Edge tempat menemukan token refresh eksternal (token refresh yang tidak dihasilkan oleh Apigee Edge).
Variabel request.queryparam.external_refresh_token
menunjukkan bahwa
token refresh eksternal harus ada sebagai parameter kueri, seperti, misalnya, ?external_refresh_token=12345678
. Misalnya, untuk mewajibkan token refresh eksternal di header HTTP, tetapkan nilai ini ke request.header.external_refresh_token
. Lihat juga Menggunakan Token OAuth Pihak Ketiga.
Elemen <GenerateResponse>
<GenerateResponse enabled='true'/>
Jika disetel ke true
, kebijakan akan menghasilkan dan menampilkan respons. Misalnya, untuk
GenerateAccessToken, responsnya mungkin seperti:
{ "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 dikirim. Sebagai gantinya, kumpulan variabel flow akan diisi
dengan nilai yang terkait dengan fungsi kebijakan. Misalnya, variabel flow yang disebut
oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
akan diisi dengan kode autentikasi
yang baru dibuat. Perhatikan bahwa expires_in dinyatakan dalam detik dalam respons.
Default: |
false |
Kehadiran: |
Opsional |
Jenis: | string |
Nilai valid: | benar atau salah |
Digunakan dengan jenis hibah: |
|
Elemen <GenerateErrorResponse>
<GenerateErrorResponse enabled='true'/>
Jika disetel ke true
, kebijakan akan menghasilkan dan menampilkan respons jika atribut ContinueOnError disetel ke benar (true). Jika false
(default), tidak ada respons yang dikirim. Sebagai gantinya, kumpulan variabel flow akan diisi dengan nilai yang terkait dengan
fungsi kebijakan.
Default: |
false |
Kehadiran: |
Opsional |
Jenis: | string |
Nilai valid: | benar atau salah |
Digunakan dengan jenis hibah: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Memberi tahu kebijakan tempat menemukan parameter jenis pemberian yang diteruskan dalam permintaan. Sesuai spesifikasi OAuth 2.0, jenis pemberian harus disertakan dengan permintaan token akses dan kode otorisasi. Variabel dapat berupa header, parameter kueri, atau parameter formulir (default).
Misalnya, request.queryparam.grant_type
menunjukkan bahwa Sandi
harus ada sebagai parameter kueri, seperti, misalnya, ?grant_type=password
.
Misalnya, untuk mewajibkan jenis pemberian di header HTTP, tetapkan nilai ini ke request.header.grant_type
. Lihat juga Meminta token akses dan kode
otorisasi.
Default: |
request.formparam.grant_type (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | string |
Nilai valid: | Variabel, seperti yang dijelaskan di atas. |
Digunakan dengan jenis hibah: |
|
Elemen <Operation>
<Operation>GenerateAuthorizationCode</Operation>
Operasi OAuth 2.0 yang dijalankan oleh kebijakan.
Default: |
Jika |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: |
|
Elemen <PassWord>
<PassWord>request.queryparam.password</PassWord>
Elemen ini hanya digunakan dengan jenis pemberian sandi. Dengan jenis pemberian sandi, kredensial pengguna (sandi dan nama pengguna) harus disediakan untuk kebijakan OAuthV2. Elemen <PassWord>
dan <UserName>
digunakan untuk menentukan variabel tempat Edge dapat menemukan nilai ini. Jika elemen ini tidak ditentukan,
kebijakan akan menemukan nilai (secara default) dalam parameter bentuk yang bernama username
dan password
. Jika nilainya tidak ditemukan, kebijakan akan menampilkan error. Anda dapat menggunakan
elemen <PassWord>
dan <UserName>
untuk mereferensikan
variabel flow apa pun yang berisi kredensial.
Misalnya, Anda dapat meneruskan sandi dalam permintaan token menggunakan parameter kueri dan menetapkan
elemen seperti ini:
<PassWord>request.queryparam.password</PassWord>
.
Untuk
mewajibkan sandi di header HTTP, tetapkan nilai ini
ke request.header.password
.
Kebijakan OAuthV2 tidak melakukan hal lain terhadap nilai kredensial ini; Edge hanya memverifikasi keberadaan nilai kredensial tersebut. Developer API dapat mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.
Lihat juga Meminta token akses dan kode otorisasi.
Default: |
request.formparam.password (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Variabel flow apa pun yang tersedia untuk kebijakan saat runtime. |
Digunakan dengan jenis hibah: | sandi |
Elemen <RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
Menentukan di mana Edge harus mencari parameter redirect_uri
dalam
permintaan.
Tentang URI pengalihan
URI Pengalihan digunakan dengan kode otorisasi dan jenis pemberian implisit. URI pengalihan memberi tahu server otorisasi (Edge) tempat mengirim kode otorisasi (untuk jenis pemberian kode autentikasi) atau token akses (untuk jenis pemberian implisit). Penting untuk memahami kapan parameter ini diperlukan, kapan parameter ini bersifat opsional, dan bagaimana parameter digunakan:
-
(wajib) Jika URL Callback didaftarkan dengan aplikasi developer yang terkait dengan kunci klien permintaan, dan jika
redirect_uri
ada dalam permintaan, maka keduanya harus sama persis. Jika tidak cocok, error akan ditampilkan. Untuk mengetahui informasi tentang cara mendaftarkan aplikasi developer di Edge dan menentukan URL Callback, lihat Mendaftarkan aplikasi dan mengelola kunci API. - (opsional) Jika URL Callback terdaftar, dan
redirect_uri
tidak ada di permintaan, Edge akan mengalihkan ke URL Callback yang terdaftar. - (wajib) Jika URL Callback tidak terdaftar,
redirect_uri
diperlukan. Perhatikan bahwa dalam hal ini, Edge akan menerima URL APA PUN. Kasus ini dapat menimbulkan masalah keamanan, sehingga sebaiknya hanya digunakan dengan aplikasi klien tepercaya. Jika aplikasi klien tidak dipercaya, praktik terbaiknya adalah selalu mewajibkan pendaftaran URL Callback.
Anda dapat mengirim parameter ini dalam parameter kueri atau di header. Variabel
request.queryparam.redirect_uri
menunjukkan bahwa RedirectUri
harus ada sebagai parameter kueri, seperti, misalnya, ?redirect_uri=login.myapp.com
. Misalnya, untuk mewajibkan RedirectUri pada header
HTTP, tetapkan nilai ini ke request.header.redirect_uri
. Lihat
juga Meminta token akses dan
kode otorisasi.
Default: |
request.formparam.redirect_uri (yang dienkode dengan x-www-form-url dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Semua variabel flow yang dapat diakses dalam kebijakan saat runtime |
Digunakan dengan jenis hibah: |
Juga digunakan dengan operasi GenerateAuthorizationCode. |
Elemen <RefreshToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
Saat meminta token akses menggunakan token refresh, Anda harus menyediakan token refresh dalam permintaan. Elemen ini memungkinkan Anda menentukan tempat Edge harus mencari token refresh. Misalnya, URL dapat dikirim sebagai parameter kueri, header HTTP, atau parameter formulir (default).
Variabel request.queryparam.refreshtoken
menunjukkan bahwa token refresh harus ada sebagai parameter kueri, seperti, misalnya, ?refresh_token=login.myapp.com
. Misalnya, untuk mewajibkan RefreshToken di header HTTP, tetapkan nilai ini ke request.header.refresh_token
. Lihat
juga Meminta token akses dan
kode otorisasi.
Default: |
request.formparam.refresh_token (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Semua variabel flow yang dapat diakses dalam kebijakan saat runtime |
Digunakan dengan jenis hibah: |
|
Elemen <RefreshTokenExpiresIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Menerapkan waktu habis masa berlaku token refresh dalam milidetik. Nilai waktu masa berakhir adalah nilai
yang dihasilkan oleh sistem ditambah nilai <RefreshTokenExpiresIn>
. Jika
<RefreshTokenExpiresIn>
ditetapkan ke -1, masa berlaku token refresh
akan berakhir sesuai dengan akhir masa berlaku token refresh OAuth maksimum. Jika <RefreshTokenExpiresIn>
tidak ditentukan,
secara default masa berlaku tidak akan ditentukan.
Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default hard code atau dengan
mereferensikan variabel flow. Misalnya, Anda dapat menyimpan nilai masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Contoh:
kvm.oauth.expires_in
.
Stanza berikut juga menentukan variabel flow dan nilai default. Perhatikan bahwa nilai variabel flow lebih diutamakan daripada nilai default yang ditentukan.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </RefreshTokenExpiresIn>
Private Cloud: Untuk Edge untuk penginstalan Private Cloud, nilai defaultnya ditetapkan oleh properti conf_keymanagement_oauth_refresh_token_expiry_time_in_millis
.
Untuk menetapkan properti ini:
- Buka file
message-processor.properties
di editor. Jika file tidak ada, buat file tersebut:vi /opt/apigee/customer/application/message-processor.properties
- Tetapkan properti sesuai keinginan:
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- Pastikan file properti dimiliki oleh pengguna "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Mulai ulang Pemroses Pesan.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Default: |
Jika tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi pada tingkat sistem. |
Kehadiran: |
Opsional |
Jenis: | Bilangan Bulat |
Nilai valid: |
|
Digunakan dengan jenis hibah: |
|
"refresh_token_expires_in" : "0"
.Elemen <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Elemen ini memberi tahu Edge jenis pemberian yang diminta aplikasi klien. Metode ini hanya digunakan dengan kode otorisasi dan alur jenis pemberian implisit.
Secara default, Edge mencari nilai jenis respons dalam parameter kueri
response_type
. Jika Anda ingin mengganti perilaku default ini, gunakan elemen <ResponseType> untuk
mengonfigurasi variabel flow yang berisi nilai jenis respons. Misalnya, jika Anda menetapkan elemen ini ke request.header.response_type
, Edge akan mencari jenis respons yang akan diteruskan dalam header permintaan. Lihat juga Meminta token akses dan kode
otorisasi.
Default: |
request.formparam.response_type (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional. Gunakan elemen ini jika Anda ingin mengganti perilaku default. |
Jenis: | String |
Nilai valid: | Baik code (untuk jenis pemberian kode otorisasi) atau token
(untuk jenis pemberian implisit) |
Digunakan dengan jenis hibah: |
|
Elemen <Gunakan KembaliRefreshToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
Jika ditetapkan ke true
, token refresh yang ada akan digunakan kembali hingga masa berlakunya habis. Jika
false
, token refresh baru akan dikeluarkan oleh Apigee Edge saat token refresh yang valid
ditampilkan.
Default: |
|
Kehadiran: |
opsional |
Jenis: | boolean |
Nilai valid: |
|
Digunakan dengan jenis hibah: |
|
Elemen <Scope>
<Scope>request.queryparam.scope</Scope>
Jika ada dalam salah satu kebijakan GenerateAccessToken atau GenerateAuthorizationCode, elemen ini akan digunakan untuk menentukan cakupan mana yang akan diberikan token atau kode. Nilai ini
biasanya diteruskan ke kebijakan dalam permintaan dari aplikasi klien. Anda dapat mengonfigurasi elemen untuk
mengambil variabel alur, yang memberi Anda opsi untuk memilih cara cakupan diteruskan dalam permintaan. Pada contoh berikut, request.queryparam.scope
menunjukkan bahwa cakupan harus ada sebagai parameter kueri, misalnya, ?scope=READ
. Misalnya, untuk mewajibkan cakupan di header HTTP, tetapkan nilai ini ke request.header.scope
.
Jika elemen ini muncul dalam kebijakan "VerifyAccessToken", elemen tersebut akan digunakan untuk menentukan cakupan mana yang harus diterapkan oleh kebijakan tersebut. Dalam jenis kebijakan ini, nilai harus berupa nama cakupan yang "di-hardcode" -- Anda tidak dapat menggunakan variabel. Contoh:
<Scope>A B</Scope>
Lihat juga Mengelola cakupan OAuth2 dan Meminta token akses dan kode otorisasi.
Default: |
Tidak ada cakupan |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: |
Variabel flow jika digunakan dengan kebijakan Generate*. Jika digunakan dengan VerifyAccessToken, daftar nama cakupan (string) yang dipisahkan spasi. |
Digunakan dengan jenis hibah: |
|
Elemen <State>
<State>request.queryparam.state</State>
Jika aplikasi klien harus mengirimkan informasi status ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Edge harus mencari nilai status. Misalnya, URL dapat dikirim sebagai parameter kueri atau di header HTTP. Nilai status biasanya digunakan sebagai langkah keamanan untuk mencegah serangan CSRF.
Misalnya, request.queryparam.state
menunjukkan bahwa status harus ada sebagai parameter kueri, seperti, ?state=HjoiuKJH32
. Misalnya, untuk
mewajibkan status di header HTTP, tetapkan nilai ini
ke request.header.state
. Lihat juga Meminta token akses dan kode
otorisasi.
Default: |
Tanpa status |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Semua variabel flow yang dapat diakses oleh kebijakan saat runtime |
Digunakan dengan jenis hibah: |
|
Elemen <StoreToken>
<StoreToken>true</StoreToken>
Tetapkan elemen ini ke true
jika elemen <ExternalAuthorization>
adalah true
. Elemen <StoreToken>
memberi tahu Apigee Edge untuk menyimpan token akses eksternal. Jika tidak, perubahan tidak akan dipertahankan.
Default: |
false |
Kehadiran: |
Opsional |
Jenis: | Boolean |
Nilai valid: | benar atau salah |
Digunakan dengan jenis hibah: |
|
Elemen <SupportedGrantTypes>/<GrantType>
<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 dapat mendukung beberapa jenis pemberian (yaitu, satu endpoint dapat dikonfigurasi untuk mendistribusikan token akses untuk beberapa jenis pemberian). Untuk mengetahui informasi selengkapnya tentang endpoint, lihat Memahami endpoint OAuth. Jenis pemberian diteruskan dalam permintaan token di parameter grant_type
.
Jika jenis pemberian yang didukung tidak ditentukan, satu-satunya jenis pemberian yang diizinkan adalah
authorization_code
dan implicit
. Lihat juga elemen <GrantType> (yaitu elemen dengan tingkat lebih tinggi yang digunakan untuk menentukan lokasi Apigee Edge harus mencari parameter grant_type
yang diteruskan dalam permintaan klien. Edge akan memastikan bahwa nilai parameter grant_type
cocok dengan salah satu jenis pemberian yang didukung).
Default: |
otorisasi _kode dan implisit |
Kehadiran: |
Wajib |
Jenis: | String |
Nilai valid: |
|
Elemen <Tokens>/<Token>
Digunakan dengan operasi ValidateToken dan InvalidateToken. Lihat juga Menyetujui dan mencabut token akses. Elemen <Token> mengidentifikasi variabel flow yang menentukan
sumber token yang akan dicabut. Misalnya, jika developer diminta mengirimkan token akses sebagai parameter kueri bernama access_token
, gunakan request.queryparam.access_token
.
Elemen <UserName>
<UserName>request.queryparam.user_name</UserName>
Elemen ini hanya digunakan dengan jenis pemberian sandi. Dengan jenis pemberian sandi, kredensial pengguna (sandi dan nama pengguna) harus disediakan untuk kebijakan OAuthV2. Elemen <PassWord>
dan <UserName>
digunakan untuk menentukan variabel tempat Edge dapat menemukan nilai ini. Jika elemen ini tidak ditentukan,
kebijakan akan menemukan nilai (secara default) dalam parameter bentuk yang bernama username
dan password
. Jika nilainya tidak ditemukan, kebijakan akan menampilkan error. Anda dapat menggunakan
elemen <PassWord>
dan <UserName>
untuk mereferensikan
variabel flow apa pun yang berisi kredensial.
Misalnya, Anda dapat meneruskan nama pengguna dalam parameter kueri dan menetapkan
elemen <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 hal lain terhadap nilai kredensial ini; Edge hanya memverifikasi keberadaan nilai kredensial tersebut. Developer API dapat mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.
Lihat juga Meminta token akses dan kode otorisasi.
Default: |
request.formparam.username (x-www-form-urlencoding dan ditentukan dalam isi permintaan) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai valid: | Setelan variabel apa pun. |
Digunakan dengan jenis hibah: | sandi |
Memverifikasi token akses
Setelah endpoint token disiapkan untuk proxy API, kebijakan OAuthV2 terkait yang
menentukan operasi VerifyAccessToken
akan disertakan ke Flow yang mengekspos
resource yang dilindungi.
Misalnya, untuk memastikan bahwa semua permintaan ke API telah diotorisasi, kebijakan berikut akan menerapkan verifikasi token akses:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Kebijakan ini disertakan ke resource API agar dilindungi. Untuk memastikan semua permintaan ke API telah diverifikasi, lampirkan kebijakan tersebut ke PreFlow permintaan ProxyEndpoint, sebagai berikut:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
Elemen opsional berikut dapat digunakan untuk mengganti setelan default untuk operasi VerifyAccessToken.
Nama | Deskripsi |
---|---|
Cakupan |
Daftar cakupan yang dipisahkan spasi. Verifikasi akan berhasil jika setidaknya salah satu cakupan yang tercantum ada dalam token akses. Misalnya, kebijakan berikut akan memeriksa token akses untuk memastikan bahwa token tersebut berisi setidaknya salah satu cakupan yang tercantum. Jika ada fitur READ atau TULIS, verifikasi akan berhasil. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | Variabel tempat token akses diharapkan berada. Misalnya
request.queryparam.accesstoken . Secara default, token akses diharapkan
ditampilkan oleh aplikasi di header HTTP Otorisasi, sesuai dengan spesifikasi OAuth 2.0. Gunakan setelan ini jika token akses diperkirakan akan ditampilkan di lokasi non-standar, seperti parameter kueri, atau header HTTP dengan nama selain Otorisasi. |
Lihat juga Memverifikasi token akses dan Meminta token akses dan kode otorisasi.
Menentukan lokasi variabel permintaan
Untuk setiap jenis hibah, kebijakan membuat asumsi tentang lokasi atau informasi yang diperlukan dalam pesan permintaan. Asumsi ini didasarkan pada spesifikasi OAuth 2.0. Jika aplikasi Anda harus menyimpang dari spesifikasi OAuth 2.0, Anda dapat menentukan lokasi yang diharapkan untuk setiap parameter. Misalnya, saat menangani kode otorisasi, Anda dapat menentukan lokasi kode otorisasi, client ID, URI pengalihan, dan cakupannya. Parameter ini dapat ditentukan sebagai header HTTP, parameter kueri, atau parameter formulir.
Contoh di bawah menunjukkan cara menentukan lokasi parameter kode otorisasi yang diperlukan 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 parameter kueri:
... <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 diisi saat setiap kebijakan OAuth dijalankan, sehingga tersedia untuk kebijakan atau aplikasi lain yang dieksekusi di alur proxy API.
Operasi VerifyAccessToken
Operasi VerifyAccessToken dijalankan, sejumlah besar variabel alur diisi dalam konteks eksekusi proxy. Variabel ini memberi Anda properti yang terkait dengan token akses, aplikasi developer, developer, dan perusahaan. Anda dapat menggunakan kebijakan Tetapkan Pesan atau JavaScript, misalnya, untuk membaca salah satu variabel ini dan menggunakannya sesuai kebutuhan nanti dalam alur. Variabel ini juga dapat berguna untuk tujuan proses debug.
proxy.pathsuffix
). Menetapkan variabel flow.resource.name secara eksplisit tidak diperlukan.
Jika produk API tidak dikonfigurasi dengan lingkungan dan proxy API yang valid, flow.resource.name
harus ditetapkan secara eksplisit untuk mengisi variabel produk API dalam alur. Untuk mengetahui detail tentang konfigurasi produk, lihat Menggunakan Edge management
API untuk Memublikasikan API.
Variabel khusus token
Variabel | Deskripsi |
---|---|
organization_name |
Nama organisasi tempat proxy dieksekusi. |
developer.id |
ID developer yang terkait dengan aplikasi klien terdaftar. |
developer.app.name |
Nama developer yang terkait dengan aplikasi klien terdaftar. |
client_id |
Client ID aplikasi klien yang terdaftar. |
grant_type |
Jenis pemberian yang terkait dengan permintaan. |
token_type |
Jenis token yang terkait dengan permintaan. |
access_token |
Token akses yang sedang diverifikasi. |
accesstoken.{custom_attribute} |
Atribut khusus bernama dalam token akses. |
issued_at |
Tanggal penerbitan token akses dinyatakan dalam waktu epoch Unix dalam milidetik. |
expires_in |
Waktu habis masa berlaku untuk token akses. Dinyatakan dalam detik. Meskipun elemen ExpiresIn
menetapkan waktu habis masa berlaku dalam milidetik, dalam respons token dan
variabel alur, nilainya akan habis dalam detik. |
status |
Status token akses (misalnya, disetujui atau dicabut). |
scope |
Cakupan (jika ada) yang terkait dengan token akses. |
apiproduct.<custom_attribute_name> |
Atribut khusus bernama dari produk API yang terkait dengan aplikasi klien yang terdaftar. |
apiproduct.name |
Nama produk API yang dikaitkan dengan aplikasi klien terdaftar. |
revoke_reason |
(Khusus Apigee Hybrid) Menunjukkan alasan token akses dicabut. Nilainya dapat berupa |
Variabel khusus aplikasi
Variabel ini terkait dengan Aplikasi Developer yang terkait dengan token.
Variabel | Deskripsi |
---|---|
app.name |
|
app.id |
|
app.accessType |
|
app.callbackUrl |
|
app.status |
disetujui atau dicabut |
app.scopes |
|
app.appFamily |
|
app.apiproducts |
|
app.appParentStatus |
|
app.appType |
Misalnya: Developer |
app.appParentId |
|
app.created_by |
|
app.created_at |
|
app.last_modified_at |
|
app.last_modified_by |
|
app.{custom_attributes} |
Atribut khusus bernama dari aplikasi klien terdaftar. |
Variabel khusus developer
Jika app.appType adalah "Perusahaan", atribut perusahaan akan diisi dan jika app.appType adalah "Developer", atribut developer akan diisi.
Variabel | Deskripsi |
---|---|
Variabel khusus developer | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
aktif atau tidak aktif |
developer.apps |
|
developer.created_by |
|
developer.created_at |
|
developer.last_modified_at |
|
developer.last_modified_by |
|
developer.{custom_attributes} |
Atribut kustom yang telah diberi nama dari developer. |
Variabel khusus perusahaan
Jika app.appType adalah "Perusahaan", atribut perusahaan akan diisi dan jika app.appType adalah "Developer", atribut developer akan diisi.
Variabel | Deskripsi |
---|---|
company.id |
|
company.displayName |
|
company.apps |
|
company.appOwnerStatus |
|
company.created_by |
|
company.created_at |
|
company.last_modified_at |
|
company.last_modified_by |
|
company.{custom_attributes} |
Atribut khusus perusahaan yang telah diberi nama. |
Operasi GenerateAuthorizationCode
Variabel ini ditetapkan saat operasi GenerateAuthorizationCode berhasil dijalankan:
Awalan: oauthv2authcode.{policy_name}.{variable_name}
Contoh: oauthv2authcode.GenerateCodePolicy.code
Variabel | Deskripsi |
---|---|
code |
Kode otorisasi yang dibuat saat kebijakan dieksekusi. |
redirect_uri |
URI pengalihan yang terkait dengan aplikasi klien yang terdaftar. |
scope |
Cakupan OAuth opsional yang diteruskan dalam permintaan klien. |
client_id |
Client ID yang diteruskan dalam permintaan klien. |
Operasi GenerateAccessToken dan RefreshAccessToken
Variabel ini ditetapkan jika operasi GenerateAccessToken dan RefreshAccessToken berhasil dijalankan. Perlu diperhatikan bahwa variabel token refresh tidak berlaku untuk alur jenis pemberian kredensial klien.
Awalan: oauthv2accesstoken.{policy_name}.{variable_name}
Contoh: oauthv2accesstoken.GenerateTokenPolicy.access_token
Nama variabel | Deskripsi |
---|---|
access_token |
Token akses yang dibuat. |
client_id |
Client ID aplikasi developer yang terkait dengan token ini. |
expires_in |
Nilai masa berlaku token. Lihat elemen <ExpiresIn> untuk mengetahui detailnya. Perhatikan bahwa dalam respons, expires_in dinyatakan dalam detik. |
scope |
Daftar cakupan yang tersedia dikonfigurasi untuk token. Lihat Bekerja dengan cakupan OAuth2. |
status |
Berupa approved atau revoked . |
token_type |
Ditetapkan ke BearerToken . |
developer.email |
Alamat email developer terdaftar yang memiliki aplikasi developer yang terkait dengan token. |
organization_name |
Organisasi tempat proxy dieksekusi. |
api_product_list |
Daftar produk yang terkait dengan aplikasi developer terkait di token. |
refresh_count |
|
refresh_token |
Token refresh yang dibuat. Perlu diperhatikan bahwa token refresh tidak dibuat untuk jenis pemberian kredensial klien. |
refresh_token_expires_in |
Masa aktif token refresh, dalam detik. |
refresh_token_issued_at |
Nilai waktu ini adalah representasi string dari kuantitas stempel waktu 32-bit yang sesuai. Misalnya, 'Wed, 21 Aug 2013 19:16:47 UTC' sesuai dengan nilai stempel waktu 1377112607413. |
refresh_token_status |
Berupa approved atau revoked . |
GenerateAccessTokenImplicitGrant
Variabel ini ditetapkan ketika operasi GenerateAccessTokenImplicit berhasil dijalankan untuk alur jenis pemberian implisit.
Awalan: oauthv2accesstoken.{policy_name}.{variable_name}
Contoh: oauthv2accesstoken.RefreshTokenPolicy.access_token
Variabel | Deskripsi |
---|---|
oauthv2accesstoken.access_token |
Token akses yang dibuat saat kebijakan dieksekusi. |
oauthv2accesstoken.{policy_name}.expires_in |
Nilai masa berlaku token, dalam detik. Lihat elemen <ExpiresIn> untuk mengetahui detailnya. |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Penyebab | Dilempar oleh operasi |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 | Masa berlaku token akses telah berakhir. |
VerifyAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | Token akses dicabut. | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | Resource yang diminta tidak ada produk API apa pun yang terkait dengan token akses. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | Kebijakan diharapkan dapat menemukan token akses dalam variabel yang ditentukan dalam elemen <AccessToken> , tetapi variabel tersebut tidak dapat di-resolve. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | Kebijakan ini seharusnya menemukan kode otorisasi dalam variabel yang ditentukan dalam elemen <Code> , tetapi variabel tersebut tidak dapat di-resolve. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 | Kebijakan ini diharapkan dapat menemukan Client-ID dalam variabel yang ditentukan dalam elemen
<ClientId> , tetapi variabel tersebut tidak dapat di-resolve. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | Kebijakan ini diharapkan menemukan token refresh dalam variabel yang ditentukan dalam elemen
<RefreshToken> , tetapi variabel tersebut tidak dapat di-resolve. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | Kebijakan diharapkan menemukan token dalam variabel yang ditentukan dalam elemen <Tokens> , tetapi variabel tersebut tidak dapat di-resolve. |
ValidasiToken |
steps.oauth.v2.InsufficientScope |
403 | Token akses yang ditampilkan dalam permintaan memiliki cakupan yang tidak cocok dengan cakupan yang ditentukan dalam kebijakan verifikasi token akses. Untuk mempelajari cakupan, lihat Menggunakan cakupan OAuth2. | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 | Token akses yang dikirim dari klien tidak valid. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
Nama error ini ditampilkan jika properti Catatan: Sebaiknya ubah kondisi aturan kesalahan yang ada untuk menangkap nama |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.invalid_request |
400 | Nama error ini digunakan untuk berbagai jenis error, biasanya untuk parameter yang tidak ada
atau salah yang dikirim dalam permintaan. Jika <GenerateResponse> ditetapkan ke false , gunakan variabel kesalahan (yang dijelaskan di bawah) untuk mengambil detail error, seperti nama dan penyebab kesalahan. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | Header otorisasi tidak memiliki kata "Bearer", yang diperlukan. Sebagai
contoh: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
Proxy API tidak ada dalam Produk yang terkait dengan token akses. Tips: Pastikan produk yang terkait dengan token akses dikonfigurasi dengan benar. Misalnya, jika Anda menggunakan karakter pengganti di jalur resource, pastikan karakter pengganti tersebut digunakan dengan benar. Lihat Membuat produk API untuk detailnya. Lihat juga postingan Komunitas Apigee ini untuk panduan lebih lanjut tentang penyebab error ini. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
Nama error ini ditampilkan jika properti |
GenerateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | Kebijakan ini harus menentukan token akses atau kode otorisasi, tetapi tidak keduanya. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 | Elemen <Tokens>/<Token> mengharuskan Anda menentukan jenis token (misalnya refreshtoken ). Jika klien meneruskan jenis yang salah, error ini akan ditampilkan. |
ValidasiToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | Jenis responsnya adalah token , tetapi tidak ada jenis pemberian yang ditentukan. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
Klien menentukan jenis pemberian yang tidak didukung oleh kebijakan (tidak tercantum dalam elemen <SupportedGrantTypes>). Catatan: Saat ini ada bug saat error jenis pemberian yang tidak didukung tidak ditampilkan dengan benar. Jika terjadi error jenis pemberian yang tidak didukung, proxy tidak akan memasuki Alur Error, seperti yang diharapkan. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab |
---|---|
InvalidValueForExpiresIn |
Untuk elemen |
InvalidValueForRefreshTokenExpiresIn |
Untuk elemen <RefreshTokenExpiresIn> , nilai yang valid adalah bilangan bulat positif dan -1 . |
InvalidGrantType |
Jenis pemberian yang tidak valid ditentukan dalam elemen
<SupportedGrantTypes> . Lihat referensi kebijakan untuk mengetahui daftar jenis yang valid. |
ExpiresInNotApplicableForOperation |
Pastikan operasi yang ditentukan dalam elemen <Operations> mendukung berakhirnya masa berlaku. Misalnya, operasi VerifyToken tidak demikian. |
RefreshTokenExpiresInNotApplicableForOperation |
Pastikan operasi yang ditentukan dalam elemen <Operations> mendukung akhir masa berlaku token refresh. Misalnya, operasi VerifyToken tidak demikian. |
GrantTypesNotApplicableForOperation |
Pastikan jenis pemberian yang ditentukan di <SupportedGrantTypes> didukung untuk operasi yang ditentukan. |
OperationRequired |
Anda harus menentukan operasi dalam kebijakan ini menggunakan elemen
Catatan: Jika elemen |
InvalidOperation |
Anda harus menentukan operasi yang valid dalam kebijakan ini menggunakan elemen Catatan: Jika elemen |
TokenValueRequired |
Anda harus menentukan nilai token <Token> dalam elemen
<Tokens> . |
Variabel kesalahan
Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime.
<GenerateResponse>
ditetapkan ke
false
. Jika <GenerateResponse>
adalah
true
, kebijakan akan segera menampilkan respons ke klien jika terjadi error --
alur error dilewati dan variabel ini tidak diisi. Untuk informasi selengkapnya, lihat
Yang perlu Anda
ketahui tentang error kebijakan.Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name = "invalid_request" |
oauthV2.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GenerateAccesstoken.fault.name = invalid_request
Catatan: Untuk operasi VerifyAccessToken, nama kesalahan menyertakan akhiran ini: |
oauthV2.policy_name.fault.cause |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
Contoh respons error
Respons ini akan dikirim kembali ke klien jika elemen <GenerateResponse>
bernilai true.
errorcode
dari respons error. Jangan mengandalkan teks di
faultstring
, karena bisa berubah.Jika <GenerateResponse>
bernilai true, kebijakan akan menampilkan error dalam format ini untuk operasi yang menghasilkan token dan kode. Untuk mengetahui daftar lengkapnya, lihat Referensi respons error HTTP OAuth.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
Jika <GenerateResponse>
bernilai true, kebijakan akan menampilkan error dalam format ini untuk operasi verifikasi dan validasi. Untuk mengetahui daftar lengkapnya, lihat Referensi respons error HTTP OAuth.
{ { "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, skema
kebijakan tersedia di GitHub.
Menggunakan konfigurasi OAuth default
Setiap organisasi (bahkan organisasi uji coba gratis) di Apigee Edge disediakan dengan endpoint token OAuth. Endpoint telah dikonfigurasi sebelumnya dengan kebijakan dalam proxy API yang disebut oauth. Anda dapat mulai menggunakan endpoint token segera setelah membuat akun di Apigee Edge. Untuk mengetahui detailnya, baca Memahami endpoint OAuth.
Menghapus token akses
Secara default, token OAuth2 dihapus permanen dari sistem Apigee Edge 3 hari (259200 detik) setelah token akses dan token refresh (jika ada) habis masa berlakunya. Dalam beberapa kasus, Anda mungkin ingin mengubah setelan default ini. Misalnya, Anda mungkin ingin mempersingkat waktu penghapusan permanen untuk menghemat kapasitas disk jika sejumlah besar token dibuat.
Jika menggunakan Edge untuk Private Cloud, Anda dapat mengubah setelan default ini dengan menetapkan properti organisasi seperti yang dijelaskan di bagian ini. (Penghapusan permanen selama 3 hari untuk token yang sudah habis masa berlakunya berlaku pada Edge untuk Private Cloud versi 4.19.01 dan yang lebih baru. Untuk versi sebelumnya, interval penghapusan permanen 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 diterapkan yang akan terpengaruh; setelan tidak berlaku untuk token yang dibuat sebelumnya.
- Buka file ini untuk diedit:
/opt/apigee/customer/application/message-processor.properties
- Tambahkan properti berikut untuk menetapkan jumlah detik untuk menunggu sebelum menghapus token setelah habis masa berlakunya:
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- Mulai ulang pemroses pesan. Contoh:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
dan <RefreshTokenExpiresIn>
.
Memperbarui setelan penghapusan permanen untuk Edge Private Cloud 4.15.07
Catatan: Hanya token yang dibuat setelah setelan ini diterapkan yang akan terpengaruh; setelan ini tidak berlaku untuk token yang dibuat sebelumnya.
-
Tetapkan nilai positif untuk atribut
<ExpiresIn>
dan<RefreshTokenExpiresIn>
dalam kebijakan OAuthV2. Nilainya dalam milidetik. Contoh:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
Deploy ulang proxy.
-
Gunakan API ini untuk memperbarui properti penghapusan permanen token untuk organisasi Anda:
POST https://<host-name>/v1/organizations/<org-name>
Muatan:
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
Mulai ulang pemroses pesan. Contoh:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
API ini menetapkan properti penghapusan permanen token ke benar untuk organisasi yang disebut AutomationOrganization. Dalam hal ini, token akses akan dihapus permanen dari database 120 detik setelah masa berlaku token dan token refresh berakhir.
Perilaku yang tidak sesuai dengan RFC
Kebijakan OAuthV2 menampilkan respons token yang berisi properti tertentu yang tidak sesuai dengan RFC. Tabel berikut menampilkan properti yang tidak mematuhi kebijakan yang ditampilkan oleh kebijakan OAuthV2 dan properti yang mematuhi kebijakan terkait.
OAuthV2 menampilkan: | Properti yang sesuai dengan RFC adalah: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
(Nilai yang sesuai adalah angka, bukan string.) |
Selain itu, respons error untuk token refresh yang sudah tidak berlaku lagi jika 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"}