Kebijakan OAuthV2

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

Apa

OAuthV2 adalah kebijakan multi-aspek untuk menjalankan operasi jenis pemberian izin OAuth 2.0. Ini adalah kebijakan utama yang digunakan untuk mengonfigurasi endpoint OAuth 2.0 di Apigee Edge.

Tips: Jika ingin mempelajari OAuth di Apigee Edge lebih lanjut, lihat halaman beranda OAuth. Halaman ini menyediakan 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 dalam header Authorization. Anda dapat mengubah default tersebut menggunakan elemen ini. Misalnya, request.queryparam.access_token menunjukkan bahwa token akses harus ada sebagai parameter kueri 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 dalam header Otorisasi sebagai token Pembawa. Contoh:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Saat ini, Bearer adalah satu-satunya awalan yang didukung.

Elemen <AppEndUser>

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

Jika ID pengguna akhir aplikasi harus dikirim ke server otorisasi, elemen ini memungkinkan Anda menentukan tempat Edge akan mencari ID pengguna akhir. Misalnya, parameter ini 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 dalam 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 menurut ID pengguna akhir. Untuk informasi selengkapnya, lihat Mengaktifkan pengambilan dan pencabutan token akses OAuth 2.0 berdasarkan 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 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 flow akan digunakan. Jika variabel tidak dapat di-resolve, string akan menjadi default.

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

Menampilkan atau menyembunyikan atribut kustom dalam respons

Perlu diingat bahwa jika Anda menetapkan 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 sehingga tidak terlihat oleh aplikasi klien.

Secara default, atribut khusus muncul dalam respons. Jika ingin menyembunyikannya, Anda dapat menetapkan parameter display ke false. Contoh:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Nilai atribut display tidak dipertahankan. Misalkan, Anda membuat token akses dengan atribut khusus yang ingin disembunyikan dalam respons yang dihasilkan. Menetapkan display=false akan mencapai sasaran tersebut. Namun, jika token akses 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 inginkan.

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

• Reset atribut kustom secara eksplisit dalam kebijakan token refresh dan tetapkan tampilannya ke false. Dalam hal ini, Anda mungkin perlu mengambil nilai kustom asli dari token akses asli menggunakan kebijakan GetOAuthV2Info.
• Gunakan kebijakan JavaScript pascapemrosesan untuk mengekstrak atribut kustom apa pun yang tidak ingin Anda lihat dalam respons secara manual.

Lihat juga Menyesuaikan Token dan Kode Otorisasi.

Elemen <ClientId>

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

Dalam beberapa kasus, aplikasi klien harus mengirim ID klien ke server otorisasi. Elemen ini menentukan bahwa Apigee harus mencari client ID 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). Elemen ini memungkinkan Anda menentukan tempat Edge akan mencari kode otorisasi. Misalnya, parameter ini 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 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> ditetapkan ke -1, masa berlaku token atau kode akan berakhir sesuai dengan masa berlaku token akses OAuth maksimum. Jika <ExpiresIn> tidak ditentukan, sistem akan menerapkan nilai default yang dikonfigurasi di tingkat sistem.

Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default yang di-hardcode atau dengan mereferensikan variabel flow. Misalnya, Anda dapat menyimpan nilai masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Contoh, kvm.oauth.expires_in.

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

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

Stanza berikut juga menentukan variabel alur dan nilai default. Perhatikan bahwa nilai variabel aliran 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 token 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 tidak berlaku akan dihapus dari sistem Apigee Edge secara otomatis 3 hari setelah masa berlaku 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 menetapkan properti ini:

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

   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 Message Processor.

   /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. Misalnya, untuk mewajibkan token akses eksternal di header HTTP, tetapkan nilai ini ke request.header.external_access_token. Lihat juga Menggunakan Token OAuth Pihak Ketiga.

Elemen <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Jika elemen ini 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 autentikasi eksternal (kode autentikasi yang tidak dibuat oleh Apigee Edge).

