Kebijakan GetOAuthV2Info

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 &quot;access_token&quot; (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.

Anda kemudian 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 &quot;refresh_token&quot; (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 name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.

salah Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.

true Opsional
async

Atribut ini tidak digunakan lagi.

salah Tidak digunakan lagi

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

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan menjadi data

Ketersediaan Opsional
Jenis String

&lt;AccessToken&gt; 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.


&lt;AuthorizationCode&gt; 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.

&lt;ClientId&gt; 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.

&lt;IgnoreAccessTokenStatus&gt; 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

&lt;RefreshToken&gt; 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code HTTP status Cause
steps.oauth.v2.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.authorization_code_expired 500 The authorization code sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
steps.oauth.v2.invalid_refresh_token 500 The refresh token sent to the policy is invalid.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see this Apigee Community post for information about troubleshooting this error.
steps.oauth.v2.refresh_token_expired 500 The refresh token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Topik terkait