Menggunakan token OAuth pihak ketiga

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

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

Dalam kasus biasa, Apigee akan membuat dan menyimpan token OAuth, lalu menampilkannya ke aplikasi yang memanggil. Aplikasi pemanggil kemudian menampilkan kembali token tersebut 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 dibuat di tempat lain, sambil mempertahankan bagian verifikasi token yang sama, seolah-olah token tersebut dibuat oleh Apigee.

Contoh

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

Apa ini?

Misalkan Anda telah memiliki sistem otorisasi, dan Anda ingin menggunakan nilai token atau kode yang dihasilkan oleh sistem tersebut, bukan nilai token atau kode OAuth2 yang dihasilkan oleh Apigee. Kemudian, Anda dapat membuat permintaan proxy API yang aman dengan token atau kode yang diganti, dan Apigee akan memvalidasinya seolah-olah token atau kode tersebut dibuat oleh Apigee.

Latar Belakang

Dalam kasus biasa, Apigee membuat token dengan menghasilkan string huruf dan angka acak. Apigee dikaitkan dengan token tersebut, data lain seperti waktu token dikeluarkan, masa berlaku, daftar Produk API yang valid untuk token tersebut, dan cakupan. Semua informasi ini dapat ditampilkan dalam respons yang dibuat secara otomatis 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 nilai token, Apigee mengambil metadata token untuk menentukan apakah token valid atau tidak.

Dengan mengikuti langkah-langkah yang dijelaskan di sini, Anda dapat mengonfigurasi Apigee untuk menyimpan token yang nilai access_token-nya dibuat oleh layanan eksternal. Misalnya, Anda memiliki sistem eksternal ke Apigee yang menghasilkan token dalam bentuk "TOKEN-<16 angka acak>" . 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 pembawa TOKEN-1092837373654221, dan Apigee akan dapat memvalidasinya. Anda dapat menerapkan pola impor serupa untuk kode otorisasi dan token refresh.

Membahas Validasi Kredensial Klien

Salah satu prasyarat untuk membuat token adalah memvalidasi klien yang meminta. Secara default, kebijakan OAuthV2/GenerateAccessToken di Apigee secara implisit memverifikasi kredensial klien. Biasanya dalam permintaan token OAuthV2, client_id dan client_secret diteruskan di header Authorization, yang dienkode melalui HTTP Basic Authorization (digabungkan dengan titik dua, lalu dienkode 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 oleh Apigee - dengan kata lain, ada Aplikasi Developer yang disimpan dalam Apigee yang berisi kredensial, yang sendiri berisi client_id dan client_secret yang diberikan.

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

Dengan cara apa pun, baik secara implisit maupun eksplisit, Anda harus memastikan bahwa Proxy API yang membuat token terlebih dahulu memvalidasi kredensial klien. Perlu diingat bahwa validasi klien tidak bergantung pada pembuatan token akses. Anda dapat mengonfigurasi Apigee untuk melakukan keduanya, atau melakukan salah satu, atau tidak melakukan 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 seluruhnya. 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 dibuat oleh Apigee atau dibuat oleh sistem eksternal lalu diimpor ke Apigee, harus dikaitkan dengan aplikasi klien - yang ditunjukkan oleh client_id. Jadi, meskipun dalam kasus kebijakan OAuthV2/GenerateAccessToken di Apigee tidak akan memvalidasi bahwa client_id dan client_secret cocok, kebijakan akan memvalidasi bahwa client_id valid, ada, dan tidak dicabut. Jadi, sebagai langkah penyiapan prasyarat, Anda mungkin harus mengimpor client_id melalui Apigee API administratif.

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.

Eksternal Validasi Kredensial Klien

  1. ServiceCallout untuk Memverifikasi kredensial klien masuk, dan mendapatkan token eksternal.
  2. ExtractVariables atau langkah JavaScript untuk mengekstrak token yang dibuat secara eksternal dari respons.
  3. AssignMessage untuk menetapkan variabel khusus yang sudah dikenal bernama oauth_external_authorization_status. Nilai harus benar (true) untuk menunjukkan bahwa kredensial klien valid.
  4. OAuthV2/GenerateAccessToken dengan elemen <ExternalAuthorization> yang ditetapkan ke true, dan setidaknya satu dari <ExternalAccessToken>, <ExternalRefreshToken>, atau <ExternalAuthorizationCode>.

Internal Validasi Kredensial Klien

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

Catatan tentang konfigurasi kebijakan dan alur

  • Jika Anda ingin menggunakan sistem eksternal untuk memvalidasi kredensial klien, Anda harus mengembangkan alur kebijakan yang melakukan apa 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 token akses.

  • Setelah ServiceCallout, proxy API perlu mem-parsing respons untuk mengekstrak status validitas, serta access_token yang dibuat secara eksternal dan mungkin refresh_token.

  • Dalam kebijakan OAuthV2/GenerateAccessToken, tetapkan elemen <StoreToken> ke true, dan tetapkan elemen <ExternalAuthorization> ke true atau false sebagaimana mestinya.

    Saat kebijakan OAuthV2/GenerateAccessToken dijalankan, kebijakan tersebut akan membaca variabel oauth_external_authorization_status. Jika variabel ditetapkan dan nilainya adalah true, maka Apigee tidak akan mencoba memvalidasi kredensial klien. Jika variabel tidak disetel atau nilainya bukan benar (true), Apigee akan mencoba memvalidasi kredensial klien.

  • Ada tiga elemen untuk kebijakan OAuthV2 yang memungkinkan Anda menentukan data eksternal yang akan diimpor: <ExternalAccessToken>, <ExternalRefreshToken>, dan <ExternalAuthorizationCode>. Setiap elemen ini menerima variabel alur. Kebijakan Apigee akan membaca variabel tersebut untuk menemukan token akses, token refresh, atau kode otorisasi yang dibuat secara eksternal. Anda yang harus menerapkan kebijakan dan logika untuk menempatkan token atau kode eksternal 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 memerlukan langkah sebelumnya yang menetapkan variabel tersebut.

  • Mengenai penyetelan variabel oauth_external_authorization_status, teknik umum untuk menyetel variabel ini adalah menggunakan kebijakan AssignMessage dengan elemen AssignVariable, 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 berada sebelum kebijakan OAuthV2 dengan Operation = GenerateAccessToken.

Contoh kebijakan OAuthV2

Kebijakan OAuthV2 berikut menghasilkan token akses dengan asumsi bahwa 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>

Secara teoretis, Anda dapat menerapkan pola ini dengan layanan otorisasi OAuth2 pihak ketiga mana pun.