Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Apa
Mendapatkan atribut token akses, token refresh, kode otorisasi, dan aplikasi klien atribut dan mengisi variabel dengan nilai-nilai atribut tersebut.
Kebijakan ini berguna saat Anda perlu mengonfigurasi perilaku dinamis bersyarat berdasarkan nilai dalam token atau kode auth. Setiap kali validasi token terjadi, variabel akan terisi secara otomatis dengan nilai-nilai atribut token. Namun, jika belum ada validasi token, Anda dapat menggunakan fitur ini untuk mengisi variabel secara eksplisit dengan nilai atribut token. Lihat juga Menyesuaikan Token dan Kode Otorisasi.
Token akses yang Anda teruskan ke kebijakan ini harus valid atau kebijakan akan menampilkan
invalid_access_token
error.
Contoh
Contoh berikut menggunakan kebijakan Dapatkan Info OAuth V2 untuk mengambil informasi tentang berbagai alur kerja OAuth2 dan kemudian mengakses informasi itu dalam kode.
Token akses
Untuk mendapatkan referensi ke token akses, gunakan elemen <AccessToken>
di
kebijakan Anda.
Contoh berikut mengharapkan menemukan token akses dalam parameter kueri yang bernama "access_token" (detail penerapan yang sebenarnya terserah kepada Anda):
<GetOAuthV2Info name="MyTokenAttrsPolicy"> <AccessToken ref="request.queryparam.access_token"></AccessToken> </GetOAuthV2Info>
Dengan mempertimbangkan token akses, kebijakan akan mencari profil token dan mengisi serangkaian variabel dengan data profil.
Selanjutnya, Anda dapat mengakses variabel menggunakan JavaScript atau cara lain. Contoh berikut mengambil cakupan yang terkait dengan token akses menggunakan JavaScript:
var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');
Perhatikan bahwa untuk mengakses variabel tersebut dalam kode, Anda harus memberikan awalan dengan "oauthv2accesstoken". Untuk mengetahui daftar lengkap variabel yang tersedia melalui token akses, lihat Variabel token akses.
Kode Auth
Untuk mendapatkan atribut kode otorisasi, gunakan <AuthorizationCode>
dalam kebijakan Anda.
Contoh berikut mengharapkan menemukan token akses dalam formulir parameter bernama "code" (detail penerapan yang sebenarnya terserah kepada Anda):
<GetOAuthV2Info name="MyAuthCodeAttrsPolicy"> <AuthorizationCode ref="request.formparam.code"></AuthorizationCode> </GetOAuthV2Info>
Dengan kode autentikasi, kebijakan akan mencari informasi kode dan mengisi serangkaian variabel dengan data kode auth.
Selanjutnya, Anda dapat mengakses variabel menggunakan JavaScript atau cara lain. Contoh berikut mengambil atribut khusus yang terkait dengan kode otorisasi menggunakan JavaScript:
var attr = context.getVariable(‘oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name’);
Perhatikan bahwa untuk mengakses variabel tersebut dalam kode, Anda harus memberikan awalan "oauthv2authcode". Untuk mengetahui daftar lengkap variabel yang tersedia melalui kode autentikasi, lihat Variabel kode otorisasi.
Token refresh
Untuk mendapatkan atribut token refresh, gunakan elemen <RefreshToken>
di
lebih lanjut.
Contoh berikut mengharapkan menemukan token akses dalam parameter kueri yang bernama "refresh_token" (detail penerapan yang sebenarnya terserah kepada Anda):
<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy"> <RefreshToken ref="request.queryparam.refresh_token"/> </GetOAuthV2Info>
Dengan token refresh, kebijakan akan mencari informasi token refresh dan mengisi sekumpulan variabel dengan data token refresh.
Anda kemudian dapat mengakses variabel tersebut menggunakan JavaScript atau cara lainnya. Hal berikut mengambil atribut khusus yang terkait dengan token refresh menggunakan JavaScript:
var attr = context.getVariable(‘oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name’);
Perhatikan bahwa untuk mengakses variabel dalam kode, Anda harus memberikan awalan dengan "oauthv2refreshtoken". Untuk mengetahui daftar lengkap variabel yang tersedia melalui token refresh, lihat Memperbarui variabel token.
Statis
Dalam beberapa kasus yang jarang terjadi, Anda mungkin perlu mendapatkan profil token yang dikonfigurasi secara statis (satu yang tidak dapat diakses melalui variabel). Anda dapat melakukannya dengan memberikan nilai atribut token akses sebagai elemen.
<GetOAuthV2Info name="GetTokenAttributes"> <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken> </GetOAuthV2Info>
Anda dapat melakukan ini dengan semua jenis token lainnya (client ID, kode otorisasi, dan token) juga.
Client ID
Contoh ini menunjukkan cara mengambil informasi tentang aplikasi klien menggunakan client ID.
Setelah dijalankan, kebijakan akan mengisi kumpulan variabel dengan informasi klien. Di sini
ini, kebijakan mengharapkan menemukan client ID dalam parameter kueri
disebut client_id
. Dengan mempertimbangkan client ID, kebijakan akan mencari
profil dan mengisi satu set variabel dengan data profil. Variabel-variabel akan
diawali dengan oauthv2client.
<GetOAuthV2Info name="GetClientAttributes"> <ClientId ref="request.queryparam.client_id"></ClientId> </GetOAuthV2Info>
Selanjutnya, Anda dapat mengakses variabel menggunakan JavaScript atau cara lain. Misalnya, untuk mendapatkan nama aplikasi developer dan email developer yang terkait dengan aplikasi klien menggunakan JavaScript:
context.getVariable("oauthv2client.GetClientAttributes.developer.email"); context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");
Referensi Elemen
Referensi elemen menjelaskan elemen dan atribut kebijakan GetOAuthV2Info.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1" <DisplayName>Get OAuth v2.0 Info 1</DisplayName> <AccessToken ref="variable"></AccessToken> <AuthorizationCode ref="variable"></AuthorizationCode> <ClientId ref="variable"></ClientId> <RefreshToken ref="variable"></RefreshToken> </GetOAuthV2Info>
<GetOAuthV2Info> atribut
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">
Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke Setel ke |
salah | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini tidak digunakan lagi. |
salah | Tidak digunakan lagi |
<DisplayName> elemen
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI 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 |
<AccessToken> elemen
Mengambil profil untuk token akses. Anda meneruskan variabel yang berisi string token akses atau string token literal (jarang terjadi). Dalam contoh ini, token akses yang diambil dari parameter kueri yang diteruskan dalam permintaan. Menggunakan <IgnoreAccessTokenStatus> jika Anda ingin mengembalikan informasi untuk token yang dicabut atau kedaluwarsa.
<AccessToken ref="request.queryparam.access_token"></AccessToken>
Default: |
request.formparam.access_token (x-www-form-url berandadienkode dan ditentukan dalam permintaan isi) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai yang valid: |
Variabel flow yang berisi string token akses atau string literal. |
<AuthorizationCode> elemen
Mengambil profil untuk kode otorisasi. Anda meneruskan variabel yang berisi string kode autentikasi atau string token literal (kasus jarang). Dalam contoh ini, kode autentikasinya yang diambil dari parameter kueri yang diteruskan dalam permintaan. Untuk daftar variabel yang diisi oleh lihat "Variabel flow".
<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>
Default: |
request.formparam.access_token (x-www-form-url berandadienkode dan ditentukan dalam permintaan isi) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai yang valid: |
Variabel flow yang berisi string kode autentikasi, atau string literal. |
<ClientId> elemen
Mengambil informasi yang terkait dengan client ID. Dalam contoh ini, client ID diambil dari parameter kueri yang diteruskan dalam permintaan. Untuk daftar variabel yang diisi oleh operasi ini, lihat "Variabel aliran".
<ClientId ref="request.queryparam.client_id"></ClientId>
Default: |
request.formparam.access_token (x-www-form-url berandadienkode dan ditentukan dalam permintaan isi) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai yang valid: | Variabel flow yang berisi string kode autentikasi, atau string literal. |
<IgnoreAccessTokenStatus> elemen
Menampilkan informasi token meskipun token telah habis masa berlakunya atau dicabut. Elemen ini hanya dapat digunakan dengan token akses. Informasi untuk entitas lain seperti token refresh dan otorisasi kode dikembalikan tanpa memperhatikan statusnya, secara {i>default<i}.
<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>
Default: |
salah |
Kehadiran: |
Opsional |
Jenis: | Boolean |
Nilai yang valid: | benar atau salah |
<RefreshToken> elemen
Mengambil profil untuk token refresh. Anda meneruskan variabel yang berisi string token refresh atau string token literal (kasus jarang). Dalam contoh ini, token refresh yang diambil dari parameter kueri yang diteruskan dalam permintaan. Untuk daftar variabel yang diisi oleh lihat "Variabel flow".
<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>
Default: |
request.formparam.access_token (x-www-form-url berandadienkode dan ditentukan dalam permintaan isi) |
Kehadiran: |
Opsional |
Jenis: | String |
Nilai yang valid: |
Variabel flow yang berisi string token refresh, atau string literal. |
Variabel flow
Kebijakan GetOAuthV2Info mengisi variabel tersebut, dan biasanya digunakan jika Anda membutuhkan data profil, namun pemberian atau validasi belum dilakukan. .
Variabel client ID
Variabel ini diisi saat elemen ClientId ditetapkan:
oauthv2client.{policy_name}.client_id oauthv2client.{policy_name}.client_secret oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris' oauthv2client.{policy_name}.developer.email oauthv2client.{policy_name}.developer.app.name oauthv2client.{policy_name}.developer.id oauthv2client.{policy_name}.{developer_app_custom_attribute_name}
Variabel token akses
Variabel ini diisi saat elemen AccessToken ditetapkan:
oauthv2accesstoken.{policy_name}.developer.id oauthv2accesstoken.{policy_name}.developer.app.name oauthv2accesstoken.{policy_name}.developer.app.id oauthv2accesstoken.{policy_name}.developer.email oauthv2accesstoken.{policy_name}.organization_name oauthv2accesstoken.{policy_name}.api_product_list oauthv2accesstoken.{policy_name}.access_token oauthv2accesstoken.{policy_name}.scope oauthv2accesstoken.{policy_name}.expires_in //in seconds oauthv2accesstoken.{policy_name}.status oauthv2accesstoken.{policy_name}.client_id oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name} oauthv2accesstoken.{policy_name}.refresh_token oauthv2accesstoken.{policy_name}.refresh_token_status oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds oauthv2accesstoken.{policy_name}.refresh_count oauthv2accesstoken.{policy_name}.refresh_token_issued_at oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED
Variabel kode otorisasi
Variabel ini diisi saat elemen AuthorizationCode ditetapkan:
oauthv2authcode.{policy_name}.code oauthv2authcode.{policy_name}.scope oauthv2authcode.{policy_name}.redirect_uri oauthv2authcode.{policy_name}.client_id oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}
Memuat ulang variabel token
Variabel ini diisi saat elemen RefreshToken ditetapkan:
oauthv2refreshtoken.{policy_name}.developer.id oauthv2refreshtoken.{policy_name}.developer.app.name oauthv2refreshtoken.{policy_name}.developer.app.id oauthv2refreshtoken.{policy_name}.developer.email oauthv2refreshtoken.{policy_name}.organization_name oauthv2refreshtoken.{policy_name}.api_product_list oauthv2refreshtoken.{policy_name}.access_token oauthv2refreshtoken.{policy_name}.scope oauthv2refreshtoken.{policy_name}.expires_in //in seconds oauthv2refreshtoken.{policy_name}.status oauthv2refreshtoken.{policy_name}.client_id oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name} oauthv2refreshtoken.{policy_name}.refresh_token oauthv2refreshtoken.{policy_name}.refresh_token_status oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds oauthv2refreshtoken.{policy_name}.refresh_count oauthv2refreshtoken.{policy_name}.refresh_token_issued_at oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd
). Sebagai referensi, skema kebijakan
tersedia di GitHub.
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. Nama-nama {i>error<i} yang ditunjukkan di bawah ini adalah {i>string<i}
yang ditetapkan ke variabel fault.name
saat terjadi error. Lihat Kesalahan
variabel di bawah ini untuk detail lebih lanjut.
Kode error | Status HTTP | Penyebab |
---|---|---|
steps.oauth.v2.access_token_expired |
500 | Masa berlaku token akses yang dikirim ke kebijakan sudah berakhir. |
steps.oauth.v2.authorization_code_expired |
500 | Kode otorisasi yang dikirim ke kebijakan sudah tidak berlaku. |
steps.oauth.v2.invalid_access_token |
500 | Token akses yang dikirim ke kebijakan tidak valid. |
steps.oauth.v2.invalid_client-invalid_client_id |
500 | Client ID yang dikirim ke kebijakan tidak valid. |
steps.oauth.v2.invalid_refresh_token |
500 | Token refresh yang dikirim ke kebijakan tidak valid. |
steps.oauth.v2.invalid_request-authorization_code_invalid |
500 | Kode otorisasi yang dikirim ke kebijakan tidak valid. |
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound |
401 | Harap lihat postingan Komunitas Apigee ini untuk mendapatkan informasi tentang pemecahan masalah error ini. |
steps.oauth.v2.refresh_token_expired |
500 | Masa berlaku token refresh yang dikirim ke kebijakan sudah berakhir. |
Error saat deployment
Lihat pesan yang dilaporkan di UI untuk mengetahui informasi tentang error deployment.
Variabel kesalahan
Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime.
Variabel | Di 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 Matches "IPDeniedAccess" |
oauthV2.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GetTokenInfo.failed = true |
oauthV2.policy_name.fault.name |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id |
oauthV2.policy_name.fault.cause |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | oauthV2.GetTokenInfo.cause = ClientID is Invalid |
Contoh respons error
{ "fault":{ "faultstring":"ClientId is Invalid", "detail":{ "errorcode":"keymanagement.service.invalid_client-invalid_client_id" } } }
Contoh aturan kesalahan
<FaultRule name="OAuthV2 Faults"> <Step> <Name>AM-InvalidClientIdResponse</Name> </Step> <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition> </FaultRule>