Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Dalam topik ini, kami menunjukkan cara meminta token akses dan kode otorisasi, mengonfigurasi endpoint OAuth 2.0, dan mengonfigurasi kebijakan untuk setiap jenis pemberian izin yang didukung.
Kode contoh
Untuk memudahkan Anda, kebijakan dan endpoint yang dibahas dalam topik ini tersedia di GitHub dalam project oauth-doc-examples di repositori Apigee api-platform-samples. Anda dapat men-deploy kode contoh dan mencoba contoh permintaan yang ditampilkan dalam topik ini. Lihat README project untuk mengetahui detailnya.
Meminta token akses: jenis pemberian kode otorisasi
Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kode otorisasi. Untuk pengantar jenis pemberian OAuth 2.0, lihat Pengantar OAuth 2.0.
Contoh permintaan
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \ -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \ -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'
Parameter yang diperlukan
Secara default, parameter ini harus bernilai x-www-form-urlencoded
dan ditentukan dalam
isi permintaan (seperti yang ditunjukkan pada contoh di atas); namun, Anda dapat mengubah default ini dengan
mengonfigurasi elemen <GrantType>
, <Code>
, dan
<RedirectUri>
dalam kebijakan OAuthV2 yang disertakan ke endpoint
/accesstoken
ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
- grant_type - Harus ditetapkan ke nilai
authorization_code
. - code - Kode otorisasi yang diterima dari endpoint
/authorize
(atau nama apa pun yang Anda pilih). Untuk meminta token akses dalam alur jenis pemberian kode otorisasi, Anda harus mendapatkan kode otorisasi terlebih dahulu. Lihat Meminta kode otorisasi di bawah. Lihat juga Mengimplementasikan jenis pemberian kode otorisasi. - redirect_uri - Anda harus memberikan parameter ini jika parameter
redirect_uri
disertakan dalam permintaan kode otorisasi sebelumnya. Jika parameterredirect_uri
tidak disertakan dalam permintaan kode otorisasi, dan jika Anda tidak memberikan parameter ini, kebijakan ini akan menggunakan nilai URL Callback yang diberikan saat aplikasi developer terdaftar.
Parameter opsional
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
Anda harus meneruskan Client ID dan Rahasia Klien sebagai header Autentikasi Dasar (dienkode Base64) atau sebagai parameter formulir client_id
dan client_secret
. Anda mendapatkan nilai ini dari aplikasi developer yang terdaftar. Lihat juga "Mengenkode kredensial autentikasi dasar".
Contoh endpoint
Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Tindakan ini akan menjalankan kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung jenis pemberian authorization_code.
... <Flow name="generate-access-token"> <Description>Generate a token</Description> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition> </Flow> ...
Kebijakan contoh
Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima
jenis pemberian authorization_code
. Untuk mengetahui informasi tentang elemen konfigurasi opsional
yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<OAuthV2 name="GenerateAccessToken"> <Operation>GenerateAccessToken</Operation> <ExpiresIn>1800000</ExpiresIn> <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn> <SupportedGrantTypes> <GrantType>authorization_code</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan respons JSON yang menyertakan token akses, seperti yang ditunjukkan di bawah ini. Jenis pemberian authorization_code
membuat token akses dan token refresh, sehingga responsnya mungkin terlihat seperti ini:
{ "issued_at": "1420262924658", "scope": "READ", "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b", "refresh_token_issued_at": "1420262924658", "status": "approved", "refresh_token_status": "approved", "api_product_list": "[PremiumWeatherAPI]", "expires_in": "1799", //--in seconds "developer.email": "tesla@weathersample.com", "organization_id": "0", "token_type": "BearerToken", "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm", "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT", "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi", "organization_name": "docs", "refresh_token_expires_in": "86399", //--in seconds "refresh_count": "0" }
Jika <GenerateResponse>
disetel ke salah (false), kebijakan tersebut tidak akan menampilkan
respons. Sebagai gantinya, formulir ini akan mengisi kumpulan variabel flow berikut dengan data yang berkaitan dengan
pemberian token akses.
oauthv2accesstoken.{policy-name}.access_token oauthv2accesstoken.{policy-name}.expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token_issued_at oauthv2accesstoken.{policy-name}.refresh_token_status
Contoh:
oauthv2accesstoken.GenerateAccessToken.access_token oauthv2accesstoken.GenerateAccessToken.expires_in oauthv2accesstoken.GenerateAccessToken.refresh_token oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at oauthv2accesstoken.GenerateAccessToken.refresh_token_status
Meminta token akses: jenis pemberian kredensial klien
Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kredensial klien. Untuk pengantar jenis pemberian OAuth 2.0, lihat Pengantar OAuth 2.0.
Contoh permintaan
Untuk mengetahui informasi tentang encoding header autentikasi dasar dalam panggilan berikut, lihat "Mengenkode kredensial autentikasi dasar".
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \ -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \ -d 'grant_type=client_credentials'
Parameter yang diperlukan
Secara default, parameter Grants_type yang diperlukan harus berupa x-www-form-urlencoded
dan
ditentukan dalam isi permintaan (seperti yang ditunjukkan di contoh di atas); namun, Anda dapat mengubah
default ini dengan mengonfigurasi elemen <GrantType>
dalam kebijakan OAuthV2 yang
disertakan ke endpoint /accesstoken
ini. Misalnya, Anda dapat memilih untuk meneruskan parameter dalam parameter kueri. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
- grant_type - Harus ditetapkan ke nilai
client_credentials
.
Parameter opsional
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
Anda harus meneruskan Client ID dan Rahasia Klien sebagai header Autentikasi Dasar (dienkode Base64) atau sebagai parameter formulir client_id
dan client_secret
. Anda mendapatkan nilai ini dari aplikasi developer terdaftar
yang terkait dengan permintaan. Lihat juga "Mengenkode kredensial autentikasi dasar".
Contoh endpoint
Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Tindakan ini akan menjalankan kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung jenis pemberian client_credentials.
... <Flow name="generate-access-token"> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition> </Flow> ...
Kebijakan contoh
Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima
jenis pemberian client_credentials
. Untuk mengetahui informasi tentang elemen konfigurasi opsional
yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<OAuthV2 name="GenerateAccessToken"> <Operation>GenerateAccessToken</Operation> <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes --> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan respons JSON. Perhatikan
bahwa dengan jenis pemberian client_credentials
, token refresh tidak didukung. Hanya
token akses yang dibuat. Contoh:
{ "issued_at": "1420260525643", "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b", "scope": "READ", "status": "approved", "api_product_list": "[PremiumWeatherAPI]", "expires_in": "1799", //--in seconds "developer.email": "tesla@weathersample.com", "organization_id": "0", "token_type": "BearerToken", "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT", "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav", "organization_name": "docs" }
Jika <GenerateResponse>
disetel ke salah (false), kebijakan tersebut tidak akan menampilkan
respons. Sebagai gantinya, formulir ini akan mengisi kumpulan variabel flow berikut dengan data yang berkaitan dengan
pemberian token akses.
oauthv2accesstoken.{policy-name}.access_token oauthv2accesstoken.{policy-name}.expires_in //--in seconds
Contoh:
oauthv2accesstoken.GenerateAccessToken.access_token oauthv2accesstoken.GenerateAccessToken.expires_in //--in seconds
Meminta token akses: jenis pemberian sandi
Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian kredensial sandi pemilik resource (sandi). Untuk pengantar jenis pemberian OAuth 2.0, lihat Pengantar OAuth 2.0.
Untuk mengetahui detail selengkapnya tentang jenis pemberian sandi, termasuk video berdurasi 4 menit yang menunjukkan cara menerapkannya, lihat Menerapkan jenis pemberian sandi.
Contoh permintaan
Untuk mengetahui informasi tentang encoding header autentikasi dasar dalam panggilan berikut, lihat "Mengenkode kredensial autentikasi dasar".
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \ -X POST https://docs-test.apigee.net/oauth/token \ -d 'grant_type=password&username=the-user-name&password=the-users-password'
Parameter yang diperlukan
Secara default, parameter ini harus bernilai x-www-form-urlencoded
dan ditentukan dalam
isi permintaan (seperti yang ditunjukkan pada contoh di atas); namun, Anda dapat mengubah default ini dengan
mengonfigurasi elemen <GrantType>
, <Username>
, dan
<Password>
dalam kebijakan OAuthV2 yang disertakan ke endpoint
/token
ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
Kredensial pengguna biasanya divalidasi berdasarkan penyimpanan kredensial menggunakan kebijakan LDAP atau JavaScript.
- grant_type - Harus ditetapkan ke nilai
password
. - nama pengguna - Nama pengguna pemilik resource.
- sandi - Sandi pemilik resource.
Parameter opsional
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
Anda harus meneruskan Client ID dan Rahasia Klien sebagai header Autentikasi Dasar (dienkode Base64) atau sebagai parameter formulir client_id
dan client_secret
. Anda mendapatkan nilai ini dari aplikasi developer terdaftar
yang terkait dengan permintaan. Lihat juga "Mengenkode kredensial autentikasi dasar".
Contoh endpoint
Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Tindakan ini akan menjalankan kebijakan GenerateAccessToken, yang harus dikonfigurasi untuk mendukung jenis pemberian sandi.
... <Flow name="generate-access-token"> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition> </Flow> ...
Kebijakan contoh
Ini adalah kebijakan GenerateAccessToken dasar yang dikonfigurasi untuk menerima jenis pemberian sandi. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<OAuthV2 name="GenerateAccessToken"> <Operation>GenerateAccessToken</Operation> <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes --> <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours --> <SupportedGrantTypes> <GrantType>password</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan respons JSON. Perhatikan bahwa dengan jenis pemberian sandi, token akses dan token refresh akan dibuat. Contoh:
{ "issued_at": "1420258685042", "scope": "READ", "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b", "refresh_token_issued_at": "1420258685042", "status": "approved", "refresh_token_status": "approved", "api_product_list": "[PremiumWeatherAPI]", "expires_in": "1799", //--in seconds "developer.email": "tesla@weathersample.com", "organization_id": "0", "token_type": "BearerToken", "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq", "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT", "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6", "organization_name": "docs", "refresh_token_expires_in": "28799", //--in seconds "refresh_count": "0" }
Jika <GenerateResponse>
disetel ke salah (false), kebijakan tersebut tidak akan menampilkan
respons. Sebagai gantinya, formulir ini akan mengisi kumpulan variabel flow berikut dengan data yang berkaitan dengan
pemberian token akses.
oauthv2accesstoken.{policy-name}.access_token oauthv2accesstoken.{policy-name}.expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token_issued_at oauthv2accesstoken.{policy-name}.refresh_token_status
Contoh:
oauthv2accesstoken.GenerateAccessToken.access_token oauthv2accesstoken.GenerateAccessToken.expires_in oauthv2accesstoken.GenerateAccessToken.refresh_token oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at oauthv2accesstoken.GenerateAccessToken.refresh_token_status
Meminta token akses: jenis pemberian implisit
Bagian ini menjelaskan cara meminta token akses menggunakan alur jenis pemberian implisit. Untuk pengantar tentang jenis pemberian OAuth 2.0, lihat Pengantar OAuth 2.0.
Contoh permintaan
$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \ 'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'
Parameter yang diperlukan
Secara default, parameter ini harus berupa parameter kueri (seperti yang ditunjukkan dalam contoh di atas); namun, default ini dapat diubah dengan mengonfigurasi elemen <ResponseType>
, <ClientId>
, dan <RedirectUri>
dalam kebijakan OAuthV2 yang disertakan ke endpoint /token
ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
Kredensial pengguna biasanya divalidasi dengan penyimpanan kredensial menggunakan info layanan LDAP atau kebijakan JavaScript.
- response_type - Harus ditetapkan ke nilai
token
. - client_id - Client ID dari aplikasi developer yang terdaftar.
- redirect_uri - Parameter ini wajib jika URI Callback tidak disediakan saat aplikasi developer klien terdaftar. Jika URL Callback diberikan saat pendaftaran klien, URL tersebut akan dibandingkan dengan nilai ini dan harus sama persis.
Parameter opsional
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
Pemberian implisit tidak memerlukan autentikasi dasar. Anda harus meneruskan client ID sebagai parameter permintaan, seperti yang dijelaskan di sini.
Contoh endpoint
Berikut adalah contoh konfigurasi endpoint untuk membuat token akses. Tindakan ini akan menjalankan kebijakan GenerateAccessTokenImplicitGrant.
... <Flow name="generate-access-token-implicit"> <Request> <Step> <Name>GenerateAccessTokenImplicitGrant</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition> </Flow> ...
Kebijakan contoh
Ini adalah kebijakan GenerateAccessTokenImplicitGrant dasar yang memproses permintaan token untuk alur jenis pemberian implisit. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <OAuthV2 name="GenerateAccessTokenImplicit"> <DisplayName>GenerateAccessTokenImplicit</DisplayName> <Operation>GenerateAccessTokenImplicitGrant</Operation> <GenerateResponse enabled="true"/> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan pengalihan Lokasi 302
di header respons. Pengalihan mengarah ke URL yang ditentukan dalam parameter redirect_uri
dan ditambahkan dengan token akses dan waktu habis masa berlaku token. Perhatikan bahwa jenis pemberian implisit tidak mendukung token refresh. Contoh:
https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5
Jika <GenerateResponse>
disetel ke salah (false), kebijakan tersebut tidak akan menampilkan
respons. Sebagai gantinya, formulir ini akan mengisi kumpulan variabel flow berikut dengan data yang berkaitan dengan
pemberian token akses.
oauthv2accesstoken.{policy-name}.access_token oauthv2accesstoken.{policy-name}.expires_in //--in seconds
Contoh:
oauthv2accesstoken.GenerateAccessToken.access_token oauthv2accesstoken.GenerateAccessToken.expires_in //--in seconds
Meminta kode otorisasi
Jika menggunakan alur jenis pemberian kode otorisasi, Anda perlu mendapatkan kode otorisasi sebelum dapat meminta token akses.
Contoh permintaan
$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \ 'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'
tempat kebijakan GenerateAuthorizationCode OAuthV2 dilampirkan di endpoint proxy /oauth/authorize
(lihat contoh endpoint di bawah).
Parameter yang diperlukan
Secara default, parameter ini harus berupa parameter kueri (seperti yang ditunjukkan dalam contoh di atas); namun, default ini dapat diubah dengan mengonfigurasi elemen <ResponseType>
, <ClientId>
, dan <RedirectUri>
dalam kebijakan OAuthV2 yang disertakan ke endpoint /authorize
ini. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
- response_type - Harus ditetapkan ke nilai
code
. - client_id - Client ID dari aplikasi developer yang terdaftar.
Parameter opsional
- redirect_uri - Jika URI Callback lengkap (bukan sebagian) ditentukan dalam aplikasi klien yang terdaftar, parameter ini bersifat opsional; jika tidak, parameter ini bersifat wajib. Callback adalah URL tempat Edge mengirimkan kode autentikasi yang baru dibuat. Lihat juga Mendaftarkan aplikasi dan mengelola kunci API.
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
Tidak memerlukan autentikasi dasar, tetapi client ID aplikasi klien yang terdaftar harus dimasukkan dalam permintaan.
Contoh endpoint
Berikut adalah contoh konfigurasi endpoint untuk membuat kode otorisasi:
<OAuthV2 name="GenerateAuthorizationCode"> <Operation>GenerateAuthorizationCode</Operation> <!-- ExpiresIn, in milliseconds. The ref is optional. The explicitly specified value is the default, when the variable reference cannot be resolved. 60000 = 1 minute 120000 = 2 minutes --> <ExpiresIn>60000</ExpiresIn> <GenerateResponse enabled="true"/> </OAuthV2>
Kebijakan contoh
Ini adalah kebijakan GenerateAuthorizationCode dasar. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<OAuthV2 name="GenerateAuthorizationCode"> <Operation>GenerateAuthorizationCode</Operation> <GenerateResponse enabled="true"/> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan parameter kueri ?code
ke lokasi redirect_uri
(URI Callback) dengan kode otorisasi yang dilampirkan. Pesan ini dikirim melalui pengalihan browser 302 dengan URL di header Location pada
respons. Contoh: ?code=123456
.
Jika <GenerateResponse>
disetel ke false
, kebijakan tidak akan
menampilkan respons. Sebagai gantinya, sistem ini akan mengisi kumpulan variabel flow berikut dengan data yang berkaitan
dengan kode otorisasi.
oauthv2authcode.{policy-name}.code oauthv2authcode.{policy-name}.scope oauthv2authcode.{policy-name}.redirect_uri oauthv2authcode.{policy-name}.client_id
Contoh:
oauthv2authcode.GenerateAuthorizationCode.code oauthv2authcode.GenerateAuthorizationCode.scope oauthv2authcode.GenerateAuthorizationCode.redirect_uri oauthv2authcode.GenerateAuthorizationCode.client_id
Memperbarui token akses
Token refresh adalah kredensial yang Anda gunakan untuk mendapatkan token akses, biasanya setelah token akses berakhir atau menjadi tidak valid. Token refresh ditampilkan dalam respons saat Anda menerima token akses.
Untuk meminta token akses baru menggunakan token refresh:
Contoh permintaan
Untuk mengetahui informasi tentang encoding header autentikasi dasar dalam panggilan berikut, lihat "Mengenkode kredensial autentikasi dasar".
$ curl -X POST \ -H "Content-type: application/x-www-form-urlencoded" \ -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \ https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \ -d 'grant_type=refresh_token&refresh_token=my-refresh-token'
Parameter yang diperlukan
- grant_type - Harus ditetapkan ke nilai
refresh_token
. - refresh_token - Token refresh yang terkait dengan token akses yang ingin diperpanjang.
Secara default, kebijakan akan mencarinya sebagai parameter x-www-form-urlencoded
yang ditentukan dalam isi permintaan, seperti yang ditunjukkan dalam contoh di atas. Guna mengonfigurasi lokasi alternatif untuk input ini, Anda dapat menggunakan elemen <GrantType>
dan <RefreshToken>
dalam kebijakan OAuthV2. Untuk mengetahui detailnya, lihat kebijakan OAuthV2.
Parameter opsional
- state - String yang akan dikirim kembali bersama respons. Biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs.
- scope - Memungkinkan Anda memfilter daftar produk API yang dapat digunakan dengan token yang dibuat. Untuk informasi mendetail tentang cakupan, lihat Bekerja dengan cakupan OAuth2.
Autentikasi
- client_id
- client_secret
Anda harus meneruskan Client ID dan Rahasia Klien sebagai header Autentikasi Dasar (dienkode Base64) atau sebagai parameter formulir client_id
dan client_secret
. Lihat
juga "Mengenkode kredensial autentikasi dasar".
Saat memuat ulang token akses, tidak ada autentikasi ulang pengguna.
Berikut adalah contoh konfigurasi endpoint untuk membuat token akses menggunakan token refresh. Tindakan ini akan menjalankan kebijakan RefreshAccessToken.
... <Flow name="generate-refresh-token"> <Request> <Step> <Name>RefreshAccessToken</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition> </Flow> ...
Kebijakan contoh
Ini adalah kebijakan RefreshAccessToken dasar yang dikonfigurasi untuk menerima
jenis pemberian refresh_token
. Untuk mengetahui informasi tentang elemen konfigurasi opsional yang
dapat Anda konfigurasi dengan kebijakan ini, lihat kebijakan OAuthV2.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <OAuthV2 name="RefreshAccessToken"> <Operation>RefreshAccessToken</Operation> <GenerateResponse enabled="true"/> <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes --> <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours --> </OAuthV2>
Hasil
Dengan mengaktifkan <GenerateResponse>
, kebijakan akan menampilkan respons JSON yang berisi token akses baru. Jenis pemberian refresh_token
mendukung pembuatan akses dan token refresh baru. Contoh:
{ "issued_at": "1420301470489", "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b", "scope": "READ", "refresh_token_issued_at": "1420301470489", "status": "approved", "refresh_token_status": "approved", "api_product_list": "[PremiumWeatherAPI]", "expires_in": "1799", //--in seconds "developer.email": "tesla@weathersample.com", "token_type": "BearerToken", "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5", "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT", "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw", "organization_name": "docs", "refresh_token_expires_in": "28799", //--in seconds "refresh_count": "2" }
Anda harus mengetahui bahwa setelah token refresh baru dibuat, versi asli tidak lagi valid.
Respons di atas adalah yang Anda dapatkan jika <GenerateResponse>
ditetapkan ke benar (true).
Jika <GenerateResponse>
disetel ke salah (false), kebijakan tersebut tidak akan menampilkan respons.
Sebagai gantinya, formulir ini akan mengisi kumpulan variabel konteks (flow) berikut dengan data yang berkaitan dengan
pemberian token akses.
oauthv2accesstoken.{policy-name}.access_token oauthv2accesstoken.{policy-name}.expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds oauthv2accesstoken.{policy-name}.refresh_token_issued_at oauthv2accesstoken.{policy-name}.refresh_token_status
Contoh:
oauthv2accesstoken.RefreshAccessToken.access_token oauthv2accesstoken.RefreshAccessToken.expires_in oauthv2accesstoken.RefreshAccessToken.refresh_token oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at oauthv2accesstoken.RefreshAccessToken.refresh_token_status
Mengenkode kredensial autentikasi dasar
Saat Anda melakukan panggilan API untuk meminta token atau kode autentikasi, merupakan praktik yang baik, dan direkomendasikan oleh spesifikasi OAuth 2.0 untuk meneruskan nilai client_id dan client_secret sebagai header HTTP-Basic Authentication, seperti dijelaskan dalam IETF RFC 2617. Untuk melakukannya, Anda harus mengenkode hasil penggabungan dua nilai dengan base64 dengan titik dua yang memisahkannya.
Dalam kode semu:
result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))
Dalam contoh ini, ns4fQc14Zg4hKFCNaSzArVuwszX95X
adalah client_id dan ZIjFyTsNgQNyxI
adalah rahasia klien.
Apa pun bahasa pemrograman yang Anda gunakan untuk menghitung nilai berenkode base64, untuk kredensial klien yang diberikan, hasil berenkode base64 adalah: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==
Kemudian, Anda dapat membuat permintaan token sebagai berikut:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \ -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \ -d 'grant_type=client_credentials'
Utilitas curl
sebenarnya akan membuat header HTTP Basic untuk Anda, jika Anda menggunakan
opsi -u. Fungsi berikut setara dengan yang di atas:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \ -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \ -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \ -d 'grant_type=client_credentials'
Lingkungan pemrograman lain mungkin memiliki pintasan serupa yang secara otomatis menghasilkan header berenkode base64.
{i>Hashing token<i} dalam database
Untuk melindungi akses OAuth dan token refresh jika terjadi pelanggaran keamanan database, Anda dapat mengaktifkan hashing token otomatis di organisasi Edge. Saat fitur ini diaktifkan, Edge akan otomatis membuat versi hash dari akses OAuth yang baru dibuat dan token refresh menggunakan algoritma yang Anda tentukan. (Berikut informasi tentang cara melakukan hashing massal pada token yang sudah ada.) Token yang tidak di-hash digunakan dalam panggilan API, dan Edge memvalidasinya berdasarkan versi yang di-hash dalam database.
Properti tingkat organisasi berikut mengontrol hashing token OAuth.
features.isOAuthTokenHashingEnabled = true features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN
Jika Anda sudah memiliki token yang di-hash dan ingin mempertahankannya hingga habis masa berlakunya, tetapkan properti berikut di organisasi Anda, dengan algoritma hashing cocok dengan algoritma yang ada (misalnya SHA1, default Edge sebelumnya). Jika token tidak di-hash, gunakan PLAIN.
features.isOAuthTokenFallbackHashingEnabled = true features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN
Jika Anda adalah pelanggan cloud Edge, hubungi Dukungan Apigee Edge untuk menetapkan properti ini di organisasi Anda dan, jika ingin, melakukan hashing massal pada token yang ada.
Topik terkait
- Mengimplementasikan jenis pemberian kredensial klien
- Menerapkan jenis pemberian kode otorisasi
- Kursus online keamanan API (termasuk OAuth)
- Kebijakan OAuthV2 -- Memiliki banyak contoh yang menunjukkan cara membuat permintaan ke server otorisasi dan cara mengonfigurasi kebijakan OAuthV2.