Kebijakan OAuthV2

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

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

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Untuk mempelajari lebih lanjut OAuth di Apigee, lihat halaman beranda OAuth. Di sini tersedia link ke referensi, contoh, video, dan lainnya.

Tips: Lihat kebijakan VerifyIAM untuk kebijakan Standar yang menyediakan metode terintegrasi Google Cloud IAM untuk mengelola autentikasi dan otorisasi di proxy.

Contoh

VerifyAccessToken

VerifyAccessToken

Konfigurasi kebijakan OAuthV2 ini (dengan operasi VerifyAccessToken) memverifikasi bahwa token akses yang dikirimkan ke Apigee valid. Saat operasi kebijakan ini dipicu, Apigee akan mencari token akses yang valid dalam permintaan. Jika token akses valid, permintaan diizinkan untuk dilanjutkan. Jika tidak valid, semua pemrosesan akan berhenti dan error akan ditampilkan dalam respons.

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Catatan: Hanya Token Bearer OAuth 2.0 yang didukung. Jenis token lainnya seperti token Message Authentication Code (MAC) tidak didukung.

Aplikasi klien perlu mengirimkan permintaan dengan token. Misalnya, menggunakan curl, perintahnya mungkin:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

Dengan API_ENDPOINT adalah domain yang digunakan untuk mengakses API Anda, seperti yang dikonfigurasi di sistem Apigee Anda.

Secara default, kebijakan OAuthV2 mengekstrak token akses dari header Authorization, dengan menghapus awalan Bearer. Anda dapat mengubah perilaku default ini dengan elemen konfigurasi AccessToken.

GenerateAccessToken

Membuat token akses

Untuk contoh yang menunjukkan cara meminta token akses untuk setiap jenis pemberian izin yang didukung, lihat Mendapatkan token OAuth 2.0. Topik ini mencakup contoh operasi ini:

• Kode otorisasi
• Kredensial klien
• Implisit
• Password

Catatan: Dengan operasi GenerateAccessToken, kebijakan OAuthV2 dapat menampilkan respons yang tidak sepenuhnya mematuhi spesifikasi OAuth 2.0 terkait. Sebagai contoh, properti token_type dalam respons token mungkin tidak mematuhi kebijakan. Untuk mengetahui detail tentang elemen respons yang tidak sesuai ini dan elemen lainnya yang mungkin tidak sesuai, lihat Perilaku yang sesuai dengan RFC.

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 akses JWT

Token akses JWT

Untuk contoh yang menunjukkan cara membuat, memverifikasi, dan memperbarui token akses JWT, lihat Menggunakan token akses JWT.

Token alur respons

Membuat token akses pada alur respons

Terkadang Anda mungkin perlu membuat token akses dalam alur respons. Misalnya, Anda dapat melakukannya sebagai respons terhadap beberapa validasi kustom yang dilakukan di layanan backend. Dalam contoh ini, kasus penggunaan memerlukan token akses dan token refresh, sehingga tidak memungkinkan jenis pemberian implisit. Dalam hal ini, kita akan menggunakan jenis pemberian sandi untuk membuat token. Seperti yang akan Anda lihat, trik agar ini berfungsi adalah meneruskan header permintaan Otorisasi dengan kebijakan JavaScript.

Pertama, mari kita lihat contoh kebijakan:

<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 menerapkan kebijakan ini pada alur respons, kebijakan akan gagal dengan error 401 UnAuthorized meskipun parameter login yang benar ditentukan dalam kebijakan. Untuk mengatasi masalah ini, Anda perlu menyetel header permintaan Otorisasi.

Header Otorisasi harus berisi skema akses Dasar dengan client_id:client_secret yang dienkode Base64.

Anda dapat menambahkan header ini dengan kebijakan JavaScript yang ditempatkan tepat sebelum kebijakan OAuthV2, seperti ini. Variabel konteks "local_clientid" dan "local_secret" harus ditetapkan sebelumnya dan tersedia dalam alur:

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

Peringatan: Kebijakan VerifyAPIKey dan OAuthV2 mungkin mengalami peningkatan latensi p90+ dalam kondisi tertentu. Perilaku ini biasanya diamati saat kecepatan Kueri Per Detik (QPS) sangat rendah (kecepatan satu digit) dan Pemroses Pesan (MP) disediakan secara berlebihan. Latensi yang lebih tinggi dalam skenario ini terutama disebabkan oleh penggunaan cache yang tidak efisien.

Lihat juga Mengenkode kredensial autentikasi dasar.

Referensi elemen

Referensi kebijakan menjelaskan elemen dan atribut kebijakan OAuthV2.

Catatan: Cara Anda mengonfigurasi kebijakan ini, dan elemen yang perlu Anda tentukan, bergantung pada operasi yang Anda inginkan agar kebijakan tersebut lakukan. Misalnya, jika Anda menerapkan jenis pemberian izin kode otorisasi, Anda akan memerlukan empat kebijakan OAuthV2 terpisah untuk melakukan pembuatan kode otorisasi, pembuatan kode akses, validasi kode akses, dan pembuatan token refresh. Referensi ini mencantumkan semua elemen yang dapat digunakan dengan kebijakan ini.

Jika Anda ingin melihat konfigurasi untuk kasus penggunaan jenis pemberian tertentu, lihat halaman beranda OAuth untuk mengetahui daftar penerapan jenis pemberian.

Contoh kebijakan yang ditampilkan di bawah adalah salah satu dari banyak kemungkinan konfigurasi. Contoh ini menunjukkan kebijakan OAuthV2 yang dikonfigurasi untuk operasi GenerateAccessToken. Hal ini mencakup elemen wajib dan opsional. Lihat deskripsi elemen di bagian ini untuk mengetahui 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 umum untuk semua elemen induk kebijakan:

Atribut	Deskripsi	Default	Kehadiran
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 pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.	T/A	Wajib
continueOnError	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini	false	Opsional
enabled	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.	benar	Opsional
async	Atribut ini tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

Elemen <AccessToken>

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

Secara default, saat Operation adalah VerifyAccessToken, kebijakan mengharapkan token akses dikirim di header Authorization sebagai token pemilik; yaitu, dengan awalan "Bearer", diikuti dengan satu spasi kosong. Anda dapat mengubah default tersebut menggunakan elemen ini, dengan menentukan nama variabel yang berisi token akses yang akan diverifikasi. Saat Anda menggunakan elemen ini, kebijakan secara default tidak mencari awalan dalam isi variabel. Jika Anda ingin menentukan bahwa kebijakan harus mencari awalan, gunakan elemen AccessTokenPrefix juga.

