Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan token OAuth pihak ketiga

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Dalam topik ini, kita akan membahas cara mengimpor token akses, token refresh, atau kode autentikasi yang dihasilkan secara eksternal ke dalam penyimpanan token Apigee. Anda dapat menggunakan teknik ini jika ingin mengonfigurasi Apigee untuk memvalidasi token yang dihasilkan di luar Apigee.

Dalam kasus biasa, Apigee akan membuat dan menyimpan token OAuth, serta menampilkannya ke aplikasi panggilan. Aplikasi yang memanggil kemudian menampilkan token tersebut kembali ke Apigee saat meminta layanan, dan Apigee - melalui kebijakan OAuthV2 dengan Operation = VerifyAccessToken - akan memverifikasi bahwa token tersebut valid. Topik ini menjelaskan cara mengonfigurasi Apigee untuk menyimpan token OAuth yang dihasilkan di tempat lain, sekaligus menjaga bagian verifikasi token tetap sama, seolah-olah token tersebut dibuat oleh Apigee.

Contoh

Jika Anda ingin melihat contoh kerja yang menggambarkan teknik yang dijelaskan dalam topik ini, lihat contoh Pengelolaan Token yang Didelegasikan Apigee.

Apa ini?

Misalnya Anda sudah memiliki sistem otorisasi, dan ingin menggunakan token atau nilai kode yang dihasilkan oleh sistem tersebut sebagai pengganti token OAuth2 atau nilai kode yang dihasilkan Apigee. Selanjutnya, Anda dapat membuat permintaan proxy API yang aman dengan token atau kode pengganti, dan Apigee akan memvalidasinya seolah-olah dibuat oleh Apigee.

Beberapa Latar Belakang

Pada kasus biasa, Apigee menghasilkan token dengan menghasilkan string huruf dan angka acak. Apigee berkaitan dengan token tersebut, data lain seperti waktu token dikeluarkan, masa habis berlaku, daftar Produk API yang valid untuk token, dan cakupannya. Semua informasi ini dapat ditampilkan dalam respons yang otomatis dibuat oleh kebijakan OAuthV2 yang dikonfigurasi dengan Operation = GenerateAccessToken. Responsnya akan terlihat seperti ini:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Nilai access_token digunakan oleh Apigee untuk mengambil metadata token. Misalnya, permintaan proxy API menyertakan token pembawa zBC90HhCGmGlaMBWeZAai2s3za5j. Dengan menggunakan nilai token, Apigee mengambil metadata token untuk menentukan apakah token tersebut valid atau tidak.

Dengan mengikuti langkah-langkah yang dijelaskan di sini, Anda dapat mengonfigurasi Apigee untuk menyimpan token yang nilai access_tokennya dihasilkan oleh layanan eksternal. Misalnya, Anda memiliki sistem di luar Apigee yang menghasilkan token dengan format "TOKEN-<16 random numbers>" . Dalam hal ini, metadata token lengkap yang disimpan oleh Apigee mungkin adalah:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Dalam hal ini, aplikasi dapat membuat permintaan ke proxy API, yang membawa token pemilik TOKEN-1092837373654221, dan Apigee akan dapat memvalidasinya. Anda dapat menerapkan pola impor yang serupa ke kode otorisasi dan token refresh.

Mari Kita bahas tentang Memvalidasi Kredensial Klien

Salah satu prasyarat untuk membuat token adalah memvalidasi klien yang meminta. Secara default, kebijakan OAuthV2/GenerateAccessToken di Apigee memverifikasi kredensial klien secara implisit. Biasanya dalam permintaan token OAuthV2, client_id dan client_secret diteruskan dalam header Otorisasi, yang dienkode melalui Otorisasi Dasar HTTP (digabungkan titik dua, lalu berenkode base64). Kebijakan OAuthV2/GenerateAccessToken di Apigee mendekode header tersebut dan mencari client_id, serta memverifikasi bahwa client_secret yang diteruskan valid untuk client_id tersebut. Cara ini berfungsi jika kredensial diketahui Apigee - dengan kata lain ada Aplikasi Developer yang tersimpan dalam Apigee yang berisi kredensial, yang berisi client_id dan client_secret yang diberikan.

Jika kredensial klien tidak akan divalidasi oleh Apigee, Anda harus mendesain Proxy API Anda, sebelum menghasilkan token, untuk memvalidasi klien secara eksplisit melalui beberapa cara lain. Sering kali hal ini dilakukan melalui kebijakan ServiceCallout yang terhubung ke endpoint jarak jauh di jaringan Anda.

Dengan satu atau cara lainnya, baik secara implisit maupun eksplisit, Anda harus memastikan bahwa Proxy API yang menghasilkan token akan memvalidasi kredensial klien terlebih dahulu. Perlu diingat bahwa memvalidasi klien tidak bergantung pada pembuatan token akses. Anda dapat mengonfigurasi Apigee untuk melakukan keduanya, melakukan salah satunya, atau tidak keduanya.

Jika Anda ingin kebijakan OAuthV2/GenerateAccessToken di Apigee memvalidasi kredensial klien terhadap penyimpanan Apigee, tetapkan elemen <ExternalAuthorization> ke false di dalam konfigurasi kebijakan, atau hapus sepenuhnya. Jika Anda ingin menggunakan layanan otorisasi eksternal untuk memvalidasi kredensial klien secara eksplisit, tetapkan <ExternalAuthorization> ke true.

