Menggunakan Token OAuth Pihak Ketiga

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

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

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

Contoh

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

Apa ini?

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

Beberapa Latar Belakang

Dalam kasus biasa, Apigee Edge menghasilkan token dengan menghasilkan string huruf dan angka acak. Apigee Edge mengaitkan token tersebut, data lain seperti waktu token dikeluarkan, masa berlaku habis, daftar Produk API dengan token yang valid, 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": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Nilai atribut access_token pada dasarnya adalah kunci pencarian untuk data respons. Aplikasi dapat membuat permintaan ke proxy API yang dihosting di Edge, yang memiliki token pemilik zBC90HhCGmGlaMBWeZAai2s3za5j, dan Edge - dengan kebijakan OAuthV2 dengan Operation = VerifyAccessToken - akan mencari token, mengambil semua informasi, dan menggunakan informasi tersebut untuk menentukan apakah token tersebut valid atau tidak, untuk Proxy API yang diminta. Langkah ini disebut Validasi token. Semua informasi di atas membentuk token. Nilai access_token merupakan cara untuk mencari informasi tersebut.

Di sisi lain, dengan mengikuti langkah-langkah yang dijelaskan di sini, Anda dapat mengonfigurasi Edge untuk menyimpan token sehingga nilai access_token-nya dihasilkan oleh layanan eksternal. Semua {i>metadata<i} lainnya mungkin sama. Misalnya, Anda memiliki sistem di luar Apigee Edge yang menghasilkan token dengan bentuk "TOKEN-<16 random numbers>" . Dalam hal ini, metadata token lengkap yang disimpan oleh Apigee Edge mungkin:

{
  "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": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Dalam hal ini, aplikasi dapat membuat permintaan ke proxy API yang dihosting di Edge, yang membawa token pemilik TOKEN-1092837373654221, dan Edge - melalui kebijakan OAuthV2 dengan Operation = VerifyAccessToken - akan dapat memvalidasinya. Anda dapat menerapkan pola impor yang serupa ke kode otorisasi dan token refresh.

Mari Kita Bahas Validasi Kredensial Klien

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

Jika kredensial klien tidak divalidasi oleh Apigee Edge, Anda harus mendesain Proxy API, sebelum menghasilkan token, untuk memvalidasi klien secara eksplisit melalui beberapa cara lain. Sering kali ini 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 menghasilkan token terlebih dahulu memvalidasi kredensial klien. Perlu diingat bahwa memvalidasi klien independen dari pembuatan token akses. Anda dapat mengonfigurasi Apigee Edge untuk melakukan keduanya, atau melakukan salah satunya, atau tidak keduanya.

Jika Anda ingin kebijakan OAuthV2/GenerateAccessToken di Apigee Edge untuk memvalidasi kredensial klien terhadap penyimpanan Edge, setel 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 Edge mungkin tidak memvalidasi kredensial klien, client_id tetap harus diketahui dan dikelola oleh Apigee Edge. Setiap access_token di Apigee Edge, baik yang dihasilkan oleh Apigee Edge atau dihasilkan oleh sistem eksternal lalu diimpor ke Apigee Edge, harus dikaitkan dengan aplikasi klien - yang ditunjukkan oleh client_id. Jadi, meskipun kebijakan OAuthV2/GenerateAccessToken di Apigee Edge 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 Edge.

Alur Kebijakan untuk OAuth pihak ketiga di Apigee

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

Validasi Eksternal Kredensial Klien

  1. ServiceCallout untuk Memverifikasi kredensial klien yang masuk, dan memperoleh token eksternal.
  2. ExtractVariables atau langkah JavaScript untuk mengekstrak token yang dihasilkan secara eksternal dari respons.
  3. AssignMessage untuk menetapkan variabel terkenal khusus yang disebut oauth_external_authorization_status. Nilainya harus benar untuk menunjukkan bahwa kredensial klien valid.
  4. 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 alur dan konfigurasi kebijakan

  • Jika Anda ingin menggunakan sistem eksternal untuk memvalidasi kredensial klien, Anda dapat 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 juga token akses jika kredensial valid.

  • 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, lalu tetapkan elemen <ExternalAuthorization> ke true atau false yang sesuai.

    Saat dijalankan, kebijakan OAuthV2/GenerateAccessToken akan membaca variabel oauth_external_authorization_status. Jika variabel ditetapkan dan nilainya adalah true (benar), Apigee Edge tidak akan mencoba memvalidasi kredensial klien. Jika variabel tidak ditetapkan atau nilainya tidak benar, Apigee Edge 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 flow. Kebijakan Edge akan membaca variabel tersebut untuk menemukan token akses, token refresh, atau kode otorisasi yang dihasilkan secara eksternal. Andalah yang menentukan apakah akan menerapkan kebijakan dan logika untuk menempatkan token atau kode eksternal ke dalam variabel yang sesuai.

    Misalnya, konfigurasi berikut dalam kebijakan OAuthV2 memberi tahu Edge untuk mencari token dalam variabel konteks bernama external_token.

    <ExternalAccessToken>external_token</ExternalAccessToken>
    

    Anda juga harus memiliki langkah sebelumnya yang menetapkan variabel tersebut.

  • Terkait penetapan variabel oauth_external_authorization_status, teknik 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 berada sebelum kebijakan OAuthV2 dengan Operation = GenerateAccessToken.

Contoh kebijakan OAuthV2

Kebijakan OAuthV2 berikut menghasilkan token akses Apigee Edge mengingat bahwa Edge menemukan nilai token dalam variabel flow external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <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 teori, Anda dapat menerapkan pola ini dengan layanan otorisasi OAuth2 pihak ketiga mana pun.