Contoh:

• Jika konfigurasi kebijakan adalah:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  Untuk meneruskan token menggunakan curl, Anda dapat menggunakan:

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• Jika konfigurasi kebijakan adalah:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  Untuk meneruskan token menggunakan curl, Anda dapat menggunakan:

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Dengan API_ENDPOINT adalah domain yang digunakan untuk mengakses API Anda, seperti yang dikonfigurasi di sistem Apigee Anda.

Default	T/A
Kehadiran	Opsional
Jenis	String
Nilai yang valid	nama variabel apa pun
Digunakan dengan operasi	VerifyAccessToken

Elemen <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Secara default, saat Operation adalah VerifyAccessToken, kebijakan mengharapkan token akses dikirim di header Authorization sebagai token pemilik; yaitu, dengan awalan "Bearer", diikuti dengan satu spasi kosong. Jika Anda menggunakan elemen AccessToken untuk menentukan lokasi yang berbeda untuk token akses masuk, Anda juga dapat menggunakan elemen ini, AccessTokenPrefix, untuk menentukan awalan yang berbeda dan tidak standar.

Misalnya, jika Anda menentukan:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

Kemudian, kebijakan akan mengekstrak token akses masuk dari header permintaan token, dengan cara ini: jika header dimulai dengan kata "KEY" yang diikuti dengan spasi, kebijakan akan menghapus prefiks dan spasi tersebut, lalu menafsirkan nilai yang tersisa sebagai token akses. Jika awalan yang ditentukan tidak ada di header, kebijakan akan memunculkan kesalahan.

Jika Anda menentukan elemen AccessToken, dan tidak menentukan elemen AccessTokenPrefix, kebijakan akan menafsirkan seluruh nilai variabel yang ditentukan dalam elemen AccessToken sebagai token akses.

Elemen ini hanya efektif jika elemen AccessToken juga digunakan.

Default	-tidak ada-
Kehadiran	Opsional
Jenis	String
Nilai yang valid	string apa pun
Digunakan dengan operasi	VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Menentukan algoritma enkripsi yang digunakan untuk menandatangani token akses JWT. Algoritma RSA (RS*) menggunakan pasangan kunci publik/rahasia, sedangkan algoritma HMAC (HS*) menggunakan rahasia bersama. Elemen ini diperlukan untuk operasi GenerateJWTAccessToken, VerifyJWTAccessToken, dan RefreshJWTAccessToken.

Default	T/A
Kehadiran	Wajib diisi saat menggunakan operasi GenerateJWTAccessToken, VerifyJWTAccessToken, dan RefreshJWTAccessToken.
Jenis	String
Nilai yang valid	HS256, HS384, HS512, RS256, RS384, RS512

Elemen <AppEndUser>

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

Jika ID pengguna akhir aplikasi harus dikirim ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Apigee harus mencari ID pengguna akhir. Misalnya, ID 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=[e-mail]. Untuk mewajibkan AppEndUser di header HTTP, misalnya, tetapkan nilai ini ke request.header.app_enduser.

Dengan memberikan setelan ini, Anda dapat menyertakan ID pengguna akhir aplikasi dalam token akses. Fitur ini berguna jika Anda ingin dapat mengambil atau mencabut token akses OAuth 2.0 berdasarkan ID pengguna akhir. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan pengambilan dan pencabutan token akses OAuth 2.0 menurut ID pengguna akhir, ID aplikasi, atau keduanya.

Default	T/A
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang dapat diakses oleh kebijakan saat runtime.
Digunakan dengan jenis pemberian	authorization_code implisit sandi client_credentials

<Attributes/Attribute>

<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 dapat menyematkan ID pengguna atau ID sesi dalam token akses yang dapat diekstrak dan diperiksa saat runtime.

Elemen ini memungkinkan Anda menentukan nilai dalam variabel alur atau dari string literal. Jika Anda menentukan variabel dan string, nilai yang ditentukan dalam variabel alur akan digunakan. Jika variabel tidak dapat diselesaikan, string akan menjadi default.

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

Catatan:

Anda dapat membuat hingga 18 atribut kustom.

Jika Anda menambahkan atribut kustom ke kode otorisasi, atribut tersebut akan diwarisi oleh token akses yang dibuat dari kode tersebut.

Menampilkan atau menyembunyikan atribut khusus dalam respons

Ingatlah bahwa jika Anda menyetel elemen GenerateResponse kebijakan ini ke true, representasi JSON lengkap token akan ditampilkan dalam respons, termasuk atribut kustom yang Anda tetapkan. Dalam beberapa kasus, Anda mungkin ingin menyembunyikan beberapa atau semua atribut kustom dalam respons agar tidak terlihat oleh aplikasi klien.

Secara default, atribut khusus akan muncul dalam respons. Jika ingin menyembunyikannya, Anda dapat menyetel 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. Misalkan Anda membuat token akses dengan atribut kustom yang ingin disembunyikan dalam respons yang dihasilkan. Menetapkan display=false akan mencapai tujuan tersebut. Namun, jika token akses baru dibuat nanti menggunakan token refresh, atribut kustom asli dari token akses akan muncul dalam respons token refresh. Hal ini karena Apigee tidak mengingat bahwa atribut display awalnya ditetapkan ke false dalam kebijakan pembuatan token akses--atribut kustom hanyalah bagian dari metadata token akses.

Anda akan melihat perilaku yang sama jika menambahkan atribut kustom ke kode otorisasi--saat token akses dibuat menggunakan kode tersebut, atribut kustom tersebut akan muncul dalam respons token akses. Sekali lagi, ini mungkin bukan perilaku yang Anda maksudkan.

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

• Reset atribut kustom 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 pasca-pemrosesan untuk mengekstrak secara manual atribut kustom yang tidak ingin Anda lihat dalam respons.

Lihat juga Menyesuaikan Token dan Kode Otorisasi.

Default	N/A
Kehadiran	Opsional
Nilai yang valid	name -Nama atribut ref - Nilai atribut. Dapat berasal dari variabel alur. display - (Opsional) Memungkinkan Anda menentukan apakah atribut kustom muncul dalam respons atau tidak. Jika true, atribut kustom akan muncul dalam respons (Jika GenerateResponse juga diaktifkan). Jika false, atribut kustom tidak disertakan dalam respons. Nilai defaultnya adalah true. Lihat Menampilkan atau menyembunyikan atribut khusus dalam respons.
Digunakan dengan jenis pemberian	authorization_code implisit sandi client_credentials refresh_token Juga dapat digunakan dengan operasi GenerateAuthorizationCode.

