Kebijakan OAuthV2

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

Apa

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

Tips: Jika Anda ingin mempelajari OAuth di Apigee Edge lebih lanjut, lihat halaman beranda OAuth. Halaman ini menyediakan link ke resource, sampel, video, dan lainnya. Lihat contoh OAuth lanjutan di GitHub untuk mengetahui 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. Elemen ini mencakup elemen wajib dan opsional. Lihat deskripsi elemen di bagian ini untuk 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 sama untuk semua elemen induk kebijakan:

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan 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 yang 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 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 harus mencari ID pengguna akhir. Misalnya, ID tersebut 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. Misalnya, untuk mewajibkan AppEndUser di header HTTP, tetapkan nilai ini ke request.header.app_enduser.

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

<Atribut/Atribut>

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

Elemen ini memungkinkan Anda menentukan nilai dalam variabel flow 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 tersebut adalah default.

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

Menampilkan atau menyembunyikan atribut khusus dalam respons

Perlu diingat bahwa jika Anda menetapkan elemen GenerateResponse kebijakan ini ke true, representasi lengkap token JSON akan ditampilkan dalam respons, termasuk atribut khusus yang Anda tetapkan. Dalam beberapa kasus, Anda mungkin ingin menyembunyikan beberapa atau semua atribut khusus 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. Misalnya, 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 yang baru nantinya dibuat menggunakan token refresh, atribut khusus yang asli dari token akses tersebut akan muncul dalam respons token refresh. Hal ini karena Edge tidak mengingat bahwa atribut display awalnya ditetapkan ke false dalam kebijakan buat token akses--atribut khusus hanyalah bagian dari metadata token akses.

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

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

• Reset atribut khusus 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 pascapemrosesan untuk mengekstrak secara manual atribut khusus 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 mengirim client ID ke server otorisasi. Elemen ini memungkinkan Anda menentukan di mana Edge harus mencari client ID. Satu-satunya lokasi valid yang dapat Anda tetapkan adalah lokasi default, variabel flow 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 untuk mencari kode otorisasi. Misalnya, ID 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. Misalnya, untuk mewajibkan kode otorisasi di header HTTP, 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 hard code 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 Cloud Publik, Edge menyimpan entity berikut dalam cache selama minimal 180 detik setelah entity diakses.

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

Stanza berikut juga menentukan variabel flow dan nilai default. Perlu diketahui bahwa nilai variabel flow 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 berakhirnya masa berlaku token setelah dibuat. Jika Anda perlu memaksa berakhirnya masa berlaku token (misalnya, berdasarkan kondisi), solusi yang memungkinkan dijelaskan dalam postingan Komunitas Apigee ini.

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

Private Cloud: Untuk Edge untuk penginstalan Private Cloud, nilai defaultnya 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 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 dihasilkan 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 false atau tidak ada, Edge akan memvalidasi client_id dan client_secret secara normal terhadap penyimpanan otorisasi Apigee Edge. Gunakan elemen ini jika Anda ingin bekerja dengan 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 dihasilkan 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. Misalnya, untuk mewajibkan kode autentikasi eksternal di header HTTP, 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 dihasilkan 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. Misalnya, untuk mewajibkan token refresh eksternal di header HTTP, 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 menghasilkan 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, kumpulan variabel flow akan 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 menghasilkan dan menampilkan respons jika atribut ContinueOnError disetel ke benar (true). Jika false (default), tidak ada respons yang dikirim. Sebagai gantinya, kumpulan variabel flow akan 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 spesifikasi OAuth 2.0, jenis pemberian harus disertakan 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. Misalnya, untuk mewajibkan jenis pemberian di header HTTP, 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 bentuk yang bernama username dan password. Jika nilainya 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 di header HTTP, tetapkan nilai ini ke request.header.password.

Kebijakan OAuthV2 tidak melakukan hal lain terhadap nilai kredensial ini; Edge hanya memverifikasi keberadaan nilai kredensial tersebut. Developer API dapat mengambil permintaan nilai 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 di mana 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 autentikasi) atau token akses (untuk jenis pemberian implisit). Penting untuk memahami kapan parameter ini diperlukan, kapan parameter ini bersifat opsional, dan bagaimana parameter digunakan:

• (wajib) Jika URL Callback didaftarkan 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 Callback, lihat Mendaftarkan aplikasi dan mengelola kunci API.

