Kebijakan OAuthV2

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

Apa

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

Tips: Jika Anda ingin mempelajari lebih lanjut OAuth di Apigee Edge, lihat halaman beranda OAuth. Di sini tersedia link ke referensi, contoh, video, dan lainnya. Lihat contoh OAuth lanjutan di GitHub untuk melihat demonstrasi yang baik tentang cara kebijakan ini digunakan dalam aplikasi yang berfungsi.

Contoh

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

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

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

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

Lihat juga "Mengenkode kredensial autentikasi dasar".

Referensi elemen

Referensi kebijakan menjelaskan elemen dan atribut kebijakan OAuthV2.

Contoh kebijakan yang ditampilkan di bawah adalah salah satu dari banyak kemungkinan konfigurasi. Contoh ini menunjukkan kebijakan OAuthV2 yang dikonfigurasi untuk operasi GenerateAccessToken. 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:

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

Elemen <AccessToken>

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

Secara default, VerifyAccessToken mengharapkan token akses dikirim di header Authorization. Anda dapat mengubah default tersebut menggunakan elemen ini. Misalnya, request.queryparam.access_token menunjukkan bahwa token akses harus ada sebagai parameter kueri bernama access_token.

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

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

Elemen <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Secara default, VerifyAccessToken mengharapkan token akses dikirim di header Otorisasi sebagai token Bearer. Contoh:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Saat ini, hanya Bearer yang merupakan awalan yang didukung.

Elemen <AppEndUser>

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

Dalam kasus saat ID pengguna akhir aplikasi harus dikirim ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Edge 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=ntesla@theramin.com. Untuk mewajibkan AppEndUser di header HTTP, misalnya, tetapkan nilai ini ke request.header.app_enduser.

Dengan menyediakan 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.

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

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. Misalnya, 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 Edge 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 secara eksplisit atribut kustom 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.

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 Meminta token akses dan kode otorisasi.

Elemen <Code>

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

Dalam alur jenis pemberian otorisasi, klien harus mengirimkan kode otorisasi ke server otorisasi (Apigee Edge). Dengan elemen ini, Anda dapat menentukan tempat Edge harus mencari kode otorisasi. Misalnya, 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, misalnya, ?auth_code=AfGlvs9. Untuk mewajibkan kode otorisasi di header HTTP, misalnya, tetapkan nilai ini ke request.header.auth_code. Lihat juga Meminta token akses dan kode otorisasi.

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> disetel ke -1, token atau kode akan berakhir sesuai dengan masa berlaku maksimum token akses OAuth. 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 mereferensikan variabel alur. Misalnya, Anda dapat menyimpan nilai masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Contoh, kvm.oauth.expires_in.

Dengan Apigee Edge untuk Public Cloud, Edge menyimpan entitas berikut dalam cache selama minimal 180 detik setelah entitas diakses.

• Token akses OAuth. Artinya, token yang dicabut masih dapat berhasil hingga tiga menit, hingga batas cache-nya berakhir.
• Entitas Key Management Service (KMS) (Aplikasi, Developer, Produk API).
• Atribut kustom pada token OAuth dan entitas KMS.

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

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

Edge tidak mendukung cara untuk memaksa 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 sudah habis masa berlakunya akan dihapus dari sistem Apigee Edge secara otomatis 3 hari setelah masa berlakunya habis. Lihat juga Menghapus token akses

Private Cloud: Untuk penginstalan Edge untuk Private Cloud, nilai default ditetapkan oleh properti conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Untuk menyetel properti ini:

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

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

2. Tetapkan properti sesuai keinginan:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

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

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

4. Mulai ulang Pemroses Pesan.

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

Elemen <ExternalAccessToken>

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

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

Variabel request.queryparam.external_access_token menunjukkan bahwa token akses eksternal harus ada sebagai parameter kueri, seperti, 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, Edge akan memvalidasi client_id dan client_secret secara normal terhadap penyimpanan otorisasi Apigee Edge. Gunakan elemen ini jika Anda ingin menggunakan token OAuth pihak ketiga. Untuk mengetahui detail tentang penggunaan elemen ini, lihat Menggunakan Token OAuth Pihak Ketiga.

Elemen <ExternalAuthorizationCode>

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

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

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

Variabel request.queryparam.external_refresh_token menunjukkan bahwa token refresh eksternal harus ada sebagai parameter kueri, 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, 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" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Jika false, tidak ada respons yang dikirim. Sebagai gantinya, 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.

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.

<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, misalnya, ?grant_type=password. Untuk mewajibkan jenis pemberian dalam header HTTP, misalnya, tetapkan nilai ini ke request.header.grant_type. Lihat juga Meminta token akses dan kode otorisasi.

Elemen <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Operasi OAuth 2.0 yang dijalankan oleh kebijakan.

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 Edge 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 alur 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; Edge hanya memverifikasi bahwa nilai tersebut ada. Developer API yang akan mengambil nilai permintaan dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Meminta token akses dan kode otorisasi.

Elemen <RedirectUri>

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

Menentukan tempat Edge 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 (Edge) 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 Edge dan menentukan URL Panggilan Balik, lihat Mendaftarkan aplikasi dan mengelola kunci API.