Elemen <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Elemen ini hanya dapat digunakan dengan operasi VerifyAccessToken. Menentukan time-to-live (TTL) pada cache token akses untuk eksekusi kebijakan tertentu. Saat pertama kali memverifikasi token akses OAuth 2, Apigee harus mengambil token akses dari penyimpanan persisten. Operasi ini relatif mahal, jadi Apigee menyimpan dalam cache hasil pencarian token, termasuk status token, daftar produk yang valid untuk token, dan atribut kustom yang dilampirkan ke token. Pemanggilan OAuthV2/VerifyAccessToken berikutnya hingga TTL berakhir akan membaca hasil yang di-cache dalam memori, yang berarti verifikasi token akan jauh lebih cepat.

TTL default untuk cache token akses adalah 180 detik. Elemen ini memungkinkan Anda mengurangi TTL tersebut, sehingga mengorbankan performa demi kebenaran. Salah satu skenario yang membuat hal ini masuk akal adalah jika Anda terkadang mencabut token, dan Anda ingin mengurangi jangka waktu saat Apigee akan terus memperlakukan token yang dicabut sebagai valid.

Rentang yang didukung adalah antara 1 dan 180 detik. Anda dapat memberikan variabel alur dan nilai default. Jika Anda memberikan variabel alur dan jika variabel tersebut berisi nilai numerik, variabel tersebut akan lebih diprioritaskan daripada nilai default yang ditentukan.

Catatan: Performa akan menurun saat Anda menggunakan angka yang lebih rendah untuk masa berlaku cache.

Default	T/A Jika Anda menghilangkan elemen ini, periode habis masa berlaku default untuk token akses yang di-cache adalah 180 detik.
Kehadiran	Opsional
Jenis	Bilangan bulat
Nilai yang valid	Bilangan bulat positif bukan nol. Menentukan waktu habis masa berlaku dalam detik.
Digunakan dengan operasi	VerifyAccessToken

Atribut

Tabel berikut menjelaskan atribut elemen <CacheExpiryInSeconds>

Atribut	Deskripsi	Default	Kehadiran
ref	Referensi ke variabel alur yang berisi nilai untuk masa berlaku cache, yang dinyatakan dalam detik. Jika diberikan, nilai variabel alur akan lebih diprioritaskan daripada nilai default yang ditentukan.	T/A	Opsional

Elemen <ClientId>

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