Meskipun Apigee mungkin tidak memvalidasi kredensial klien, client_id tetap harus diketahui dan dikelola oleh Apigee. Setiap access_token di Apigee, baik yang dihasilkan oleh Apigee atau dihasilkan oleh sistem eksternal, lalu diimpor ke Apigee, harus dikaitkan dengan aplikasi klien - ditunjukkan oleh client_id. Jadi, meskipun kebijakan OAuthV2/GenerateAccessToken di Apigee tidak akan memvalidasi bahwa client_id dan client_secret cocok, kebijakan tersebut akan memvalidasi bahwa client_id valid, ada, dan tidak dicabut. Jadi sebagai langkah penyiapan prasyarat, Anda mungkin harus mengimpor client_id melalui API administratif Apigee.

Alur Kebijakan untuk OAuth pihak ketiga di Apigee

Untuk menggunakan token dari sistem OAuth pihak ketiga di Apigee, alur untuk membuat token akses harus mengikuti salah satu pola berikut.

Validasi Eksternal Kredensial Klien

ServiceCallout untuk Memverifikasi kredensial klien yang masuk, dan mendapatkan token eksternal.
ExtractVariables atau langkah JavaScript untuk mengekstrak token yang dihasilkan secara eksternal dari respons.
AssignMessage untuk menetapkan variabel terkenal khusus yang disebut oauth_external_authorization_status. Nilai ini harus benar untuk menunjukkan bahwa kredensial klien valid.
OAuthV2/GenerateAccessToken dengan elemen <ExternalAuthorization> yang ditetapkan ke true, dan setidaknya salah satu dari <ExternalAccessToken>, <ExternalRefreshToken>, atau <ExternalAuthorizationCode>.

Validasi Internal Kredensial Klien

ServiceCallout untuk memperoleh token eksternal.
ExtractVariables atau langkah JavaScript untuk mengekstrak token yang dihasilkan secara eksternal dari respons.
OAuthV2/GenerateAccessToken dengan elemen <ExternalAuthorization> yang ditetapkan ke false, dan setidaknya salah satu dari <ExternalAccessToken>, <ExternalRefreshToken>, atau <ExternalAuthorizationCode>.

Catatan tentang konfigurasi alur dan kebijakan

Jika Anda ingin menggunakan sistem eksternal untuk memvalidasi kredensial klien, Anda dapat mengembangkan alur kebijakan yang melakukan fungsi yang diperlukan. Biasanya Anda akan menggunakan kebijakan ServiceCallout untuk mengirim kredensial yang dikenali secara eksternal ke layanan autentikasi eksternal. Layanan autentikasi eksternal biasanya akan menampilkan respons dan, jika kredensial valid, juga akan menampilkan token akses.
Setelah ServiceCallout, proxy API perlu mengurai respons untuk mengekstrak status validitas, access_token yang dihasilkan secara eksternal, dan mungkin refresh_token.
Pada kebijakan OAuthV2/GenerateAccessToken, tetapkan elemen <StoreToken> ke true, dan tetapkan elemen <ExternalAuthorization> ke true atau false yang sesuai.

Saat kebijakan OAuthV2/GenerateAccessToken dijalankan, kebijakan akan membaca variabel oauth_external_authorization_status. Jika variabel ditetapkan dan nilainya adalah true, Apigee tidak akan mencoba memvalidasi kredensial klien. Jika variabel tidak ditetapkan atau nilainya tidak benar, Apigee akan mencoba memvalidasi kredensial klien.
Terdapat tiga elemen untuk kebijakan OAuthV2 yang memungkinkan Anda menentukan data eksternal yang akan diimpor: <ExternalAccessToken>, <ExternalRefreshToken>, dan <ExternalAuthorizationCode>. Setiap elemen ini menerima variabel flow. Kebijakan Apigee akan membaca variabel tersebut untuk menemukan token akses, token refresh, atau kode otorisasi yang dihasilkan secara eksternal. Andalah yang harus menerapkan kebijakan dan logika untuk menempatkan token atau kode eksternal di dalam variabel yang sesuai.

Misalnya, konfigurasi berikut dalam kebijakan OAuthV2 memberi tahu Apigee untuk mencari token dalam variabel konteks bernama external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
Anda juga harus memiliki langkah sebelumnya yang menetapkan variabel tersebut.

Terkait setelan variabel oauth_external_authorization_status, teknik yang umum untuk menetapkan variabel ini adalah menggunakan kebijakanAssignMessage dengan elemen TetapkanVariable, seperti ini:

<AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Ingat, kebijakan ini harus berlaku sebelum kebijakan OAuthV2 dengan Operation = GenerateAccessToken.

Contoh kebijakan OAuthV2

Kebijakan OAuthV2 berikut menghasilkan token akses, mengingat Apigee menemukan nilai token dalam variabel alur external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

Biasanya, dengan jenis pemberian kredensial klien, Anda harus memberikan header Autentikasi Dasar dengan Client ID dan Rahasia Klien yang dienkode. Namun, dalam kasus ini, Anda tidak perlu menyediakan header tersebut. Kebijakan ini masih mengharapkan client_id ada dalam permintaan, dan kebijakan akan memvalidasinya. Apigee mengharapkan client_id dikirim sebagai bagian dari data formulir permintaan, misalnya, dalam request.formparam.client_id.

Secara teori, Anda dapat menerapkan pola ini dengan layanan otorisasi OAuth2 pihak ketiga.