• (opsional) Jika URL Panggilan Balik terdaftar, dan redirect_uri tidak ada dalam permintaan, Edge akan mengalihkan ke URL Panggilan Balik yang terdaftar.
• (wajib) Jika URL Callback tidak terdaftar, maka redirect_uri diperlukan. Perhatikan bahwa dalam kasus ini, Edge 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 Panggilan Balik.

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 Meminta token akses dan kode otorisasi.

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 Edge harus mencari token refresh. Misalnya, parameter ini dapat dikirim sebagai parameter kueri, header HTTP, atau parameter formulir (default).

Variabel request.queryparam.refreshtoken menunjukkan bahwa token refresh harus ada sebagai parameter kueri, seperti, misalnya, ?refresh_token=login.myapp.com. Untuk mewajibkan RefreshToken di header HTTP, misalnya, tetapkan nilai ini ke request.header.refresh_token. Lihat juga Meminta token akses dan kode otorisasi.

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> ditetapkan ke -1, masa berlaku token refresh berakhir sesuai dengan masa berlaku maksimum token refresh OAuth. Jika <RefreshTokenExpiresIn> tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi di tingkat sistem. Hubungi Dukungan Apigee Edge untuk mengetahui informasi selengkapnya tentang setelan sistem default.

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

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

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

Private Cloud: Untuk penginstalan Edge untuk Private Cloud, nilai default ditetapkan oleh properti conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Untuk menyetel properti ini:

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

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

2. Tetapkan properti sesuai keinginan:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

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

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

4. Mulai ulang Pemroses Pesan.

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

Elemen <ResponseType>

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

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

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

Elemen <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

Elemen <Scope>

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

Jika elemen ini ada di salah satu kebijakan GenerateAccessToken atau GenerateAuthorizationCode, elemen ini digunakan untuk menentukan cakupan 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", maka elemen ini digunakan untuk menentukan cakupan 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 Meminta token akses dan kode otorisasi.

Elemen <State>

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

Jika aplikasi klien harus mengirim informasi status ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Edge 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, seperti, misalnya, ?state=HjoiuKJH32. Untuk mewajibkan status di header HTTP, misalnya, tetapkan nilai ini ke request.header.state. Lihat juga Meminta token akses dan kode otorisasi.

Elemen <StoreToken>

 <StoreToken>true</StoreToken>

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

<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 Edge. Endpoint dapat mendukung beberapa jenis pemberian (yaitu, satu endpoint dapat dikonfigurasi untuk mendistribusikan token akses untuk beberapa jenis pemberian). Untuk mengetahui informasi selengkapnya tentang endpoint, lihat Memahami endpoint OAuth. Jenis pemberian diteruskan dalam permintaan token di parameter grant_type.

Jika 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 Edge harus mencari parameter grant_type yang diteruskan dalam permintaan klien. Edge akan memastikan bahwa nilai parameter grant_type cocok dengan salah satu jenis pemberian yang didukung).

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 Edge 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 alur 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; Edge hanya memverifikasi bahwa nilai tersebut ada. Developer API yang akan mengambil nilai permintaan dan mengirimkannya ke penyedia identitas sebelum kebijakan pembuatan token dijalankan.

Lihat juga Meminta token akses dan kode otorisasi.

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.

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

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

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 mencampur dan mencocokkan 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

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

Variabel khusus token

Variabel spesifik per aplikasi

Variabel ini terkait dengan Aplikasi Developer yang terkait dengan token.

Variabel khusus developer

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

Variabel khusus perusahaan

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

operasi GenerateAuthorizationCode

Variabel ini ditetapkan saat operasi GenerateAuthorizationCode berhasil dieksekusi:

Awalan: oauthv2authcode.{policy_name}.{variable_name}

Contoh: oauthv2authcode.GenerateCodePolicy.code

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

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

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.

Deployment errors

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

Fault variables

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

Example error response

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

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>

Skema kebijakan

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

Menangani konfigurasi OAuth default

Setiap organisasi (bahkan organisasi uji coba gratis) di Apigee Edge 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 Edge. Untuk mengetahui detailnya, lihat Memahami endpoint OAuth.

Menghapus token akses

Secara default, token OAuth2 dihapus dari sistem Apigee Edge 3 hari (259200 detik) setelah token akses dan token refresh (jika ada) telah habis masa berlakunya. Dalam beberapa kasus, Anda mungkin ingin mengubah setelan default ini. Misalnya, Anda dapat mempersingkat waktu penghapusan untuk menghemat ruang disk jika sejumlah besar token sedang dibuat.

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

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

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

Memperbarui setelan penghapusan untuk Edge Private Cloud 4.15.07

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

Perilaku yang tidak sesuai dengan RFC

Kebijakan OAuthV2 menampilkan respons token yang berisi properti non-RFC yang sesuai. Tabel berikut menunjukkan properti yang tidak mematuhi kebijakan yang ditampilkan oleh kebijakan OAuthV2 dan properti yang sesuai.

Selain itu, respons error untuk token refresh yang sudah tidak berlaku jika grant_type = refresh_token adalah:

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

Namun, respons yang sesuai dengan RFC adalah:

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

Topik terkait

• Pengantar OAuth 2.0