• (opsional) Jika URL Callback terdaftar, dan redirect_uri tidak ada di permintaan, Edge akan mengalihkan ke URL Callback yang terdaftar.
• (wajib) Jika URL Callback tidak terdaftar, redirect_uri diperlukan. Perhatikan bahwa dalam hal ini, Edge akan menerima URL APA PUN. Kasus ini dapat menimbulkan masalah keamanan, sehingga sebaiknya hanya digunakan dengan aplikasi klien tepercaya. Jika aplikasi klien tidak dipercaya, 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 pada 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 menyediakan token refresh dalam permintaan. Elemen ini memungkinkan Anda menentukan tempat Edge harus mencari token refresh. Misalnya, URL 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 di 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 masa berakhir adalah nilai yang dihasilkan oleh sistem ditambah nilai <RefreshTokenExpiresIn>. Jika <RefreshTokenExpiresIn> ditetapkan ke -1, masa berlaku token refresh akan berakhir sesuai dengan akhir masa berlaku token refresh OAuth maksimum. Jika <RefreshTokenExpiresIn> tidak ditentukan, secara default masa berlaku tidak akan ditentukan.

Waktu habis masa berlaku juga dapat ditetapkan saat runtime menggunakan nilai default hard code 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.

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

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

Private Cloud: Untuk Edge untuk penginstalan Private Cloud, nilai defaultnya 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 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. Metode 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 flow 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 <Gunakan KembaliRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

Elemen <Scope>

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

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

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

<Scope>A B</Scope>

Lihat juga Mengelola 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 tempat Edge harus mencari nilai status. Misalnya, URL 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, ?state=HjoiuKJH32. Misalnya, untuk mewajibkan status di header HTTP, 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, perubahan 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 di parameter grant_type.

Jika jenis pemberian yang didukung tidak ditentukan, satu-satunya jenis pemberian yang diizinkan adalah authorization_code dan implicit. Lihat juga elemen <GrantType> (yaitu elemen dengan tingkat lebih tinggi yang digunakan untuk menentukan lokasi 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 flow yang menentukan sumber token yang akan dicabut. Misalnya, jika developer diminta mengirimkan token akses sebagai parameter kueri 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 ini. Jika elemen ini tidak ditentukan, kebijakan akan menemukan nilai (secara default) dalam parameter bentuk yang bernama username dan password. Jika nilainya 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 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 terhadap nilai kredensial ini; Edge hanya memverifikasi keberadaan nilai kredensial tersebut. Developer API dapat mengambil permintaan nilai 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 terkait yang menentukan operasi VerifyAccessToken akan disertakan ke Flow yang mengekspos resource yang dilindungi.

Misalnya, untuk memastikan bahwa semua permintaan ke API telah diotorisasi, kebijakan berikut akan menerapkan verifikasi token akses:

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

Kebijakan ini disertakan ke resource API agar dilindungi. Untuk memastikan semua permintaan ke API telah diverifikasi, lampirkan kebijakan tersebut 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 hibah, kebijakan membuat asumsi tentang lokasi atau informasi yang diperlukan dalam pesan permintaan. Asumsi ini didasarkan pada spesifikasi OAuth 2.0. Jika aplikasi Anda harus 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 cakupannya. 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 diperlukan untuk mendukung basis aplikasi klien, Anda dapat memadupadankan 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 setiap kebijakan OAuth dijalankan, sehingga tersedia untuk kebijakan atau aplikasi lain yang dieksekusi di 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 Tetapkan Pesan 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 terkait dengan token.

Variabel khusus developer

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

Variabel khusus perusahaan

Jika app.appType adalah "Perusahaan", atribut perusahaan akan 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 jika operasi GenerateAccessToken dan RefreshAccessToken berhasil dijalankan. Perlu diperhatikan 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 ketika operasi GenerateAccessTokenImplicit berhasil dijalankan untuk alur jenis pemberian implisit.

Awalan: oauthv2accesstoken.{policy_name}.{variable_name}

Contoh: oauthv2accesstoken.RefreshTokenPolicy.access_token

Referensi error

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

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 kesalahan

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime.

Contoh respons error

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

Jika <GenerateResponse> bernilai 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 kesalahan

<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 disediakan dengan endpoint token OAuth. Endpoint telah dikonfigurasi sebelumnya dengan kebijakan dalam proxy API yang disebut oauth. Anda dapat mulai menggunakan endpoint token segera setelah membuat akun di Apigee Edge. Untuk mengetahui detailnya, baca Memahami endpoint OAuth.

Menghapus token akses

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

Jika menggunakan Edge untuk Private Cloud, Anda dapat mengubah setelan default ini dengan menetapkan properti organisasi seperti yang dijelaskan di bagian ini. (Penghapusan permanen selama 3 hari untuk token yang sudah habis masa berlakunya berlaku pada Edge untuk Private Cloud versi 4.19.01 dan yang lebih baru. Untuk versi sebelumnya, interval penghapusan permanen 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 akan terpengaruh; setelan tidak berlaku untuk token yang dibuat sebelumnya.

Memperbarui setelan penghapusan permanen untuk Edge Private Cloud 4.15.07

Catatan: Hanya token yang dibuat setelah setelan ini diterapkan yang akan 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 menampilkan properti yang tidak mematuhi kebijakan yang ditampilkan oleh kebijakan OAuthV2 dan properti yang mematuhi kebijakan terkait.

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

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