Variabel request.queryparam.external_auth_code menunjukkan bahwa kode autentikasi eksternal harus ada sebagai parameter kueri, misalnya, ?external_auth_code=12345678. Untuk mewajibkan kode autentikasi eksternal dalam 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 dalam 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 akan dikirim. Sebagai gantinya, serangkaian variabel alur diisi dengan nilai yang terkait dengan fungsi kebijakan. Misalnya, variabel flow yang disebut oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code akan diisi dengan kode autentikasi yang baru dibuat. Perhatikan bahwa expires_in dinyatakan dalam detik dalam respons.

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 hibah yang diteruskan dalam permintaan. Sesuai dengan spesifikasi OAuth 2.0, jenis pemberian harus dilengkapi dengan permintaan untuk 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 izin di 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 disediakan untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel tempat Edge dapat menemukan nilai ini. Jika elemen ini tidak ditentukan, kebijakan akan menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan menampilkan error. Anda dapat menggunakan elemen <PassWord> dan <UserName> untuk mereferensikan variabel flow apa pun yang berisi kredensial.

Misalnya, Anda dapat meneruskan sandi dalam permintaan token menggunakan parameter kueri dan menetapkan elemen seperti ini: <PassWord>request.queryparam.password</PassWord>. Untuk mewajibkan sandi dalam header HTTP, tetapkan nilai ini ke request.header.password.

Kebijakan OAuthV2 tidak melakukan tindakan lain dengan nilai kredensial ini; Edge hanya memverifikasi bahwa nilai tersebut ada. Developer API dapat mengambil permintaan nilai dan mengirimnya 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 kode otorisasi dan jenis pemberian implisit. URI pengalihan memberi tahu server otorisasi (Edge) tempat 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 Callback didaftarkan dengan aplikasi developer yang dikaitkan dengan kunci klien permintaan, dan jika redirect_uri ada dalam permintaan, maka keduanya harus sama persis. Jika tidak cocok, error akan ditampilkan. Untuk informasi tentang mendaftarkan aplikasi developer di Edge dan menentukan URL Callback, lihat Mendaftarkan aplikasi dan mengelola kunci API.

• (opsional) Jika URL Callback terdaftar, dan redirect_uri tidak ada pada permintaan, Edge akan mengalihkan ke URL Callback yang terdaftar.
• (wajib) Jika URL Callback tidak terdaftar, redirect_uri diperlukan. Perhatikan bahwa dalam kasus ini, Edge akan menerima URL APA PUN. Kasus ini dapat menimbulkan masalah keamanan, sehingga 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. Misalnya, untuk mewajibkan RedirectUri di header HTTP, 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. Misalnya, untuk mewajibkan RefreshToken dalam header HTTP, 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 akan berakhir sesuai dengan masa berlaku token refresh OAuth maksimum. 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 di-hardcode atau dengan mereferensikan variabel flow. Misalnya, Anda dapat menyimpan nilai masa berlaku token dalam peta nilai kunci, mengambilnya, menetapkannya ke variabel, dan mereferensikannya dalam kebijakan. Misalnya, kvm.oauth.expires_in.

Stanza berikut juga menentukan variabel alur dan nilai default. Perlu diperhatikan bahwa nilai variabel alur lebih diprioritaskan 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 menetapkan properti ini:

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

   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 Message Processor.

   /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. Ini hanya digunakan dengan kode otorisasi dan alur jenis pemberian implisit.

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

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 akan dikeluarkan oleh Apigee Edge saat token refresh yang valid ditampilkan.

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 memberikan token atau kode. Nilai ini biasanya diteruskan ke kebijakan dalam permintaan dari aplikasi klien. Anda dapat mengonfigurasi elemen untuk mengambil variabel alur, sehingga memberi Anda opsi untuk memilih cara cakupan diteruskan dalam permintaan. Dalam contoh berikut, request.queryparam.scope menunjukkan bahwa cakupan harus ada sebagai parameter kueri, seperti, misalnya, ?scope=READ. Untuk mewajibkan cakupan di header HTTP, misalnya, tetapkan nilai ini ke request.header.scope.

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

<Scope>A B</Scope>

Lihat juga Menggunakan cakupan OAuth2 dan Meminta token akses dan kode otorisasi.

Elemen <State>

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

Jika aplikasi klien harus mengirimkan informasi status ke server otorisasi, elemen ini memungkinkan Anda menentukan di mana Edge harus mencari nilai status. Misalnya, parameter ini dapat dikirim sebagai parameter kueri atau di header HTTP. Nilai status biasanya digunakan sebagai tindakan 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> 

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

Elemen <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Menentukan jenis pemberian yang didukung oleh endpoint token OAuth di Apigee Edge. Endpoint dapat mendukung beberapa jenis pemberian (yaitu, satu endpoint dapat dikonfigurasi untuk mendistribusikan token akses untuk beberapa jenis pemberian). Untuk mengetahui informasi selengkapnya tentang endpoint, lihat Memahami endpoint OAuth. Jenis pemberian diteruskan dalam permintaan token dalam parameter grant_type.