Dalam beberapa kasus, aplikasi klien harus mengirimkan client ID ke server otorisasi. Elemen ini menentukan bahwa Apigee harus mencari ID klien dalam variabel alur request.formparam.client_id. Menetapkan ClientId ke variabel lain tidak didukung. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.client_id (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur: request.formparam.client_id
Digunakan dengan jenis pemberian	authorization_code sandi implisit client_credentials Juga dapat 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). Dengan elemen ini, Anda dapat menentukan tempat Apigee harus mencari kode otorisasi. Misalnya, ID klien 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. Untuk mewajibkan kode otorisasi di header HTTP, misalnya, tetapkan nilai ini ke request.header.auth_code. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.code (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang dapat diakses oleh kebijakan saat runtime
Digunakan dengan jenis pemberian	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> tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi di tingkat sistem.

Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default yang dikodekan secara permanen atau dengan merujuk variabel alur. Misalnya, Anda dapat menyimpan nilai habis masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Contoh, kvm.oauth.expires_in.

Apigee menyimpan entitas berikut dalam cache selama minimal 180 detik setelah entitas tersebut diakses.

• Token akses OAuth. Artinya, elemen ExpiresIn pada kebijakan OAuth v2 tidak akan dapat mengakhiri masa berlaku token akses dalam waktu kurang dari 180 detik.
• Entitas Key Management Service (KMS) (Aplikasi, Developer, Produk API).
• Atribut kustom pada token OAuth dan entitas KMS.

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

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

Apigee tidak mendukung cara untuk memaksa masa berlaku token berakhir setelah dibuat. Jika Anda perlu memaksa masa berlaku token berakhir (misalnya, berdasarkan kondisi), kemungkinan solusinya dijelaskan dalam postingan Komunitas Apigee ini.

Secara default, token akses yang telah habis masa berlakunya akan dihapus dari sistem Apigee Apigee secara otomatis 3 hari setelah habis masa berlakunya. Lihat juga Menghapus token akses

Default	Jika tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi di tingkat sistem.
Kehadiran	Opsional
Jenis	Bilangan bulat
Nilai yang valid	Bilangan bulat positif bukan nol. Tentukan waktu habis masa berlaku dalam milidetik. Meskipun nilai elemen ini dalam milidetik, nilai yang ditetapkan dalam properti expires_in token dan dalam variabel alur expires_in dinyatakan dalam detik.
Digunakan dengan jenis pemberian	authorization_code implisit sandi client_credentials refresh_token Juga digunakan dengan operasi GenerateAuthorizationCode.

Elemen <ExternalAccessToken>

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

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

Variabel request.queryparam.external_access_token menunjukkan bahwa token akses eksternal harus ada sebagai parameter kueri, misalnya, ?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 Token OAuth Pihak Ketiga.

Elemen <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Jika elemen ini salah atau tidak ada, Apigee akan memvalidasi client_id dan client_secret secara normal terhadap penyimpanan otorisasi Apigee. Gunakan elemen ini jika Anda ingin menggunakan token OAuth pihak ketiga. Untuk mengetahui detail tentang penggunaan elemen ini, lihat Menggunakan Token OAuth Pihak Ketiga.

Default	false
Kehadiran	Opsional
Jenis	Boolean
Nilai yang valid	benar atau salah
Digunakan dengan jenis pemberian	authorization_code sandi client_credentials

Elemen <ExternalAuthorizationCode>

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

Memberi tahu Apigee tempat untuk menemukan kode otorisasi eksternal (kode otorisasi yang tidak dibuat oleh Apigee).

Variabel request.queryparam.external_auth_code menunjukkan bahwa kode autentikasi eksternal harus ada sebagai parameter kueri, seperti, misalnya, ?external_auth_code=12345678. Untuk mewajibkan kode auth eksternal di header HTTP, misalnya, 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 tempat menemukan token refresh eksternal (token refresh yang tidak dibuat oleh Apigee).

Variabel request.queryparam.external_refresh_token menunjukkan bahwa token refresh eksternal harus ada sebagai parameter kueri, seperti, misalnya, ?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 Token OAuth Pihak Ketiga.

Elemen <GenerateResponse>

<GenerateResponse enabled='true'/>

Jika disetel ke true atau jika atribut enabled tidak disertakan, kebijakan akan membuat 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" : "[e-mail]",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Jika disetel ke false atau jika elemen <GenerateResponse> tidak ada, tidak ada respons yang dikirim. Sebagai gantinya, serangkaian variabel alur diisi dengan nilai yang terkait dengan fungsi kebijakan. Misalnya, variabel alur yang disebut oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code diisi dengan kode otorisasi yang baru dibuat. Perhatikan bahwa expires_in dinyatakan dalam detik dalam respons.

Default	true
Kehadiran	Opsional
Jenis	string
Nilai yang valid	benar atau salah
Digunakan dengan jenis pemberian	implisit sandi client_credentials refresh_token Juga dapat digunakan dengan operasi GenerateAuthorizationCode.

Elemen <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

Default	false
Kehadiran	Opsional
Jenis	string
Nilai yang valid	benar atau salah
Digunakan dengan jenis pemberian	implisit sandi client_credentials refresh_token Juga dapat digunakan dengan operasi GenerateAuthorizationCode.

<GrantType>

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

Memberi tahu kebijakan tempat menemukan parameter jenis pemberian yang diteruskan dalam permintaan. Sesuai dengan spesifikasi OAuth 2.0, jenis pemberian izin harus diberikan 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. Untuk mewajibkan jenis pemberian dalam header HTTP, misalnya, tetapkan nilai ini ke request.header.grant_type. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.grant_type (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	string
Nilai yang valid	Variabel, seperti yang dijelaskan di atas.
Digunakan dengan jenis pemberian	authorization_code sandi implisit client_credentials refresh_token

Elemen <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Operasi OAuth 2.0 yang dijalankan oleh kebijakan.

Default	Jika <Operation> tidak ditentukan, Apigee akan melihat daftar <SupportedGrantTypes>. Hanya operasi pada jenis pemberian tersebut yang akan berhasil. Dengan kata lain, Anda dapat menghilangkan <Operation> jika Anda menentukan <GrantType> dalam daftar <SupportedGrantTypes>. Jika <Operation> maupun <SupportedGrantTypes> tidak ditentukan, jenis pemberian default adalah authorization_code. Artinya, permintaan jenis pemberian authorization_code akan berhasil, tetapi semua permintaan lainnya akan gagal.
Kehadiran	Opsional
Jenis	String
Nilai yang valid	GenerateAccessToken - Membuat token akses. Lihat juga Mendapatkan token OAuth 2.0. GenerateAccessTokenImplicitGrant - Membuat token akses untuk jenis pemberian izin implisit. Lihat juga Mendapatkan token OAuth 2.0. GenerateAuthorizationCode - Membuat kode autentikasi. Digunakan dengan jenis pemberian kode otorisasi. Lihat juga Mendapatkan token OAuth 2.0. RefreshAccessToken - Menukar token refresh dengan token akses baru. Lihat juga Mendapatkan token OAuth 2.0. VerifyAccessToken - Memverifikasi bahwa token akses yang dikirim dalam permintaan valid. Lihat contoh VerifyAccessToken di atas dan Memverifikasi token akses. InvalidateToken - Mencabut token akses. Setelah token dicabut, klien tidak dapat menggunakan token tersebut untuk memanggil API yang dilindungi. Lihat juga Menyetujui dan mencabut token akses. Peringatan: Token OAuth di-cache selama tiga menit (180 detik); oleh karena itu, token yang dicabut mungkin masih berhasil digunakan hingga tiga menit, hingga batas cache-nya berakhir. ValidateToken - Mengaktifkan kembali atau "menyetujui" token akses yang sebelumnya dicabut. Lihat juga Menyetujui dan mencabut token akses. Operasi token akses JWT tambahan Jika Anda lebih memilih menggunakan token akses JWT daripada token string buram, operasi berikut juga tersedia untuk membuat dan memvalidasi token JWT. Untuk mengetahui detailnya, lihat Menggunakan operasi token JWT OAuth: GenerateJWTAccessToken - Menghasilkan token akses dengan JWT yang ditandatangani. Lihat Membuat token akses JWT. GenerateJWTAccessTokenImplicitGrant - Membuat token akses dengan JWT yang ditandatangani untuk jenis pemberian implisit. Lihat Membuat token akses JWT. VerifyJWTAccessToken - Memverifikasi token akses JWT yang ditandatangani. Lihat juga Memverifikasi token akses JWT. RefreshJWTAccessToken - Menukar token refresh dengan token akses JWT baru. Lihat juga Memperbarui token akses JWT.

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 tersedia untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel tempat Apigee dapat menemukan nilai ini. Jika elemen ini tidak ditentukan, kebijakan mengharapkan untuk menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan memunculkan 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 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 dengan nilai kredensial ini; Apigee hanya memverifikasi bahwa nilai tersebut ada. Developer API yang akan mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.password (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang tersedia untuk kebijakan saat runtime.
Digunakan dengan jenis pemberian	sandi

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Menyediakan kunci pribadi yang digunakan untuk memverifikasi atau menandatangani token akses berformat JWT dengan algoritma RSA. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur. Gunakan hanya jika nilai elemen Algorithm adalah salah satu dari RS256, RS384, atau RS512. Untuk mengetahui informasi selengkapnya, lihat Menggunakan operasi token OAuth JWT.

Catatan: Untuk melindungi rahasia, sebaiknya simpan kunci di set properti yang tercakup dalam lingkungan atau peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Mengakses nilai set properti dan Menggunakan peta nilai kunci.

Default	T/A
Kehadiran	Wajib diisi jika nilai elemen Algorithm adalah salah satu dari HS256, HS384, atau HS512.
Jenis	String
Nilai yang valid	Variabel alur yang berisi string yang merepresentasikan nilai kunci pribadi RSA berenkode PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Menentukan kunci publik atau sertifikat publik yang digunakan untuk memverifikasi tanda tangan pada token akses berformat JWT yang ditandatangani dengan algoritma RSA. Gunakan atribut ref untuk meneruskan kunci/sertifikat dalam variabel alur. Gunakan hanya jika nilai elemen Algorithm adalah salah satu dari RS256, RS384, atau RS512.

Default	T/A
Kehadiran	Untuk memverifikasi JWT yang ditandatangani dengan algoritma RSA, Anda harus menggunakan elemen Sertifikat, JWKS, atau Nilai.
Jenis	String
Nilai yang valid	Variabel atau string alur.

Elemen <RedirectUri>

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

Menentukan tempat Apigee harus mencari parameter redirect_uri dalam permintaan.

Tentang URI pengalihan

URI pengalihan digunakan dengan jenis pemberian kode otorisasi dan implisit. URI pengalihan memberi tahu server otorisasi (Apigee) ke mana harus mengirim kode otorisasi (untuk jenis pemberian kode otorisasi) atau token akses (untuk jenis pemberian implisit). Penting untuk memahami kapan parameter ini diperlukan, kapan bersifat opsional, dan cara penggunaannya:

• (wajib) Jika URL Panggilan Balik terdaftar 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 Apigee dan menentukan URL Panggilan Balik, lihat Mendaftarkan aplikasi dan mengelola kunci API.

  Catatan: Untuk memastikan Apigee memeriksa kecocokan persis antara "URL Panggilan Balik" dan "redirect_uri" (bukan kecocokan ke depan), tetapkan properti berikut di organisasi Anda: features.isStrictOAuthUriValidation = true. Defaultnya adalah false (kecocokan ke depan).

  Hubungi Customer Care Google Cloud untuk mengaktifkan properti.

• (opsional) Jika URL Callback terdaftar, dan redirect_uri tidak ada dalam permintaan, Apigee akan mengalihkan ke URL Callback yang terdaftar.
• (wajib) Jika URL Panggilan Balik tidak terdaftar, maka redirect_uri wajib diisi. Perhatikan bahwa dalam kasus ini, Apigee akan menerima URL APA PUN. Kasus ini dapat menimbulkan masalah keamanan, dan oleh karena itu hanya boleh digunakan dengan aplikasi klien tepercaya. Jika aplikasi klien tidak tepercaya, 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. Untuk mewajibkan RedirectUri di header HTTP, misalnya, tetapkan nilai ini ke request.header.redirect_uri. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.redirect_uri (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang dapat diakses dalam kebijakan saat runtime
Digunakan dengan jenis pemberian	authorization_code implisit Juga digunakan dengan operasi GenerateAuthorizationCode.

Elemen <RefreshToken>

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

Saat meminta token akses menggunakan token refresh, Anda harus memberikan token refresh dalam permintaan. Elemen ini memungkinkan Anda menentukan tempat Apigee harus mencari token refresh. Misalnya, parameter ini dapat dikirim sebagai parameter kueri, header HTTP, atau parameter formulir (default).

Variabel request.queryparam.refreshtoken menunjukkan bahwa refresh token harus ada sebagai parameter kueri, misalnya, ?refresh_token=login.myapp.com. Untuk mewajibkan RefreshToken di header HTTP, misalnya, tetapkan nilai ini ke request.header.refresh_token. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.refresh_token (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang dapat diakses dalam kebijakan saat runtime
Digunakan dengan jenis pemberian	refresh_token

Elemen <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Menerapkan waktu habis masa berlaku token refresh dalam milidetik. Nilai waktu habis masa berlaku adalah nilai yang dihasilkan sistem ditambah nilai <RefreshTokenExpiresIn>. Jika <RefreshTokenExpiresIn> tidak ditentukan, sistem akan menerapkan nilai default.

Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default yang dikodekan secara permanen atau dengan merujuk variabel alur. Misalnya, Anda dapat menyimpan nilai habis masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Misalnya, kvm.oauth.expires_in.

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

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

Default	2592000000 md (30 hari) (berlaku mulai 31 Mei 2023)
Kehadiran	Opsional
Jenis	Bilangan bulat
Nilai yang valid	Bilangan bulat positif bukan nol. Menentukan waktu habis masa berlaku dalam milidetik.
Digunakan dengan jenis pemberian	authorization_code sandi refresh_token

Elemen <ResponseType>

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

Elemen ini memberi tahu Apigee jenis pemberian yang diminta aplikasi klien. Parameter ini hanya digunakan dengan alur jenis pemberian implisit dan kode otorisasi.

Secara default, Apigee mencari nilai jenis respons dalam parameter kueri response_type. Jika Anda ingin mengganti perilaku default ini, gunakan elemen <ResponseType> untuk mengonfigurasi variabel alur yang berisi nilai jenis respons. Misalnya, jika Anda menetapkan elemen ini ke request.header.response_type, Apigee akan mencari jenis respons yang akan diteruskan di header permintaan. Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.response_type (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional. Gunakan elemen ini jika Anda ingin mengganti perilaku default.
Jenis	String
Nilai yang valid	code (untuk jenis pemberian kode otorisasi) atau token (untuk jenis pemberian implisit)
Digunakan dengan jenis pemberian	implisit Juga digunakan dengan operasi GenerateAuthorizationCode.

Elemen <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Jika disetel ke true, token refresh yang ada akan digunakan kembali hingga masa berlakunya berakhir. Jika false, token refresh baru dikeluarkan oleh Apigee saat token refresh yang valid diberikan.

Default	false
Kehadiran	opsional
Jenis	boolean
Nilai yang valid	true atau false
Digunakan dengan jenis pemberian	refresh_token

Elemen <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

Kebijakan OAuthV2, dengan operasi GenerateAccessToken, dapat menampilkan respons yang tidak sesuai dengan spesifikasi OAuth 2.0 IETF terkait, termasuk RFC 6749 dan RFC 6750. Jika Anda menyertakan elemen RFCCompliantRequestResponse dalam kebijakan, dengan nilai true, kebijakan OAuthV2 akan menampilkan respons yang sesuai dengan RFC.

Tabel berikut menunjukkan perbedaan dalam beberapa nilai yang ditampilkan oleh kebijakan OAuthV2, bergantung pada apakah elemen RFCCompliantRequestResponse adalah true atau false.

Elemen	Nilai salah (false) atau tidak ada	Nilai benar (true)
Header HTTP Cache-Control	Tidak ada yang diberikan	Respons error dan non-error akan menyertakan kolom header respons HTTP Cache-Control untuk mematuhi RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1), dengan nilai no-store dalam respons apa pun yang berisi token, kredensial, atau informasi sensitif lainnya, serta kolom header respons Pragma dengan nilai no-cache.
Properti "token_type" dalam respons token yang valid	Nilai token_type yang tidak patuh. { ... "token_type": "BearerToken", ... }	Nilai token_type yang sesuai. { ... "token_type": "Bearer", ... }
Properti "expires_in" dan "refresh_token_expires_in" dalam respons token yang valid	Nilai numerik dalam tanda kutip. Contoh: { ... "expires_in": "3600", "refresh_token_expires_in": "345600", ... }	Nilai diserialisasi sebagai angka, bukan string. Contoh: { ... "expires_in": 3600, "refresh_token_expires_in": 345600, ... }
respons error untuk token refresh yang sudah tidak berlaku saat grant_type = refresh_token	Respons error tidak sesuai dengan RFC 6749. Contoh: { "ErrorCode": "InvalidRequest", "Error": "Refresh Token expired" }	Payload respons error akan menyertakan elemen "error" dan "error_description". Contoh: { "error": "invalid_grant", "error_description": "refresh token expired" }

Catatan: Respons dari Apigee mencakup beberapa properti yang tidak disebutkan secara eksplisit dalam RFC 6749. Spesifikasi ini memungkinkan properti tambahan. Untuk menyesuaikan respons agar hanya berisi properti yang Anda butuhkan, gunakan set elemen GenerateResponseElement yang ditetapkan ke false, lalu gunakan kebijakan AssignMessage atau JavaScript untuk menghasilkan payload respons Anda sendiri.

Default	false: Secara default, kebijakan akan menunjukkan perilaku tertentu yang tidak sesuai dengan RFC seperti yang dijelaskan di atas.
Kehadiran	Opsional
Jenis	Boolean
Nilai yang valid	true atau false
Digunakan dengan jenis pemberian	Semua

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Menyediakan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token akses berformat JWT dengan algoritma HMAC. Gunakan hanya jika algoritma adalah salah satu dari HS256, HS384, atau HS512. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur. Untuk mengetahui informasi selengkapnya, lihat Menggunakan operasi token OAuth JWT.

Apigee menerapkan kekuatan kunci minimum untuk algoritma HS256/HS384/HS512. Panjang kunci minimum untuk HS256 adalah 32 byte, untuk HS384 adalah 48 byte, dan untuk HS512 adalah 64 byte. Menggunakan kunci dengan kekuatan yang lebih rendah akan menyebabkan error runtime.

Catatan: Untuk melindungi rahasia, sebaiknya simpan kunci di set properti yang tercakup dalam lingkungan atau peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Mengakses nilai set properti dan Menggunakan peta nilai kunci.

Default	T/A
Kehadiran	Diperlukan untuk algoritma HMAC.
Jenis	String
Nilai yang valid	Variabel alur

Elemen <Scope>

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

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

Jika elemen ini muncul dalam kebijakan "VerifyAccessToken", elemen ini digunakan untuk menentukan cakupan mana yang harus diterapkan oleh kebijakan. Dalam jenis kebijakan ini, nilai harus berupa nama cakupan "hard coded" -- Anda tidak dapat menggunakan variabel. Contoh:

<Scope>A B</Scope>

Lihat juga Bekerja dengan cakupan OAuth2 dan Mendapatkan token OAuth 2.0.

Default	Tidak ada cakupan
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Jika digunakan dengan kebijakan Generate*, variabel alur. Jika digunakan dengan VerifyAccessToken, daftar nama cakupan (string) yang dipisahkan spasi.
Digunakan dengan jenis pemberian	authorization_code implisit sandi client_credentials Juga dapat digunakan dengan operasi GenerateAuthorizationCode dan VerifyAccessToken.

Elemen <State>

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

Jika aplikasi klien harus mengirim informasi status ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Apigee harus mencari nilai status. Misalnya, token 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, misalnya, ?state=HjoiuKJH32. Untuk mewajibkan status di header HTTP, misalnya, tetapkan nilai ini ke request.header.state. Lihat juga Lihat juga Mendapatkan token OAuth 2.0.

Default	Tanpa status
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Variabel alur apa pun yang dapat diakses oleh kebijakan saat runtime
Digunakan dengan jenis pemberian	Semua Dapat juga digunakan dengan operasi GenerateAuthorizationCode

Elemen <StoreToken>

 <StoreToken>true</StoreToken>

Tetapkan elemen ini ke true jika elemen <ExternalAuthorization> adalah true. Elemen <StoreToken> memberi tahu Apigee untuk menyimpan token akses eksternal. Jika tidak, data tidak akan dipertahankan.

Default	false
Kehadiran	Opsional
Jenis	Boolean
Nilai yang valid	benar atau salah
Digunakan dengan jenis pemberian	authorization_code sandi client_credentials

<SupportedGrantTypes>/<GrantType> element

<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. 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 tidak ada jenis pemberian yang didukung yang ditentukan, maka satu-satunya jenis pemberian yang diizinkan adalah authorization_code dan implicit. Lihat juga elemen <GrantType> (yang merupakan elemen tingkat yang lebih tinggi yang digunakan untuk menentukan tempat Apigee harus mencari parameter grant_type yang diteruskan dalam permintaan klien. Apigee akan memastikan bahwa nilai parameter grant_type cocok dengan salah satu jenis pemberian yang didukung).

Default	_code otorisasi dan implisit
Kehadiran	Wajib
Jenis	String
Nilai yang valid	client_credentials authorization_code sandi implisit

Elemen <Tokens>/<Token>

Digunakan dengan operasi ValidateToken dan InvalidateToken. Lihat juga Menyetujui dan mencabut token akses. Elemen <Token> mengidentifikasi variabel alur yang menentukan sumber token yang akan dibatalkan. Jika developer diharapkan mengirimkan token akses sebagai parameter kueri bernama access_token, misalnya, 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 tersedia untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel tempat Apigee dapat menemukan nilai ini. Jika elemen ini tidak ditentukan, kebijakan mengharapkan untuk menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan memunculkan 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 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 dengan nilai kredensial ini; Apigee hanya memverifikasi bahwa nilai tersebut ada. Developer API yang akan mengambil permintaan nilai dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Mendapatkan token OAuth 2.0.

Default	request.formparam.username (x-www-form-urlencoded dan ditentukan dalam isi permintaan)
Kehadiran	Opsional
Jenis	String
Nilai yang valid	Setelan variabel apa pun.
Digunakan dengan jenis pemberian	sandi

Memverifikasi token akses

Setelah endpoint token disiapkan untuk proxy API, kebijakan OAuthV2 yang sesuai yang menentukan operasi VerifyAccessToken dilampirkan ke Alur yang mengekspos resource yang dilindungi.

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

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

Kebijakan dilampirkan ke resource API yang akan dilindungi. Untuk memastikan bahwa semua permintaan ke API diverifikasi, lampirkan kebijakan 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 di token akses. Misalnya, kebijakan berikut akan memeriksa token akses untuk memastikan bahwa token tersebut berisi setidaknya salah satu cakupan yang tercantum. Jika READ atau WRITE ada, 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 disajikan oleh aplikasi di header HTTP Otorisasi, sesuai dengan spesifikasi OAuth 2.0. Gunakan setelan ini jika token akses diharapkan ditampilkan di lokasi non-standar, seperti parameter kueri, atau header HTTP dengan nama selain Authorization.

Lihat juga Memverifikasi token akses dan Mendapatkan token OAuth 2.0.

Menentukan lokasi variabel permintaan

Untuk setiap jenis pemberian, kebijakan membuat asumsi tentang lokasi atau informasi yang diperlukan dalam pesan permintaan. Asumsi ini didasarkan pada spesifikasi OAuth 2.0. Jika aplikasi Anda perlu 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, ID klien, URI pengalihan, dan cakupan. 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 perlu untuk mendukung dasar aplikasi klien Anda, Anda dapat menggabungkan 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 alur

Variabel alur yang ditentukan dalam tabel ini diisi saat kebijakan OAuth masing-masing dijalankan, sehingga tersedia untuk kebijakan atau aplikasi lain yang dijalankan dalam alur proxy API.

Operasi VerifyAccessToken

Saat operasi VerifyAccessToken dijalankan, sejumlah besar variabel alur diisi dalam konteks eksekusi proxy. Variabel ini memberi Anda properti yang terkait dengan token akses, aplikasi developer, dan developer. Anda dapat menggunakan kebijakan AssignMessage 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.

Catatan: Variabel produk API akan diisi secara otomatis jika produk API dikonfigurasi dengan lingkungan, proxy, dan resource API yang valid (berasal dari proxy.pathsuffix). Variabel flow.resource.name tidak perlu ditetapkan secara eksplisit.

Jika produk API tidak dikonfigurasi dengan lingkungan dan proxy API yang valid, maka flow.resource.name harus ditetapkan secara eksplisit untuk mengisi variabel produk API dalam alur. Untuk mengetahui detail konfigurasi produk, lihat Mengelola produk API.

Variabel khusus token

Variabel	Deskripsi
organization_name	Nama organisasi tempat proxy dieksekusi.
developer.id	ID developer atau AppGroup yang terkait dengan aplikasi klien terdaftar.
developer.app.name	Nama developer atau aplikasi AppGroup yang terkait dengan aplikasi klien terdaftar.
client_id	ID klien aplikasi klien terdaftar.
grant_type	Jenis pemberian yang terkait dengan permintaan. Tidak didukung untuk operasi VerifyJWTAccessToken.
token_type	Jenis token yang terkait dengan permintaan.
access_token	Token akses yang sedang diverifikasi.
accesstoken.{custom_attribute}	Atribut kustom bernama di token akses.
issued_at	Tanggal penerbitan token akses yang dinyatakan dalam waktu epoch Unix dalam milidetik.
expires_in	Waktu habis masa berlaku token akses. Dinyatakan dalam detik. Meskipun elemen ExpiresIn menetapkan masa berlaku dalam milidetik, dalam respons token dan variabel alur, nilai dinyatakan dalam detik.
status	Status token akses (misalnya, disetujui atau dicabut).
scope	Cakupan (jika ada) yang terkait dengan token akses.
apiproduct.<custom_attribute_name>	Atribut kustom bernama dari produk API yang terkait dengan aplikasi klien terdaftar.
apiproduct.name	Nama produk API yang terkait dengan aplikasi klien terdaftar.
revoke_reason	(Khusus Apigee hybrid) Menunjukkan alasan pencabutan token akses. Tidak didukung untuk operasi VerifyJWTAccessToken. Nilai dapat berupa REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, atau TOKEN_REVOKED.

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 kustom bernama dari aplikasi klien terdaftar.

Variabel khusus AppGroup

Variabel alur berikut berisi informasi tentang AppGroup untuk token dan diisi oleh kebijakan. Atribut AppGroup ini hanya diisi jika verifyapikey.{policy_name}.app.appType adalah "AppGroup".

Catatan: Jika Anda bermigrasi dari Apigee Edge, variabel alur perusahaan akan otomatis tersedia di atribut AppGroup yang sesuai setelah migrasi. Tidak ada perubahan yang diperlukan pada paket selama migrasi.

Variabel	Deskripsi
appgroup.displayName	Nama tampilan AppGroup.
appgroup.name	Nama AppGroup.
appgroup.id	ID AppGroup. Catatan: ID ini dibuat secara internal oleh Apigee dan tidak dijamin akan tetap sama dari waktu ke waktu. Jangan gunakan variabel appgroup.id untuk tujuan berikut: ID Kuota Kunci KVM ID yang dikirim ke target untuk digunakan dalam logika bisnis backend
appOwnerStatus	Status pemilik aplikasi: 'active', 'inactive', atau 'login_lock'.
created_at	Stempel tanggal/waktu saat AppGroup dibuat.
created_by	Alamat email developer yang membuat AppGroup.
last_modified_at	Stempel tanggal/waktu saat AppGroup terakhir diubah.
last_modified_by	Alamat email developer yang terakhir mengubah AppGroup.
{appgroup_custom_attributes}	Atribut AppGroup khusus apa pun. Tentukan nama atribut kustom.

Variabel khusus developer

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	Catatan: Mengakses variabel ini akan menyebabkan latensi tinggi jika jumlah aplikasi lebih dari 10.
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes}	Atribut kustom bernama milik developer.

Operasi GenerateAuthorizationCode

Variabel ini ditetapkan saat operasi GenerateAuthorizationCode berhasil dieksekusi:

Awalan: oauthv2authcode.{policy_name}.{variable_name}

Contoh: oauthv2authcode.GenerateCodePolicy.code

Variabel	Deskripsi
code	Kode otorisasi yang dibuat saat kebijakan dijalankan.
redirect_uri	URI pengalihan yang terkait dengan aplikasi klien terdaftar.
scope	Cakupan OAuth opsional yang diteruskan dalam permintaan klien.
client_id	ID klien yang diteruskan dalam permintaan klien.

Operasi GenerateAccessToken dan RefreshAccessToken

Variabel ini ditetapkan saat operasi GenerateAccessToken dan RefreshAccessToken berhasil dieksekusi. Perhatikan 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	ID klien aplikasi developer yang terkait dengan token ini.
expires_in	Nilai masa berlaku untuk token. Lihat elemen <ExpiresIn> untuk mengetahui detailnya. Perhatikan bahwa dalam respons, expires_in dinyatakan dalam detik.
scope	Daftar cakupan yang tersedia yang dikonfigurasi untuk token. Lihat Bekerja dengan cakupan OAuth2.
status	approved atau revoked.
token_type	Disetel ke BearerToken.
developer.email	Alamat email developer terdaftar yang memiliki aplikasi developer yang terkait dengan token.
organization_name	Org tempat proxy dijalankan.
api_product_list	Daftar produk yang terkait dengan aplikasi developer yang sesuai dengan token.
refresh_count
refresh_token	Token refresh yang dibuat. Perhatikan bahwa token refresh tidak dibuat untuk jenis pemberian kredensial klien.
refresh_token_expires_in	Masa berlaku token refresh, dalam hitungan detik.
refresh_token_issued_at	Nilai waktu ini adalah representasi string dari jumlah stempel waktu 32-bit yang sesuai. Misalnya, 'Wed, 21 Aug 2013 19:16:47 UTC' sesuai dengan nilai stempel waktu 1377112607413.
refresh_token_status	approved atau revoked.

GenerateAccessTokenImplicitGrant

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

Awalan: oauthv2accesstoken.{policy_name}.{variable_name}

Contoh: oauthv2accesstoken.RefreshTokenPolicy.access_token

Variabel	Deskripsi
oauthv2accesstoken.access_token	Token akses yang dibuat saat kebijakan dijalankan.
oauthv2accesstoken.{policy_name}.expires_in	Nilai masa berlaku untuk token, dalam detik. Lihat elemen <ExpiresIn> untuk mengetahui detailnya.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code	HTTP status	Cause	Thrown by operations
steps.oauth.v2.access_token_expired	401	The access token is expired.	VerifyAccessToken InvalidateToken
steps.oauth.v2.access_token_not_approved	401	The access token was revoked.	VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist	401	The requested API product does not exist in any of the API products associated with the access token.	VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken	500	The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved.	GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode	500	The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved.	GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId	500	The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken	500	The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved.	RefreshAccessToken
steps.oauth.v2.FailedToResolveToken	500	The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.	ValidateToken InvalidateToken
steps.oauth.v2.InsufficientScope	403	The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes.	VerifyAccessToken
steps.oauth.v2.invalid_client	401	This error name is returned when the <GenerateResponse> property of the policy is set to true and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header. Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidRequest	400	This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.InvalidAccessToken	401	The authorization header does not have the word Bearer, which is required. For example: Authorization: Bearer your_access_token	VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	The currently executing API proxy or operation is not in the Product associated with the access token. Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Managing API products for details. See also Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for more guidance on causes for this error.	VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier	500	This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header. Note: It is recommended that you change existing fault rule conditions to catch both the invalid_client and InvalidClientIdentifier names.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidParameter	500	The policy must specify either an access token or an authorization code, but not both.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType	500	The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown.	ValidateToken InvalidateToken
steps.oauth.v2.MissingParameter	500	The response type is token, but no grant types are specified.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType	500	The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element). Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken

JWT token-specific runtime errors

Runtime error codes and descriptions for JWT auth token flows depend on the OAuth2 flow context:

• If the flow context is token generation or refresh, see Error codes for JWT token generation and refresh flows below.
• For the token verification flow, see Error codes for token verification flows below.

Error codes for JWT token generation and refresh flows

For OAuth2 flows that generate or refresh JWT tokens, error responses adhere to the error responses specified in RFC6749. For details, see Section 5.2 Error Response.

Error codes for the token verification flow

The error codes listed in the following table apply to VerifyAccessToken operation only.

Fault code	HTTP status	Cause	Thrown by operations
oauth.v2.JWTSigningFailed	401	The policy was unable to sign the JWT.	GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm	401	This occurs when the algorithm is not present in the JWT access token or when the value is not supported.	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.InsufficientKeyLength	401	In Generation of JWT, for a key less than the minimum size for the HS384 or HS512 algorithms	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.JWTAlgorithmMismatch	401	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.	VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed	401	The policy was unable to decode the JWT. The JWT is possibly corrupted.	VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT	401	Occurs when the required claims are not present in the Jwt Access token	VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature	401	This occurs when the signature of JWT access token could not be verified or when the signature is invalid.	VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader	401	Occurs when the JWT's type is not at+Jwt	VerifyJWTAccessToken

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
InvalidValueForExpiresIn	For the <ExpiresIn> element, valid values are positive integers.
InvalidValueForRefreshTokenExpiresIn	For the <RefreshTokenExpiresIn> element, valid values are positive integers.
InvalidGrantType	An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation	Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation	Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation	Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired	You must specify an operation in this policy using the <Operation> element. Note: If the <Operation> element is missing, the UI throws a schema validation error.
InvalidOperation	You must specify a valid operation in this policy using the <Operation> element. Note: If the <Operation> element is invalid, the UI throws a schema validation error.
TokenValueRequired	You must specify a token <Token> value in the <Tokens> element.

JWT token-specific deployment errors

These deployment errors are specific to policies that use JWT token operations.

Error name	Cause
InvalidValueForAlgorithm	The algorithm specified in the <Algorithm> element is not among the list of available algorithms or is not present.
MissingKeyConfiguration	The required <SecretKey>, <PrivateKey>, or <PublicKey> elements are missing, depending on which algorithm is used.
EmptyValueElementForKeyConfiguration	The required child element <Value> is not defined in the <PrivateKey>, <PublicKey>, or <SecretKey> elements
InvalidKeyConfiguration	The <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
EmptyRefAttributeForKeyconfiguration	The ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements is empty.
InvalidVariableNameForKey	The flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements does not contain the private prefix.

Fault variables

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

Note: You can use these variables to create Fault Rule conditions. These variables are populated when an error occurs if <GenerateResponse> is set to false. If <GenerateResponse> is true, the policy returns a response to the client immediately if an error occurs -- the error flow is skipped and these variables are not populated. For more information, see What you need to know about policy errors.

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 = "InvalidRequest"
oauthV2.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.fault.name = InvalidRequest Note: For the VerifyAccessToken operation, the fault name includes this suffix: keymanagement.service For example: keymanagement.service.invalid_access_token
oauthV2.policy_name.fault.cause	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

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

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

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

Token di Penyimpanan di-Hash

Jika Anda menggunakan Apigee hybrid atau Apigee, token akses dan token refresh OAuthV2 di-hash secara default saat disimpan dalam database Cassandra runtime. Hashing mencegah token digunakan jika database disusupi.

Menangani konfigurasi OAuth default

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

Menghapus token akses

Secara default, token OAuth2 dihapus dari sistem Apigee 3 hari (259200 detik) setelah token akses dan token refresh (jika ada) telah habis masa berlakunya.

Topik terkait

• Pengantar OAuth 2.0