Jika tidak ada jenis hibah yang didukung yang ditentukan, satu-satunya jenis hibah yang diizinkan adalah authorization_code dan implicit. Lihat juga elemen <GrantType> (yang merupakan elemen tingkat 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 dicabut. Misalnya, jika developer diharapkan mengirimkan token akses sebagai parameter kueri yang bernama access_token, gunakan request.queryparam.access_token.

Elemen <UserName>

<UserName>request.queryparam.user_name</UserName>

Elemen ini hanya digunakan dengan jenis pemberian sandi. Dengan jenis pemberian sandi, kredensial pengguna (sandi dan nama pengguna) harus disediakan untuk kebijakan OAuthV2. Elemen <PassWord> dan <UserName> digunakan untuk menentukan variabel tempat Edge dapat menemukan nilai-nilai ini. Jika elemen ini tidak ditentukan, kebijakan akan menemukan nilai (secara default) dalam parameter formulir bernama username dan password. Jika nilai tidak ditemukan, kebijakan akan menampilkan 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 dalam header HTTP, tetapkan nilai ini ke request.header.username.

Kebijakan OAuthV2 tidak melakukan tindakan lain dengan nilai kredensial ini; Edge hanya memverifikasi bahwa nilai tersebut ada. Developer API dapat mengambil permintaan nilai dan mengirimnya 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 akan dilampirkan ke Flow yang mengekspos resource yang dilindungi.

Misalnya, untuk memastikan bahwa semua permintaan ke API diotorisasi, 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, seperti 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 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, client ID, 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 basis aplikasi klien, 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 flow

Variabel alur yang ditentukan dalam tabel ini diisi saat kebijakan OAuth masing-masing dieksekusi, 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 MenetapkanMessage 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 khusus aplikasi

Variabel ini terkait dengan Aplikasi Developer yang dikaitkan dengan token.

Variabel khusus developer

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

Variabel khusus perusahaan

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

Operasi GenerateAuthorizationCode

Variabel ini ditetapkan saat operasi GenerateAuthorizationCode berhasil dijalankan:

Awalan: oauthv2authcode.{policy_name}.{variable_name}

Contoh: oauthv2authcode.GenerateCodePolicy.code

Operasi GenerateAccessToken dan RefreshAccessToken

Variabel ini ditetapkan ketika operasi GenerateAccessToken dan RefreshAccessToken berhasil dijalankan. 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 dijalankan untuk alur jenis pemberian izin implisit.

Awalan: oauthv2accesstoken.{policy_name}.{variable_name}

Contoh: oauthv2accesstoken.RefreshTokenPolicy.access_token

Referensi error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Variabel error

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime.

Contoh respons error

Respons ini dikirim kembali ke klien jika elemen <GenerateResponse> bernilai true.

Jika <GenerateResponse> true, kebijakan akan menampilkan error dalam format ini untuk operasi yang menghasilkan token dan kode. Untuk mengetahui daftar lengkapnya, lihat Referensi respons error HTTP OAuth.

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

Jika <GenerateResponse> bernilai true, kebijakan akan menampilkan error dalam format ini untuk operasi verifikasi dan validasi. Untuk mengetahui daftar lengkapnya, lihat referensi respons error HTTP OAuth.

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

Contoh aturan error

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Skema kebijakan

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

Menggunakan konfigurasi OAuth default

Setiap organisasi (bahkan organisasi uji coba gratis) di Apigee Edge dilengkapi dengan endpoint token OAuth. Endpoint sudah dikonfigurasi 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 (259.200 detik) setelah masa berlaku token akses dan token refresh (jika ada) berakhir. Dalam beberapa kasus, Anda mungkin ingin mengubah setelan default ini. Misalnya, Anda dapat mempersingkat waktu pembersihan untuk menghemat ruang disk jika token dalam jumlah besar dihasilkan.

Jika menggunakan Edge for Private Cloud, Anda dapat mengubah setelan 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 permanen 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 tertentu yang tidak sesuai dengan RFC. Tabel berikut menunjukkan properti yang tidak mematuhi kebijakan OAuthV2 dan properti yang mematuhi kebijakan yang sesuai.

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

{"ErrorCode" : "invalid_request", "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